Every repository under active development carries a normative SPEC.md.
Standard: https://github.com/PaulSnow/tracking_repo/blob/main/docs/standards/spec-driven-development.md
Reference implementation: adex documents/SPEC.md
Requirements:
SPEC.md in the repo's documentation directory (documents/ or docs/, whichever the repo uses; create docs/ if neither). Never at the repository root.
- Two sections:
- Architecture — what we are doing: purpose, surfaces, objects, invariants. Readable without the code.
- Specification — how it is implemented: layout, components, interfaces, data flows, deployment. Every architectural claim in section 1 traces to a mechanism in section 2.
CLAUDE.md opens with the normative hook:
- ALL work is done against the spec — read the relevant section first; a change that contradicts the spec means fixing the spec or the plan first.
- New work requires updating the spec — same MR/change set, not "later".
Acceptance:
Every repository under active development carries a normative
SPEC.md.Standard: https://github.com/PaulSnow/tracking_repo/blob/main/docs/standards/spec-driven-development.md
Reference implementation: adex
documents/SPEC.mdRequirements:
SPEC.mdin the repo's documentation directory (documents/ordocs/, whichever the repo uses; createdocs/if neither). Never at the repository root.CLAUDE.mdopens with the normative hook:Acceptance:
SPEC.mdwritten (both sections), describing the system as it isCLAUDE.mdhook added