The most common failure mode today is handing an AI agent a one-liner and letting it write code straight away. You say "add search to the site," and it dumps 800 lines built on Algolia--but you run Postgres full-text search. You say "make the dashboard faster," and it bolts on a cache layer when the real bottleneck is the first-paint query. The requirement gets misread, and no matter how clean the code is, it has to be torn down and redone. The root cause isn't a dumb agent; it's that three questions never got answered before anyone touched a keyboard: what are we building, how will we build it, and how do we know it's done.
Spec-driven development is the engineering discipline that fixes this: before writing a single line of code, you write a spec--a specification that states the problem, the goal, the boundaries, and the acceptance criteria--and then AI or human implements against it step by step. This isn't new; it's the "write the spec before the code" practice validated repeatedly at GitHub, Google, and elsewhere. This SOP walks through the full flow: write the spec, confirm it in chunks, generate an implementation plan, break it into tasks, implement and verify task by task, and close out by validating against the spec. Each step comes with a reusable template and example, followed by a pitfall log and FAQ.
1. The Core: Write the Spec Before Code, Four Gated Phases
The skeleton of spec-driven development is four phases, each gated by a human review. You don't advance to the next phase until the current one is validated.
SPECIFY ──> PLAN ──> TASKS ──> IMPLEMENT
│ │ │ │
▼ ▼ ▼ ▼
Human Human Human Human
reviews reviews reviews reviews- SPECIFY: Turn the vague idea into a structured spec--problem, goal, boundaries, acceptance criteria.
- PLAN: Derive a technical implementation plan from the spec--components, dependencies, ordering.
- TASKS: Break the plan into tasks completable in a single focused session, each with acceptance criteria and a verification step.
- IMPLEMENT: Execute tasks one at a time, verifying each as you go.
Why four gates instead of one? Because requirement misunderstandings are cheapest to fix early--rewriting one line in the spec is two orders of magnitude cheaper than rewriting finished code. Each gate forces a human to look, shrinking the window where the agent freelances.
2. Step One: Write the Spec
A spec is not a manual; it's a tool that forces you to think clearly before coding. A proper spec covers at least five areas: problem statement, user stories, scope boundaries, non-goals, and acceptance criteria.
Surface assumptions first. Before any spec prose, put the things you're silently assuming on the table:
ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Auth uses session cookies (not JWT)
3. The database is PostgreSQL (based on the existing Prisma schema)
4. Modern browsers only (no IE11)
-> Correct me now or I'll proceed with these.Why does this matter? Because assumptions are the most dangerous form of misunderstanding--they silently fill in the gaps in a requirement and only surface after the code is written. Stating them out loud gives "I guessed you wanted X" a chance to be rejected on the spot.
Spec template. Below is a ready-to-use template, illustrated with "add full-text search to a content site":
# Spec: On-site Full-Text Search
## Problem Statement
Users can only browse articles by category and tag today; they can't find
"that RAG evaluation piece from six months ago." No on-site search means
high bounce rate and poor long-tail reach.
## User Stories
- As a reader, I want to type a keyword and get relevant articles ranked by relevance
- As an editor, I want to see top search terms to learn what readers look for
## In Scope (what we build)
- Full-text search over published articles' title, summary, and body
- Chinese tokenization
- Results ranked by relevance with matched terms highlighted
- Recommended articles shown when search returns nothing
## Non-Goals (explicitly not building)
- No personalized ranking
- No cross-site search
- No image/video content search
- No real-time indexing (minute-level latency is acceptable)
## Acceptance Criteria
- Searching "RAG evaluation" returns relevant articles, top hit is on-topic
- Chinese tokenization is correct ("评估" is not split into "评" and "估")
- Search response P95 < 300ms
- Empty results show recommendations, not a blank page
- Search box is usable on mobileNotice the "Non-Goals" section--it's as important as "In Scope." Its job is to draw a red line for the agent: these things are explicitly out, don't freelance them in. Many agent meltdowns come not from missing something but from bolting on a pile of features you never asked for.
Reframe vague requirements into testable criteria. When you get "make the dashboard faster," don't start coding--translate it into concrete, testable conditions first:
REQUIREMENT: "Make the dashboard faster"
REFRAMED AS ACCEPTANCE CRITERIA:
- Dashboard LCP < 2.5s on a 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
-> Are these the right targets?This lets you iterate toward a clear goal instead of guessing what "faster" means.
3. Step Two: Confirm in Chunks
When the spec is drafted, don't dump it on a human for one-shot sign-off. A spec covering five sections carries a lot of information; read in one pass, it's easy to gloss over the boundaries and non-goals that actually matter. The right move is to confirm it section by section:
1. Confirm "Problem Statement + User Stories" -- align on "what problem are we solving"
2. Then confirm "Scope + Non-Goals" -- align on "what we do and don't do"
3. Finally confirm "Acceptance Criteria" -- align on "how do we know it's done"Confirm each chunk before moving to the next. Why is this better than one big sign-off? It traps misunderstandings in the smallest possible scope--if the problem statement itself is misread, no amount of detail downstream will save you. Chunked confirmation adds a second gate inside the spec.
In practice, you can have the agent stop after writing each chunk and ask "is this right? anything to add?" before drafting the next. This feedback loop is far tighter--and cheaper to correct--than having the agent write the entire spec and only then asking you to review it.
4. Step Three: Generate the Implementation Plan
With the spec locked, derive a technical plan from it. The plan answers four questions:
- What are the major components, and what depends on what (e.g., indexing service, search API, front-end search box, results page)
- Implementation order (what must be built first--you can't test the search API before an index exists)
- What can run in parallel vs. what must be sequential
- Verification checkpoints between phases
The plan should be something a human can read and say "yes, that's the right approach" or "no, change X." It's not code--don't write implementation details at this step.
For the search spec above, the plan looks roughly like this:
Plan: On-site Full-Text Search
Components:
- Indexing service: reads published articles, builds a full-text index
- Search API: takes front-end queries, hits the index, returns results
- Front-end search box + results page: input, display, highlight
Dependencies and order:
1. Indexing service first (the API depends on an index existing)
2. Search API next (the front-end depends on the API)
3. Front-end last (consumes the API)
Parallelism:
- Indexing service and front-end search box UI can run in parallel (UI mocks data initially)
Verification checkpoints:
- After indexing: manually query a known article, confirm it's findable
- After API: curl a search, get JSON back
- End-to-end: type in the front-end, see highlighted results5. Step Four: Break Into Tasks
Break the plan into tasks small enough to finish in a single focused session (usually an hour or two). Three hard rules for task breakdown:
- Each task has explicit acceptance criteria (what must be true when it's done)
- Each task has a verification step (how to confirm it's done--test command, build, manual check)
- No single task touches more than about 5 files; if it does, it's too big
Task template:
- [ ] Task: Build the article indexing service
- Acceptance: Published articles' title, summary, and body are indexed; Chinese tokenization is correct
- Verify: Query "RAG evaluation," confirm a hit; "评估" is not split
- Files: src/lib/search/indexer.ts, src/lib/search/indexer.test.ts
- [ ] Task: Implement the search API endpoint
- Acceptance: GET /api/search?q= returns JSON ranked by relevance
- Verify: curl localhost:3000/api/search?q=RAG returns a non-empty array
- Files: src/app/api/search/route.ts, src/app/api/search/route.test.ts
- [ ] Task: Front-end search box + results page
- Acceptance: Typing a keyword shows results with highlighted matches; mobile-usable
- Verify: Manual browser check + mobile viewport check
- Files: src/components/search-box.tsx, src/app/search/page.tsxTasks are ordered by dependency, not by perceived importance. The "Files" field is decided up front--it constrains the agent's blast radius. It can only touch these files; it can't opportunistically refactor half the repo.
6. Step Five: Implement and Verify
Execute tasks one at a time and verify each immediately--don't batch up a wave of verifications. This is where test-driven development (TDD) fits naturally: write the test that defines the expected behavior first, then write the implementation to make it pass. TDD and spec-driven development are a natural fit--the acceptance criteria in the spec translate directly into test cases.
Task execution loop:
1. Load only the spec section relevant to this task (don't flood the agent with the whole spec)
2. Write the failing test (red)
3. Write the implementation until the test passes (green)
4. Run the full test suite + build to confirm nothing else broke
5. Mark the task done, move to the nextKey detail: load the spec on demand. Stuffing a large spec into the agent's context at once means details start dropping out as the context grows. Each task only needs the slice of the spec that pertains to it--load that slice, not the whole document.
If implementation surfaces a gap or a new decision (say, the data model needs to change), the rule is: update the spec first, then the code--don't silently patch the code and leave the spec to rot. The spec is a living document, not an artifact frozen at write time.
7. Step Six: Validate Against the Spec and Close Out
All tasks done doesn't mean the feature is done. The final step is to walk the spec's acceptance criteria and check each one:
Acceptance check (against the spec):
- [ ] Searching "RAG evaluation" returns relevant articles, top hit on-topic -- pass
- [ ] Chinese tokenization correct -- pass
- [ ] Search response P95 < 300ms -- measured 180ms, pass
- [ ] Empty results show recommendations -- pass
- [ ] Mobile-usable -- passAny criterion that fails means "not done," not "mostly done." The value here is turning "I think it's done" into "the acceptance criteria say it's done"--the latter is falsifiable, the former isn't.
Two small wrap-up tasks: commit the spec into version control (the spec lives alongside the code, not on a separate doc site) and link back to the relevant spec section in each PR. Three months later, whoever picks this up can follow the spec to understand why it was designed this way, instead of reverse-engineering intent from the code.
8. Tools: spec-kit and the /spec Agent Skill
You can run this flow without any tooling, but scaffolding saves real time.
github/spec-kit is GitHub's official open-source spec-generation scaffold. It bakes the SPECIFY -> PLAN -> TASKS -> IMPLEMENT gated workflow into runnable commands: you hand it a vague idea, and it walks you through generating the spec, the plan, and the task list section by section, stopping for human confirmation at each step. If you want to understand what spec-kit itself is and how to install it, the companion spec-kit-resource article on this site covers exactly that. (The two are a pair: that one explains "what it is," this one explains "how to use it.")
The in-repo /spec agent skill. If you work in a tool that supports agent skills, like Claude Code, this repo ships an inlined /spec skill--a localized implementation of the same spec-driven methodology. Trigger it and it runs the four phases (SPECIFY -> PLAN -> TASKS -> IMPLEMENT), pausing for your review at the end of each. For day-to-day project intake and new features, just invoke /spec; no extra install needed.
The relationship: spec-kit is the general-purpose scaffold (works on any project); /spec is the same methodology tailored to this repo's workflow. The methodology is identical--pick whichever fits your setup.
9. Pitfall Log
Pitfall 1: The spec is too coarse, the agent freelances. The spec says only "add search," with no boundaries, no non-goals, no acceptance criteria. The agent defaults to bolting on Algolia integration, personalized ranking, and an analytics dashboard--when you wanted a Postgres full-text index. A spec's value lives in its detail; a coarse spec is no spec at all.
Pitfall 2: The spec is too detailed, it becomes code. The other extreme: the spec spells out function signatures, loop logic, and variable names. That's not a spec; that's code written in prose. The spec should stop at "what to build and to what bar," and leave "how" to the plan and the code. Rule of thumb: if the spec contains concrete implementation code, it has crossed the line.
Pitfall 3: No acceptance validation. Tasks get marked done and shipped without anyone checking the acceptance criteria. The result: search works but takes 3 seconds, Chinese tokenization is broken, the mobile button is squished--the criteria were written for nothing. Acceptance isn't a formality; it's the closing loop of the spec. Skip it and everything upstream was wasted.
Pitfall 4: The spec isn't updated and turns into a zombie doc. Mid-implementation the approach changes (Algolia swapped for Postgres full-text), the code is updated but the spec isn't. Three months later a newcomer reads the spec, finds it doesn't match the code, and the spec now misleads instead of guides. The spec is a living document: when a decision changes, update the spec first, then the code.
Pitfall 5: Treating the spec as after-the-fact documentation. The code is written first, then a spec is backfilled for the archive. That's documentation, not specification. The spec's entire value is in forcing clarity before code--a backfilled spec loses that function and just rubber-stamps a fait accompli. Spec first, code second; the order is not negotiable.
10. FAQ
Q1: What's the difference between a spec and a PRD? A PRD (Product Requirements Document) is product- and business-facing: it covers market context, user personas, and business goals, runs long, and is written for people. A spec is engineering-facing: it covers the problem, boundaries, and acceptance criteria, runs short, and is written for AI or engineers to implement against. A feature might be plucked from a PRD and turned into a spec before anyone starts coding. In short: the PRD decides "do we build it and why"; the spec decides "what does done look like."
Q2: Do small projects need a spec? Judge by complexity, not size. A copy tweak or a typo fix doesn't need a spec. But if a requirement is even slightly ambiguous, touches multiple files, or involves an architectural decision, it's worth a spec--even if it's just two or three lines of acceptance criteria. The test: could this task blow up and need rework because it was misunderstood? If yes, write a spec. A 15-minute spec prevents hours of rework.
Q3: How does spec-kit fit into this flow?
spec-kit is the scaffold for exactly this flow--its commands map to the SPECIFY, PLAN, and TASKS phases, guiding you to generate the spec, plan, and task list section by section with confirmation at each step. You don't have to memorize templates; spec-kit bakes them in along with the gating logic. The companion spec-kit-resource article covers how to install and run it. If you'd rather not install an extra tool, this repo's /spec agent skill is a local implementation of the same methodology.
Q4: Should the AI or the human write the spec? Ideally, the AI drafts and the human reviews. The AI is good at rapidly producing a structured first draft against a template, but the business judgment, priority trade-offs, and non-goal scoping inside the requirement need a human to sign off. In practice: you give the AI a vague idea, it produces a spec draft and surfaces its assumptions, you confirm or correct it chunk by chunk, and it revises. "Thinking it through" is a joint effort--neither side throws it over the wall alone.
Q5: What does acceptance actually look like? Walk the spec's acceptance criteria one by one, marking each pass or fail with evidence (test result, measured metric, manual check record). Acceptance criteria must be testable--"search should be fast" can't be accepted; "P95 < 300ms" can. If you find a criterion that can't be objectively judged as pass or fail, that criterion was too vague and should have been reframed into a testable condition back in the SPECIFY phase.
References
- GitHub spec-kit repository - github/spec-kit (spec-driven development scaffold)
- The in-repo
/specagent skill (agent-skills/skills/spec-driven-development/SKILL.md), the localized implementation of the spec-driven development methodology; the four-phase SPECIFY -> PLAN -> TASKS -> IMPLEMENT workflow is defined there