Ask an AI coding agent to “build me a tracker app for a 75 day fitness challenge” and you will probably have a working app within seconds. What you will not have is a say in the dozens of decisions buried in that request, like what happens after a missed day or where the data lives. The agent makes them silently, and you find out only after the code exists. Spec-driven development (SDD) reverses that order: you write the decisions down in short files, approve them, and only then let the agent build. The AI still writes the code; what changes is who decides, and when. Here is how the loop works in Claude Code, and when a spec is not worth the effort.
What a one-line prompt decides for you
In one test, Claude Code ran in the Claude Desktop app in Auto mode, a permission setting that runs tool calls without stopping for approval, and got only that prompt in an empty folder. It never asked a question. It loaded a frontend-design skill, a packaged set of task instructions, effectively deciding on its own that the user wanted a graphical interface. It then built a single index.html file and read the vague request as the well-known 75 Hard fitness challenge, hard-coding two daily workouts, a diet, a gallon of water, 10 pages of reading and a progress photo.
Only at the end did Claude list its assumptions under “Things to know,” such as strict mode and browser-only storage. By then the rules are already code. In real use, an assumption like this tends to surface much later, for example when a streak resets without warning on day 13.
Five ways vibe coding breaks down
Vibe coding means describing what you want in plain language, letting the AI guess the rest and fixing the result through chat. It is fast, but it leaves the developer reacting to choices the AI already made, which causes five problems:
| Problem | What happens |
|---|---|
| Unstated assumptions | Rules nobody asked for, like a forced restart after a missed day, harden into code |
| Inconsistent runs | The same prompt in a new session can produce conflicting rules |
| Disappearing fixes | Chat corrections vanish in the next session, so old bugs return |
| Context exhaustion | Long sessions fill the context window, the text a model can consider at once, causing hallucinations and regressions |
| Team drift | Five engineers running their own AI agents on one repository end up with diverging versions of the same feature |
All five share one root cause: key requirements and design decisions were never written down. A longer prompt does not help, because whatever it leaves out, the model still fills in. Vibe coding still suits low-stakes, throwaway work such as a quick proof of concept, boilerplate setup, a prototype or a simple personal site, where a formal spec only adds overhead.
A spec works like a signed job sheet
A spec, short for specification, is a written agreement between developer and AI about what is being built and why. It works like the signed job sheet a contractor gets before building a house: anything left off the sheet is decided on site, and the same holds when the builder is an AI. A useful spec names the users, the core goals, the app’s limits and what the software will not do. The how, such as file names and data structures, stays with the AI. From an approved spec, the AI drafts a numbered plan that the developer reviews before any code is written. Fixing a wrong rule at that point costs one reply; fixing it after the code exists means a costly refactor.
This is not waterfall development, which plans a whole project for months up front; SDD runs short loops sized to one feature. Agents never behave identically twice, but a tight spec narrows their choices so they guess far less, even if errors never reach zero.
How the spec files are organized
Everything lives in one top-level specs folder. Three foundation files are written once; each feature then gets a numbered folder under features with three files of its own.
| File | Scope | Contents |
|---|---|---|
| vision.md | Project | What the app is, why it exists, who it serves and its anti-goals |
| tech-stack.md | Project | Languages, storage, styling and testing choices |
| roadmap.md | Project | Features in build order, their status and what is out of scope |
| requirements.md | Feature | What the feature must do, success criteria and exclusions |
| plan.md | Feature | The AI’s step-by-step implementation plan |
| validation.md | Feature | Tests that prove the feature works |
Validation conditions must be observable, such as pressing Start on an empty form and confirming nothing is saved. The work then becomes a loop: pick the next roadmap item, write its spec, approve it, let the AI build it, validate it and mark it done. The same loop works in Cursor or Codex.
▲ Foundation files and per-feature spec folders
Building the foundation through an interview
A greenfield project starts from an empty folder with no code or commit history. After Claude created a Git repository in an empty folder, the first prompt set a firm rule: write no code yet, and interview the developer one question at a time about the vision, tech stack and roadmap, capped at six features that can each be tested in a browser in one sitting. Asking Claude to use its AskUserQuestion tool turned the interview into multiple-choice questions with a recommended answer.
| Question | Answer chosen |
|---|---|
| Which challenge | 75 Hard with fixed rules |
| Who it is for | Just me, for a fast daily check-in |
| Day ends with unchecked tasks | Offer a restart that the user confirms |
| Data storage | localStorage, the browser’s built-in storage, instead of a hosted database |
| Testing | Playwright, a browser automation tool, plus logic unit tests |
| Editing past days | Yesterday only |
Claude reserved three of the six roadmap slots for must-have features: today’s check-in, a day counter showing day N of 75, and missed-day restart handling. The rest went to a progress grid, a finish screen and backup export and import, which matters because all data stays in the browser. Where the vibe-coded app let users tick any past day, the spec allows edits to yesterday only. The tech stack came out as plain HTML, CSS and JavaScript with no frameworks or build step, all settled before any application code existed. This example accepted the recommended answers to save time; a real project deserves careful thought on each one.
The two-prompt loop for each feature
Each feature then runs through the same pair of prompts. The planning prompt produces spec files that get reviewed and committed; the implementation prompt builds from them in a fresh chat, and the feature is merged only after the tests and a manual check pass.
Plan: interview, then write three files
The planning prompt has Claude Code pick the next unbuilt feature from roadmap.md, create a branch that follows a naming rule, such as feature/1-todays-check-in, and interview the developer without writing code. For the first feature, today’s check-in, that settled details like ticked items dimming in place, a switch to the new day after midnight and Playwright tests on Chromium and WebKit mobile profiles for a Pixel 7 and an iPhone 15.
The output was requirements.md with requirements R1 through R12 and exclusions, validation.md with 16 automated test scenarios and an 8-step manual walkthrough, and plan.md with the build order and a risk note: since the first feature also carries project setup, a long session should pause at step 4, a usable checklist. Gaps in the foundation files ripple into all three, so the foundation gets reviewed first.
Build: clear the chat, then implement from the spec
After committing the specs, the developer ran /clear to wipe the conversation. The project’s state lives in Markdown files under Git rather than in chat history, so a fresh session or a teammate can carry on. The implementation prompt asks Claude Code to follow plan.md step by step, build only what requirements.md specifies, run every test in validation.md and report what still needs a manual check.
All 38 Playwright tests passed, yet Claude Code left the roadmap item unchecked for a human walkthrough. Only after the six tasks were ticked on a local server and the header read “Day complete” did Claude commit, merge and mark the feature built. The second feature reused both prompts and passed 118 tests. Playwright adds setup work, but it is a far stronger safety net than clicking through by hand alone. Even so, automated tests are not enough on their own; a person should check the interface before signing off.
▲ Automated tests, then a human check
Turning repeated prompts into skills
To avoid pasting long prompts for every feature, the planning prompt became a Claude Code skill, a named set of instructions stored on disk and run as a command. Saved at .claude/skills/feature-spec/SKILL.md, it finds the next roadmap item, creates the branch, runs the interview and writes the three spec files without touching application code. After a restart of the desktop app, typing /feature-spec starts the next feature. Skills are one of four ways to teach an agent about a project, alongside standing rules in CLAUDE.md or AGENTS.md that load first, reviewer agents with their own context windows, and MCP servers that bring in outside context and tools.
Adding specs to an existing codebase
Most real work happens in brownfield projects, existing codebases without specs, where the foundation files come from the code. The example here is a 75-day fitness tracking progressive web app, an installable web app, with a FastAPI backend and automated tests.
- Tell Claude Code to inspect the repository and tests without changing code, and to write the three foundation files from what it finds.
- Check where documents and code disagree. The README described four streak metrics that the backend had merged into one, and it listed deployment and configuration files that did not exist. The code, not the documentation, is the source of truth.
- Commit the foundation files and the skill, then run /feature-spec. For a new pause-days feature, Claude Code created a feature/07-pause-days branch and asked how many pause days a 75-day run should allow, recommending five.
- Approve the specs and let Claude Code build a feature that lets users schedule up to five rest days without breaking their streak. Once the tests pass, check the result by hand on a phone.
Choosing a framework, from Plan Mode to BMAD
SDD frameworks package the same loop with their own commands, rules and agent personas. As of October 13, 2026, they line up from lightest to heaviest:
| Framework | How it works | Best fit |
|---|---|---|
| Plan Mode in Claude Code | Proposes a plan and changes no files until you approve | Small increments |
| OpenSpec | Command-line tool that keeps a spec file for each change | Existing codebases |
| GitHub Spec Kit | Fixed path from overarching principles down to code | Teams using different coding agents |
| Superpowers | Plugin skill set that enforces ideation, planning, testing and code review in order | Disciplined solo builders |
| BMAD | Five specialized agent personas managing the specs | Enterprise-grade work and major features |
The five have not been benchmarked head to head, so the list reflects weight rather than quality. A practical pattern is two tiers: a heavier framework such as BMAD for new projects and major features, and Plan Mode for smaller work. Never run two spec frameworks in one repository, because conflicting documents destroy the single source of truth. Plan Mode is the exception, since it writes no files and can sit beside one framework.
Key takeaways
Without written decisions, an AI agent will choose your stack, your rules and even your styling, so make those calls yourself and send every substantial feature through planning, specification and implementation. To get started:
- Create a specs folder and have the AI interview you for the three foundation files, or derive them from existing code.
- Start the next feature with a planning prompt that forbids code, then review and commit its spec files.
- Clear the chat, build from the spec, and merge only after the tests pass and you have checked the result yourself.
- Turn any prompt you paste twice into a skill.
- Skip the spec when a change fits in a short ticket, touches fewer than three files, involves no design decisions or is visual polish you judge by eye.