Section 4
AI Understanding: Clarity Before Code
Ensure AI comprehensively understands a feature before coding — shape-spec, Clarification Gate, constitution.md, living docs, and Tier Two approval gates.
"What does the spec say should happen — not what does the code happen to do.
SDD Learning Path — 3D Journey
Drag to orbit · Click nodes to explore · Follow the path from shape-spec to verify
Core Topics
shape-spec before code
Understanding Requirements
AI must comprehensively understand a feature before coding. shape-spec forces structured conversation — with EARS patterns for precise acceptance criteria.
Zero ambiguity
Clarification Gate
Resolve every open item in requirements.md before advancing. Pass the Ready for Plan Checklist — measurable success, roles, errors, and constraints.
constitution.md
Consistency vs Flexibility
Balance organizational consistency with project-level flexibility. Articulate team rules in constitution.md — what is always true, what can vary.
Exact commands, living docs
Documentation Maintenance
Keep docs relevant and practical — pass the Minimal Living Docs Checklist before merge. Exact commands, not vague suggestions.
Human verification
Approval Gates (Tier Two)
Significant but not clearly wrong actions need human approval — schema changes, new dependencies, public API changes.
shape-spec Simulator
Structured conversation — answer each phase before coding.
What problem does this solve — for whom?
Approval Gates — Tier Quest
Choose: Proceed · Ask First · Block
Add zod as a new dependency for form validation
Minimal Living Docs Checklist
After implementation, living docs must reflect what shipped. Use this gate before merge — alongside the Ready for Plan Checklist you passed earlier.
Minimal "Living Docs" Checklist
requirements.md (or shaped spec) matches what you actually built.
plan.md / architecture notes describe the system as implemented.
tasks.md checkboxes done and traceable to requirements.
Tests, build, lint, or recorded acceptance proof — not “looks fine.”
Documentation Files
| File | Audience | Purpose |
|---|---|---|
| README.md | Human | Product overview — what this project is |
| requirements.md | Human + AI | Feature intent — our SPEC equivalent |
| constitution.md | Human + AI | Team rules — consistency vs flexibility |
| tasks.md | Human + AI | Atomic work units with verification |
| AGENTS.md | AI | Operational rules — commands, boundaries, structure |
Practical Takeaways
- 1shape-spec before code. Structured conversation prevents AI misassumptions.
- 2Write requirements with EARS patterns — predictable syntax AI and humans parse the same way.
- 3Clarification Gate: zero open items in requirements.md — decisions documented, clarity locked in.
- 4Ready for Plan Checklist: measurable success, explicit roles, errors, data lifecycle, and DO NOT constraints.
- 5constitution.md balances org consistency with project flexibility.
- 6Document exact commands — npm run build, not 'make sure it works.'
- 7Minimal Living Docs Checklist: spec, plan, tasks, and verification evidence before merge.
- 8Tier Two approval gates: dependencies, schema, public API — human verifies first.
- 9Living docs evolve with the project. If it is not in git, it does not exist.