Add question-reframing guidance to CLAUDE.md; commit accumulated project files
- 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>
This commit is contained in:
37
claude/spec-driven-development.md
Normal file
37
claude/spec-driven-development.md
Normal file
@@ -0,0 +1,37 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user