Spec
A spec is a lightweight checkpoint that captures intent, constraints, and success criteria for a unit of work. It tells both humans and AI agents what needs to happen next—and why.
Why It Matters
- Acts as persistent memory across handoffs and AI sessions
- Forces clarity on the problem before implementation begins
- Enables autonomous work by outlining success criteria and guardrails
Core Anatomy
- Frontmatter — machine-readable metadata (status, priority, tags, dependencies)
- Overview — the problem, why it matters, and desired outcome
- Plan / Design — phases, trade-offs, or approach notes
- Validation — how to confirm the work is done
Keep the README under ≈2,000 tokens. When it grows beyond working-memory limits, split detail into sub-spec files and link them from the Plan section.
Sub-Specs: When Depth Matters
Sub-specs are additional Markdown files inside the spec directory (DESIGN.md, IMPLEMENTATION.md, TESTING.md, etc.). They preserve Context Economy by keeping the main README scannable while storing deep detail for specific audiences.
| Use a Sub-Spec When… | Examples |
|---|---|
| README would exceed ~2,000 tokens | Architecture diagrams, multi-phase rollout plans |
| Different audiences need different depth | Exec summary in README, implementation checklist elsewhere |
| You need dedicated artifacts | TESTING.md, migration runbooks, rollout checklists |
specs/082-web-sync/
README.md # Overview + decision context
DESIGN.md # Architecture diagrams and flows
IMPLEMENTATION.md # Phases or task list
TESTING.md # Validation details
Quick Example
# 042-api-rate-limiting
Implement token bucket rate limiting (100 req/min per API key)
to protect the API from abuse by 2% of heavy users.