---
name: spec-driven-implementation
title: Spec-Driven Implementation
description: "Write the spec before you write the code. This prompt enforces a spec → plan → build → verify loop that prevents scope creep, architectural drift, and \"it works but not how we wanted\" outcomes. The spec is the contract between what you want and what gets built. Every implementation decision traces back to a spec requirement."
category: coding
tags:
  - specyfikacja
  - architektura
  - planowanie
  - implementacja
  - tdd
source: https://madejski.ai/promptoteka/spec-driven-implementation
locale: en
license: MIT
---

# 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

```markdown
## 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)