Spec-Driven Development: Production-Grade Methodology for Working with AI

TL;DR: Spec-Driven Development (SDD) is the opposite of "vibe coding". Instead of telling AI "build me an app", you first construct a specification (PRD, roadmap, acceptance criteria) and only then implement. This approach catches errors before the first line of code, lets multiple agents work in parallel, and produces software that is actually maintainable.

TL;DR

Spec-Driven Development (SDD) is the opposite of "vibe coding". Instead of telling AI "build me an app", you first build the specification (PRD, roadmap, tasks), review it as a team, and only then hand over the implementation. In practice it is the key methodology for keeping production quality in projects built with AI, avoiding "doom loops" and getting repeatable results.

Key concepts

The problem with vibe coding

"In Claude Code we can say 'build this for me and I want to succeed'. Except that, damn, it will not work. Not today, looking at what the models can do. You have to approach the implementation in a way that gives the best possible results."

Vibe coding looks like this:

• "Build me an app", enter
• "This does not work", enter
• "It still does not work", enter
• Doom loop: the agent rewrites everything and goes back to old ideas

"A year ago I was pulling my hair out. I could spend whole nights and whole days and get nothing out of it. Sometimes I threw ideas in the bin."

"There is a lot of controversy around vibe coding, and recently more and more teams have pretty good experiences with the so-called Spec Kit."

Spec-Driven Development: the definition

"Spec-Driven Development is an approach where we separate the work on the specification from the target implementation. We work very heavily on the context of the project. We build documentation, specifications and tasks, usually as Markdown files, which we create, evaluate and review, even as a team."

The three pillars of SDD:

• Specify: create the PRD, the roadmap and the tasks BEFORE you start coding
• Review: team review of the specification (no auto-apply!)
• Implement: only now does AI write code, based on the specification

Plan Mode: the first step

Claude Code has a built-in planning mode:

"If we switch the conversation mode with Shift+Tab to plan mode on, Claude Code starts behaving differently. It will not build the app, it will first make a plan for building the app."

But Plan Mode is only the beginning. The more advanced approaches are OpenSpec and Spec Kit.

Spec Kit: the tool from GitHub

"Spec Kit is a tool from GitHub itself that lets you put your vibe coding on special technical and functional rails."

How Spec Kit works:

• Constitution: you define what matters: specifications, simple UX, workflow
• Development workflow: first we specify, plan and break down tasks
• Specification: you say "add the ability to add todos" and Spec Kit writes the user stories
• Planning: AI picks the stack, plans the implementation, asks questions
• Implementation: only at the very end

"The specifications Spec Kit produces are very good. If I had had access to tools like this as a junior ten years ago, I would have spent a lot less time writing 40-page user story documents."

OpenSpec: the open source alternative

One of the videos showed OpenSpec in detail, combined with the 10x Astro Starter:

Three key commands:

• /opsx:propose: proposing a new feature
• Investigates the project (research phase)
• Builds the business and technical specification
• Creates a four-point plan for approval
• Builds a mini knowledge base about the domain

• /opsx:apply: implementing the approved specification
• Works through the tasks on the checklist
• Marks completed items

• /opsx:archive: archiving the completed change
• Moves it to the archive
• Updates the project knowledge base

"In Spec-Driven Development we put a lot of emphasis on not just generating code, but working on the specification, so that the specification is evaluated by the teams."

The roadmap: the missing piece

One host noticed that a PRD plus OpenSpec is not enough. You need a roadmap:

"If you just drop a PRD into OpenSpec, the first element of the specification could be anything. It is very hard to predict."

The solution: a /roadmapit skill that creates a roadmap with specific rules:

• Each phase is at most 5 working days
• Each phase is a business increment (not "database today, API tomorrow")
• A full-stack approach: the user sees value after every phase

"Phase one: the user can already browse listings in a city. It is not that the user knows there is a database in this project, because they do not care."

PRD: the Product Requirements Document

The PRD building method from the videos:

• Metaprompting: 3 subagents create 3 different PRD prompts
• Synthesis: Claude extracts the best elements from each
• Skill: the best prompt is saved as a /prd skill
• The Socratic method: the skill runs an interview (it asks, it does not generate right away)
• Testing: two Claude Code instances in separate terminals test the PRD automatically

The Cowork method:

"I would like you to write a PRD for an online training platform. In general the platform is about online workouts where people can train at home with a personal trainer. I care about the platform having a simple technology stack."

Comparison of results: Claude Sonnet versus Gemini. Sonnet generated a much more detailed PRD with user stories, data structures and technical recommendations.

The full flow from problem to production

One demo showed a full product sprint:

• Data analysis: a CSV with user retention. Claude Code analyzes it and finds the "wall of death" after 14 days
• Competitor research: the /research skill analyzes Duolingo, Strava and Peloton and produces a report with priorities (MoSCoW)
• Recommendation: "A streak mechanism with progress visualization"
• Design: the Pencil MCP produces a new UI screen based on the design system
• Implementation: the prompt "add the design from Pencil to my app" produces code
• Result: a working feature ready for an A/B test

