f41c22d0ac
- CLAUDE.md: add "Question the question" and "One clarifying question" rules to Tone and Interaction — XY problem detection, false premise checks, and explicit reframe pattern before answering - Add claude/ detail-file directory (topic docs referenced from CLAUDE.md) - Add ABOUT.md, FUTURE.md - Update memory/, scripts/, settings.yaml with accumulated session changes Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
38 lines
2.2 KiB
Markdown
38 lines
2.2 KiB
Markdown
# Spec-Driven Development
|
|
|
|
**Any coding project with multiple milestones MUST have specs before code.** Hard requirement, not a suggestion. Workflow: Plan → Spec → Test → Code.
|
|
|
|
At project start or when starting a new milestone, always read:
|
|
- `best-practices/spec-driven-development.md` — spec structure, requirement numbering, scenarios, maintenance
|
|
- `best-practices/test-driven-development.md` — edge case discovery, property-based testing, AI agent testing patterns
|
|
|
|
## Required artifacts
|
|
|
|
Every multi-milestone coding project must have:
|
|
|
|
1. **`SPEC.md`** — Index file at the project root. Lists all spec files with a "when to read" column. Same thin-index pattern as MEMORY.md.
|
|
2. **`spec/` directory** — One spec file per subsystem. Each spec follows: Overview, Responsibilities, Dependencies, Data Model, Requirements (numbered), Scenarios (given/when/then).
|
|
3. **Numbered requirements** — Each spec uses a prefix (e.g., `IG-1` for ingestion, `DB-1` for database). Requirements must be independently testable and unambiguous.
|
|
4. **Test files that reference spec IDs** — every test function name includes its requirement ID: `test_ig3_dedup_by_message_ts`.
|
|
|
|
## Workflow
|
|
|
|
1. **Plan** — architecture decisions, milestone breakdown, technology choices (PLAN.md)
|
|
2. **Spec** — detailed contracts, data models, interfaces, requirements, scenarios (spec/)
|
|
3. **Test** — write tests from the spec before code exists. They should all fail.
|
|
4. **Code** — implement until tests pass. Minimum code to satisfy the spec.
|
|
5. **Update** — if implementation reveals spec issues, update spec → test → code in that order.
|
|
|
|
## When to write specs
|
|
|
|
- **Before M1 implementation begins** — write specs for all subsystems in M1's scope
|
|
- **Before each subsequent milestone** — specs for new subsystems, updates to existing specs for changes
|
|
- **Spec changes and test changes ship in the same commit**
|
|
- **Code changes that affect interfaces require spec changes in the same commit**
|
|
|
|
## What does NOT need a spec
|
|
|
|
- Infrastructure-only projects (Helm values, Kustomize manifests, Ansible playbooks) — declarative, not behavioural
|
|
- Single-script utilities — a well-commented script with a test is sufficient
|
|
- Documentation-only changes
|