Spec-driven development treats a written specification as the source of truth and code as its output. What a spec contains, how to hand one to Claude Code or Codex, how to keep it current as the code moves, where the practice breaks, and how Spec Kit, Kiro, BMAD, GSD, and OpenSpec compare.
Spec-driven development treats a written specification as the primary artifact of a project and code as something produced from it. You describe the behaviour you want precisely enough that it can be built and checked, derive a plan from the description, and let a coding agent do the writing. When requirements change, the document changes first.
The idea is old. Coding agents made it practical, because for the first time the cost of regenerating an implementation from a description dropped far enough that the description is worth maintaining. Interest followed: GitHub’s Spec Kit passed 130,000 stars in its first year, and AWS shipped an IDE, Kiro, whose entire interface is organized around the practice.
This guide covers what a spec contains, how you get from a document to an agent executing it, how you keep the two in sync, where the practice breaks, and how the available tools compare. If you want the wider operating model that this sits inside, see our guide to agentic engineering.
What a spec is in this context #
A specification here sits between a PRD and a design doc, and replaces neither. A PRD argues for a piece of work: who the user is, what the problem costs, why now. A design doc explains an approach to other engineers. A spec describes system behaviour in enough detail that an agent can implement it and a test can verify it.
A workable spec answers five questions:
What behaviour changes. Stated as observable outcomes, not as tasks. “A user who closes the app mid-upload finds the upload resumed on next launch”, not “add resume logic to the up”.What is out of scope. Agents expand scope aggressively when a boundary is not written down. An explicit non-goals list is the cheapest control in the whole practice.What the interfaces are. Function signatures, endpoint shapes, schema changes, event names. Anything another part of the system will depend on.What proves it works. Acceptance criteria specific enough to become tests. If you cannot imagine the assertion, the criterion is not finished.What constraints apply. Performance budgets, security rules, platform limits, conventions the codebase already follows.
Everything else is optional and most of it is a liability. A spec long enough to fall out of date will fall out of date. We have written at length about keeping this in one plan document rather than a stack of them, and the same instinct applies whatever tooling you pick.
Several tools add a second, longer-lived document above the per-feature spec: Spec Kit calls it a constitution, Claude Code and Codex read CLAUDE.md
and AGENTS.md
, Cursor uses files under .cursor/rules/
. Those hold the rules that apply to every change: test conventions, error handling, naming, the frameworks you have standardized on. The differs, and it is worth knowing which you have. Agent instruction files are ambient context, pulled into the session automatically; a Spec Kit constitution is consulted by its workflow commands at defined steps. Keeping the two kinds of document separate matters, because a per-feature spec has a finite life and the rules above it do not.
The loop the tools converged on #
Independently, nearly every spec-driven tool arrived at the same four steps.
Specify. Turn a request into described behaviour with acceptance criteria and non-goals. Done as a conversation with the agent, then edited by a person.Plan. Turn behaviour into an approach: which files, which modules, which order, which risks. This is where architectural mistakes are cheapest to catch.Break down. Turn the plan into tasks small enough that each one can be reviewed on its own and, ideally, tested on its own.Implement. Run the agent against one task at a time, with the spec and constitution in context.
Kiro writes this to disk as requirements.md
, design.md
, and tasks.md
per feature. Spec Kit runs it as slash commands, /speckit.specify
through /speckit.implement
, with optional /speckit.clarify
and /speckit.analyze
steps for question-asking and cross-artifact consistency. BMAD distributes the steps across role-based agents that hand files to each other. The vocabulary differs and the shape does not.
The step that earns its keep is the second one. Agents are good at writing code and mediocre at choosing where code should live. Reading a plan takes two minutes and catches the class of mistake that costs a day.
Getting from a written spec to an agent executing it #
The mechanics are less exotic than the terminology suggests. In the repository-centred frameworks, Spec Kit and OpenSpec among them, the spec is a markdown file committed next to the code and the handoff is the agent reading it. Products with their own surface, such as Kiro, store and present the artifacts themselves.
The plainest version, with no framework at all:
- Write the spec in a markdown file under version control, next to the code it describes.
- Open a planning session with the agent, pointed at that file, and have it produce an approach. Claude Code’s plan mode is read-only by design, and Codex has a planning mode whose write access depends on the sandbox and approval settings you chose, so check before you start. We cover the mechanics in our guide to Claude Code plan mode. - Read the plan. Correct it in the document, not in chat, so the correction survives the session.
- Have the agent write the tests implied by the acceptance criteria, and confirm they fail.
- Implement one task at a time, checking in at each boundary.
Adding a framework changes step 1 into a guided interview and step 3 into a phase gate. What it does not change is the requirement that a person reads the artifacts. A spec generated by an agent and approved without reading is a longer prompt with more surface area for a plausible mistake to hide in.
Two details make a disproportionate difference. The first is writing acceptance criteria before implementation, so the tests come from the spec rather than from the code that was written; tests derived from an implementation confirm what the code does rather than what it should do. The second is keeping tasks small enough to review. An agent that produces 40 files in one run has produced something nobody will read carefully, and unreviewed agent output is where the practice quietly reverts to vibe coding. Our best practices for coding with agents go through the review side in more depth.
Keeping the spec and the work in sync #
This is the weak point of the practice, and the place where tool choice makes the most difference.
The pitch says code is regenerable output from a living specification. In practice, code drifts. A production incident gets patched at 2am. A dependency changes behaviour. Somebody discovers during implementation that the design was wrong and fixes the code without going back to the document. Three months later the spec describes a system that no longer exists, and it is now worse than no document at all, because people trust it.
The tools differ in how much of this they handle, and the direction matters. Propagating an edit downward, from an amended requirement into the design and the task list, is well covered: Kiro has a Sync Files action in tasks.md
that regenerates tasks against changed requirements, and it can check which tasks the code already satisfies. Propagating upward, from a change that originated in the code back into the requirements, is the direction that stays manual almost everywhere. Spec Kit’s workflow runs from specification through planning and tasks to implementation without an operation that merges a shipped change back into a maintained baseline.
OpenSpec models this most explicitly. It treats each piece of work as a change proposal expressed as a delta against the existing specs, showing which requirements are added, modified, or removed, and it ships sync
and archive
operations that fold the shipped delta back into the living spec set before the next feature starts. Whether or not you adopt the tool, the loop is the one to copy.
Three habits that work regardless of tooling:
Put the spec in the same pull request as the code. If the document lives in the repository, a reviewer can see when behaviour changed and the description did not. If it lives in Confluence, nobody will ever notice.Give the update job to the agent at the end of the session, while the context is still loaded.“Update the spec to match what we actually built, and list what changed” takes thirty seconds and is far more accurate than the same request made a week later.Separate the plan from the baseline. The task list and the implementation notes for a shipped feature are spent, and should be archived. The description of how the system now behaves is not, and needs to survive somewhere authoritative, whether that is product documentation, the tests, or a maintained spec set. Deleting both is how a team loses the baseline it needs the next time that area changes; keeping both is how the active set fills with noise.
Where it breaks down #
The overhead is wrong for small work. A four-phase process for a two-line fix is theatre. Teams that apply the ceremony uniformly abandon it within a month. Pick a threshold, whether it is an hour of work, more than three files, or anything touching a public interface, and use plain prompting below it.
Specs generated by agents and never read. The tools make it fast to produce a requirements document. Reading it is still your job, at human speed, and if you skip that you have automated the production of confident wrongness.
Precision that outruns knowledge. Writing a design document for a subsystem you do not yet understand produces detailed fiction, and the agent will implement it faithfully. Do the exploratory work first, on a throwaway branch, and write the spec once you know what the answer looks like.
Too many artifacts per feature. Frameworks that generate a requirements file, a design file, a task list, and a set of role handoffs per feature produce a lot of artifacts, and each one is something to maintain. We have argued elsewhere that one plan document usually beats many, and we still think so for a small team moving fast. The multi-document approach earns its cost when several people, or several agents, need to work from the same source at once and need clear boundaries between their pieces.
Prioritization does not disappear. Cheap implementation changes which questions are hard. When the constraint stops being engineering hours, deciding what deserves a spec at all becomes the scarce judgement, which is how coding agents changed the way we prioritize.
The tools #
Verified against primary sources on 22 August 2026. Star counts move; treat them as a rough measure of adoption.
| Tool | What it is | Licence | Works with |
|---|---|---|---|
KiroBMAD-METHODOpenSpecGSD CoreClaude Code/CodexCLAUDE.md
/ AGENTS.md
Cursor.cursor/rules/
TesslNimbalystGitHub Spec Kit is the default recommendation for a team that wants structure without buying a product. It is MIT licensed, at v1.0.1 as of August 2026, and installs into your existing agent rather than replacing it. The constitution file is its best idea: one place for the project rules that every change has to respect, consulted by the workflow commands rather than restated in each spec. The commands are opinionated, and the four artifacts per feature are more than a small change needs.
Kiro is the most complete implementation of the idea, and the one that beats a general workspace on this specific axis. A feature spec gets a requirements file, a design file, and a task list, and the flow puts your review between each phase and the code. Lighter variants exist for bugs and small changes. If your problem is that agents start coding before you have finished thinking, Kiro solves it structurally rather than by asking you to be disciplined. The trade is that you adopt an IDE, and one on AWS’s roadmap. Pricing runs from a free tier with 50 credits to $200 per user per month at the top; the plans in between are $20, $40, and $100, with extra credits at four cents each. We keep a fuller Kiro comparison if you are choosing.
BMAD-METHOD is the heaviest and the most process-shaped. It assigns roles across product, architecture, UX, development, and testing, and passes work between them as files, which produces a traceable chain from requirement to delivery. Teams migrating an existing agile process onto agents tend to like it. Teams of two find it enormous. It is MIT licensed and actively developed.
OpenSpec is the one to look at if drift is your specific problem, for the delta and archive model described above. It is MIT licensed, installs into thirty or more tools, and is lighter than Spec Kit in day-to-day use.
GSD takes a different angle: rather than phase gates, it runs research, planning, and execution in fresh-context subagents to keep the main session lean, which is a context-engineering answer to the same problem. Check the repository before you follow a link to it. The original gsd-build/get-shit-done
, which was Claude Code specific, was archived and now carries a redirect notice; development continues as GSD Core under the Open GSD organization, still MIT licensed, and it has broadened well past Claude Code to Codex, Cursor, OpenCode, Copilot, and others. Older write-ups still point at the archived repository.
Cursor and the CLI agents cover the practice partially. Their planning modes investigate the repository and propose an approach, which covers the plan step but not requirements elicitation or acceptance criteria, and rules files give you something like the constitution. None of them has a spec lifecycle, a drift check, or a defined path from a shipped change back to the document. For many teams that partial coverage is the right amount of process.
Tessl has moved on from the spec registry it launched with and now sells a registry and governance layer for agent skills, with adoption metrics, install policies, and security scanning. Relevant if your problem is standardizing what a fleet of agents knows across an organization, less so if your problem is one feature.
Nimbalyst, which we build, is in this list for a different reason from the others. It imposes no phase gates and ships no spec format, so if you want the process enforced for you, pick Spec Kit or Kiro. What it changes is the surroundings: the spec is a markdown file you edit properly, sitting beside the mockup, diagram, data model, tracker item, agent sessions, and diffs that belong to the same piece of work, with Claude Code and Codex both able to read and update them. The section below explains why we think that placement, rather than more artifacts, is what keeps a spec current.
How much process you actually need #
Our own answer, after building this way daily: fewer artifacts than the frameworks want, more discipline than plain prompting gives you.
We keep one plan document per piece of work in the repository, holding the behaviour, the non-goals, the acceptance criteria, and the open questions. We use plan mode to produce the approach and edit the document rather than arguing in chat. We write the tests before the implementation. And we make updating the document part of finishing the work, not a separate chore that never happens.
Where a visual workspace changes the picture is what surrounds the document. In Nimbalyst, the open-source visual workspace for building with Codex, Claude Code, and more, the spec is a markdown file you edit properly rather than in a terminal pane, and it sits next to the things that give it meaning: the mockup of the screen it describes, the diagram of the flow, the data model, the tracker item, the agent sessions implementing it, and the diffs those sessions produced. Your agents read and write all of them. When a session finishes, updating the plan and closing the tracker item happens in the same place the work happened, which is the difference between a document that stays current and one that does not.
The heterogeneous part matters here too. Claude Code and Codex sit side by side in the same workspace, and OpenCode is supported, so a spec written in one session can be handed to a different agent for implementation without leaving the document behind. Our guide to orchestrating Claude Code and Codex together covers the handoff patterns.
Nimbalyst is MIT licensed for individual-use features.
Frequently asked questions #
What is spec-driven development?
A way of working in which a written specification is the primary artifact and code is treated as output produced from it. You describe behaviour and the criteria that prove it, derive a plan, and let an agent implement against it. When requirements change, the document changes first.
Is spec-driven development the same as waterfall?
No, though the criticism is fair enough to take seriously. Waterfall’s problem was a long, unrevisitable planning phase committing a team to decisions made when they knew least. Spec-driven development with agents runs the loop per feature, over hours rather than quarters, and the specification is expected to change. Applied to a whole product up front, it would recreate the original problem.
Do I need a dedicated tool?
No. A markdown file in the repository plus the discipline to update it gets most of the value. Tools add templates, gates, and structure, which help on larger changes and larger teams.
Which spec-driven tool works with Claude Code?
Spec Kit, OpenSpec, BMAD, and GSD all do, and the first three also work with Codex and many other agents. Claude Code on its own covers part of the practice through plan mode and CLAUDE.md
.
How do you stop specs from going stale?
Keep them in the repository so they show up in code review, ask the agent to reconcile the document with what was built at the end of each session while the context is loaded, and archive the task and implementation artifacts once a feature ships while keeping the description of current behaviour somewhere authoritative. OpenSpec has the most explicit support for this, with sync
and archive
operations that merge a shipped change back into the maintained spec set.
Is spec-driven development worth it for solo developers?
For work above a couple of hours, yes, and the reason is context rather than communication. A written spec is what lets you resume a piece of work next week, or hand it to a second agent, without rebuilding the reasoning from memory.
Related reading #
Best practices for coding with agents. The nine-step workflow we use, including the review and test discipline around the spec.One plan doc for humans and agents. What goes in the document and what stays out of it.Why use many docs when one plan doc wins. The case against the multi-document frameworks, for small teams.Claude Code plan mode. The specify-and-plan steps without adopting a framework.How to plan features with AI agents. The planning conversation itself.What is an agentic development environment?. The workspace category this practice runs inside.
Related pages #
Related posts #
Best AI Agent Orchestration Platforms 2026: Coding vs Workflow
AI agent orchestration means two different products. Compare control planes for your own coding agents (Nimbalyst, Orca, Emdash, Superset, Conductor, Warp) against workflow frameworks like LangGraph and CrewAI.
What Is an Agentic Development Environment (ADE)?
An agentic development environment is the workspace you use to direct several coding agents at once. Definition, origins, how an ADE differs from an IDE and a CLI agent, and criteria for evaluating one.
Best Tools for Managing Parallel AI Coding Agents in 2026
Looking for an agent kanban board or a way to manage multiple coding agents? These 10 tools cover multi-agent coding across Claude Code, Codex, terminal multiplexers, and visual workspaces.