"What we showed you is a full product sprint: from recognizing the problem with users, through research, prototyping and design, to building the final product."

Legacy projects: how to apply SDD

"The scale of the project is not as important as its state. AI has this advantage and disadvantage that it follows the patterns it sees in our project quite strongly."

Recommendation:

• Refactoring: first fix the module you are working with
• Documentation per module: not one PRD for the whole project, but a dedicated one per module
• Linking: individual documents link to the higher-level architecture
• Zoom out: on legacy you do a slice of what is shown on greenfield

"On a large project we cannot create one document that describes the whole application for AI. We have to do it per module."

10x Astro Starter: a project template

A template repository on GitHub from 10x Devs:

"A template we have been developing for over a dozen months. Its purpose is to build web products on top of it, but also to make working with AI inside this repository easy, pleasant and more effective."

It includes:

• OpenSpec already configured
• CLAUDE.md
• Initialization scripts
• The Astro framework ready to go

Tests are part of SDD

"When we do it naively, 'write me tests', those tests are usually not top quality. But if we prepare a testing guide and a good prompt, we can really deliver quality tests."

"AI used consciously not only seriously helps us deliver code faster, it also lets us deliver quality faster, which was often simply missing."

How to implement it

• Adopt OpenSpec or Spec Kit as the standard way of working with Claude Code in every project
• Create a company /bee-prd skill for writing PRDs (with the Socratic method)
• Create a /bee-roadmap skill for roadmaps with 5-day phase limits
• Ban "build me an app" as a way of working: every project starts with a specification
• Introduce specification review before implementation (no auto-apply!)
• Prepare a testing guide as a context file: not "write tests" but "write tests according to the testing guide"
• Use the 10x Astro Starter as the base template for new projects, or create your own team starter
• For legacy projects: documentation per module plus refactoring before new features
• Train PMs in writing PRDs in Claude Code (the Socratic method)

Tools and commands

OpenSpec: commands

# Install OpenSpec and initialize it in the project
npm install -g @fission-ai/openspec@latest
openspec init

# Propose a new feature (based on the roadmap)
/opsx:propose
# Prompt: "First phase of this roadmap" + point to roadmap.md

# Implement the approved specification
/opsx:apply

# Archive the completed feature
/opsx:archive

Spec Kit: setup

# Install the Specify CLI (requires uv)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init my-project

# Slash commands provided by Spec Kit:
# /speckit.constitution  (project principles)
# /speckit.specify       (requirements and user stories)
# /speckit.plan          (technical plan)
# /speckit.tasks         (task list)
# /speckit.implement     (execution)

Plan Mode in Claude Code

# Switch to planning mode
Shift+Tab -> Plan Mode ON

# In Plan Mode Claude:
# - does NOT write code
# - creates an implementation plan
# - waits for your approval or critique
# - moves on to code only after approval

SDD structure in a project

project/
|-- CLAUDE.md # Project constitution
|-- ai/
| |-- prd/
| | `-- prd-final.md # PRD (result of metaprompting)
| |-- roadmap.md # Roadmap (5-day phases)
| |-- competitive-research.md # Competitor research
| `-- specs/ # OpenSpec specifications
| |-- 001-listing/
| | |-- proposal.md # What we are building
| | |-- design.md # How, technically
| | |-- tasks.md # Task checklist
| | `-- knowledge.md # Domain knowledge base
| `-- archive/
| `-- ...
|-- .claude/
| `-- skills/
| |-- prd.md # PRD skill
| |-- roadmapit.md # Roadmap skill
| `-- research.md # Research skill
`-- src/
 `-- ...

An example SDD workflow

STEP 1: PRD
> /prd
> [Claude asks questions about the product]
> [Generates the PRD into ai/prd/prd-final.md]

STEP 2: Roadmap
> /roadmapit
> [Reads the PRD, creates a roadmap with 5-day phases]
> [Saves it to ai/roadmap.md]

STEP 3: Specification (repeat for every phase)
> /clear
> /opsx:propose
> "First phase of roadmap in ai/roadmap.md"
> [Review the specification with the team]

STEP 4: Implementation
> /clear
> /opsx:apply
> [Claude implements based on the specification]

STEP 5: Archive
> /opsx:archive
> [Move on to the next phase]

Other SDD tools mentioned in the videos

Serious warnings

• Never auto-apply without review: a human must review the specification
• Do not skip the roadmap: without it OpenSpec may start from something random
• Clear between phases: every task in a clean context
• SDD does not mean slower: at first it does, but you avoid doom loops and rewriting from scratch
• Tests need a specification too: a testing guide instead of "write tests"

"This is the cure for vibe coding. Build me an app, but, importantly, one that works."

Related topics

• Claude Code: Complete Beginner's Guide: installation and commands
• Context Engineering: context files (CLAUDE.md, skills, PRD)
• MCP Servers: MCP as part of the workflow (Pencil, Figma)