spec-driven-development

Spec-Driven Development

Overview

Capture observable requirements before code. Reuse an existing spec or the user's explicit acceptance criteria; write only the missing design. Authorization follows OPS.md §1, not phase approval.

When to Use

• Starting a new project or feature
• Requirements are ambiguous or incomplete
• The change touches multiple files or modules
• You're about to make an architectural decision

When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous.

Workflow

Specify → plan → implement → verify. Review at meaningful uncertainty or integration boundaries, not as a mandatory human permission step after each phase. Continue already authorized implementation; plan-only requests end at the plan. Artifact size follows complexity, not a fixed template quota.

Phase 0: Scope Check (multi-capability only)

If a single requirement bundles several independently testable capabilities → propose a capability map first:

# Capability Map: [Initiative Name]
| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |

Build order: identity → billing, notifications.

Phase 1: Specify

Surface assumptions immediately:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL
→ Correct me now or I'll proceed with these.

Spec template:

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## Boundaries
- Always: [Verify affected behavior, follow project conventions, validate trust boundaries]
- Ask first: [Missing irreversible/outward authority or unavailable outcome-changing information]
- Never: [Expose secrets, mutate production data as a test, suppress a real failure]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]