106 lines
2.8 KiB
Markdown
106 lines
2.8 KiB
Markdown
# Spec-Driven Development Workflow
|
|
|
|
This workflow is **opt-in**. Use it when explicitly requested by saying "use spec-driven development" or "follow the spec workflow".
|
|
|
|
## Design Documents
|
|
|
|
The `specs/` folder contains design documents for features in development.
|
|
|
|
Each spec follows this structure:
|
|
|
|
```
|
|
specs/{feature}/
|
|
├── CLAUDE.md # Feature-specific instructions (read this first)
|
|
├── design.md # The specification
|
|
├── implementation.md # Current status and what's done
|
|
├── decisions.md # Why decisions were made
|
|
├── prompts.md # Reusable prompts
|
|
├── future-work.md # What's deferred
|
|
└── docs/ # Documentation with screenshots
|
|
```
|
|
|
|
**Workflow:**
|
|
|
|
1. Read the spec's `CLAUDE.md` for specific instructions
|
|
2. Read `design.md` to understand what we're building
|
|
3. Check `implementation.md` for current status
|
|
4. Find the relevant code in the codebase
|
|
5. Implement in small pieces, update `implementation.md` after each
|
|
|
|
---
|
|
|
|
## When Implementing Features (Spec Mode)
|
|
|
|
1. **Check for design doc** in `specs/` — if it exists, follow it
|
|
2. **If no spec exists** — ask if you should create one first
|
|
3. **Look at existing patterns** — find similar code and follow conventions
|
|
4. **Update implementation.md** — mark what's done after each piece
|
|
5. **Update decisions.md** — when choosing between approaches
|
|
|
|
---
|
|
|
|
## Creating a New Spec
|
|
|
|
When user asks to build a new feature:
|
|
|
|
1. Copy the template: `cp -r specs/_templates specs/{feature-name}`
|
|
2. Explore the codebase to understand existing patterns
|
|
3. Write `design.md` with technical spec
|
|
4. Write `CLAUDE.md` with feature-specific instructions
|
|
5. Initialize `implementation.md` with "not-started" status
|
|
6. Ask user to review before implementing
|
|
|
|
---
|
|
|
|
## Updating Spec Files
|
|
|
|
### implementation.md — After completing each piece:
|
|
|
|
```markdown
|
|
## Status: in-progress
|
|
|
|
## Completed
|
|
- [x] Database schema
|
|
- [x] Migration file
|
|
|
|
## In Progress
|
|
- tRPC endpoints
|
|
|
|
## Next Steps
|
|
1. UI components
|
|
2. Tests
|
|
|
|
## Session Notes
|
|
### 2024-01-15
|
|
- Done: Added schema, created migration
|
|
- Next: Implement tRPC router
|
|
```
|
|
|
|
### decisions.md — When choosing between approaches:
|
|
|
|
```markdown
|
|
## ADR-001: Use Separate Table for Custom Locations
|
|
|
|
### Context
|
|
Need to store user-defined locations.
|
|
|
|
### Options
|
|
1. JSON field — simpler, but harder to query
|
|
2. Separate table — more flexible, better indexing
|
|
|
|
### Decision
|
|
Separate table for better querying.
|
|
|
|
### Consequences
|
|
- Need migration
|
|
- Need new tRPC router
|
|
```
|
|
|
|
---
|
|
|
|
## Don't (When Using Spec-Driven Development)
|
|
|
|
- Don't implement features without checking for a design doc first
|
|
- Don't skip updating implementation.md after completing work
|
|
- Don't make architectural decisions without recording them in decisions.md
|