Spec-Driven Implementation

The Pattern

Write the specification BEFORE writing any code. The spec is the contract — it defines what "done" looks like before implementation begins.

Spec → Plan → Build → Verify → Ship

Why Spec First

Without a spec, AI tends to:

• Solve the wrong problem confidently
• Add features you didn't ask for
• Make architectural decisions without asking
• Produce code that "works" but doesn't fit the system

A spec prevents all of these because every implementation decision can be checked against a written requirement.

Spec Template

## Feature Spec: {name}

### Goal
{One sentence: what problem does this solve?}

### Requirements
1. {Requirement — testable, specific}
2. {Requirement — testable, specific}
3. {Requirement — testable, specific}

### Non-Requirements (explicitly out of scope)
- {Thing we're NOT building}
- {Edge case we're NOT handling}

### Constraints
- Must work with: {existing system/API/pattern}
- Must not break: {existing functionality}
- Performance: {latency/throughput/size requirements}
- Security: {auth, validation, data handling requirements}

### Interface Contract
{How will other code interact with this? API shape, props, events, etc.}

### Acceptance Criteria
- [ ] {Criterion 1 — verifiable}
- [ ] {Criterion 2 — verifiable}
- [ ] {Criterion 3 — verifiable}

Process

Phase 1: Write the Spec (10 min)

1. State the goal in one sentence
2. List requirements (testable, specific)
3. List non-requirements (what we're NOT doing)
4. Define constraints (what existing code must be respected)
5. Define the interface contract (how code will be called/used)
6. Write acceptance criteria (how we'll verify it works)

Phase 2: Plan (5 min)

1. Break the spec into implementation steps
2. Identify files to create/modify
3. Identify dependencies between steps
4. Estimate: is this 30 minutes or 3 hours?

Phase 3: Build (most of the time)

1. Implement step by step, following the plan
2. After each step, check: does this satisfy a spec requirement?
3. If you need to deviate from spec — STOP. Update spec first, then continue.
4. Commit after each completed requirement

Phase 4: Verify (10 min)

1. Walk through each acceptance criterion
2. Run tests
3. Check each spec requirement: is it implemented?
4. Check non-requirements: did we accidentally scope-creep?

Operating Rules

1. No code before spec approval — the spec must be reviewed before implementation starts
2. Spec changes require explicit acknowledgment — if requirements change during build, update the spec and note the change
3. Every PR references the spec — traceability from code to requirement
4. Non-requirements are sacred — resist the temptation to add "just one more thing"
5. Acceptance criteria are tests — write them as tests before writing implementation

When to Use

• Any feature that takes more than 30 minutes to implement
• Changes touching more than 3 files
• Any work involving API contracts or data model changes
• When multiple people (or sessions) will work on the same feature
• When the cost of "wrong" is high (auth, payments, data migration)

Anti-Patterns

• Spec so vague it could mean anything ("make it better")
• Spec so detailed it's already pseudocode (that's the plan, not the spec)
• Skipping non-requirements (scope creep enters through this door)
• Not updating the spec when requirements change mid-build
• Writing the spec after the code is done (that's documentation, not specification)