Spec-Driven Development
Spec-driven development means the agent implements against written acceptance criteria — not a vague "build auth" — and humans approve scope before code lands.
Last reviewed: June 2026
Tool Plan modes and spec file conventions vary. Works across Cursor, Claude Code, and Codex.
Spec template
## Goal
Add password reset via email link.
## Acceptance criteria
- [ ] POST /api/auth/reset-request sends email via existing mailer
- [ ] Token expires in 1 hour; single use
- [ ] GET /reset?token= validates and shows form
- [ ] Tests cover expired token and invalid token
## Files allowed
- src/app/api/auth/reset-request/route.ts (new)
- src/app/reset/page.tsx (new)
- src/lib/auth/reset-token.ts (new)
- src/lib/auth/reset-token.test.ts (new)
## Files forbidden
- src/lib/auth/session.ts (no changes)
- drizzle/migrations/** (human applies migration separately)
## Verification
npm test -- reset-token
npm run lint
Store specs in docs/specs/ or the issue/PR description — link from the agent prompt.
Plan → approve → implement
- Plan mode: Paste spec; ask for file list and approach only
- Human review: Reject scope creep; adjust allowed files
- Agent mode: "Implement the approved plan exactly"
- Verify: Run acceptance criteria checks; human diff review
Same loop as Agentic Workflows.
What makes specs agent-ready
| Good | Bad |
|---|---|
| Checkbox acceptance criteria | "Make it work" |
| Explicit allowed/forbidden paths | "Refactor as needed" |
| Named test command | "Add tests" |
Reference existing patterns (@src/lib/auth/login.ts) | No context |
| Edge cases listed | Assumed |
With project rules
AGENTS.md carries stack defaults. Specs carry task-specific boundaries. Do not duplicate stack versions in every spec.
Team workflow
| Role | Action |
|---|---|
| Author | Writes spec + opens PR draft |
| Agent | Implements against spec in branch |
| Reviewer | Checks diff vs spec, not vs vibe |
| QA | Runs acceptance criteria manually |
Link specs in Team AI Policy as required for ai-assisted PRs.