Overview

I built this blog in a day by talking to Claude Code. A few weeks later, when I came back to write a new article, I had no recollection of what code I was actually running - and neither did the agent.

Spec-driven development (SDD) fixes that by writing down what the software should do before an agent builds it, and keeping that description where the agent can find it. The spec becomes the source of truth: the agent reads it before a task, implements against it, and the spec is updated when the requirements change.

Why AI agents need spec-driven development

Every coding agent works within a context window - everything the model sees in the current session: your instructions, the files it has read and the output of the commands it has run. The window has a limit. When a long session gets close to it, the agent compacts the conversation, replacing the history with a shorter summary to make room. Claude Code does this automatically, and you can trigger it yourself with /compact(opens in new tab). Whatever didn’t make it into the summary is gone, and a new session starts with nothing at all.

The context window is a big part of the problem, but not all of it. The other part is how the work gets defined. Without a spec, development becomes a loop of prompt, result and review, then another prompt and another review. That’s exhausting and confusing for both the agent and the person operating it, and it’s a poor way to define a piece of work - the definition ends up scattered across a conversation that’s about to be compacted.

A spec addresses both. It defines the work up front, refined and explicit: the logical pieces it breaks down into, and the technical aspects of how each one is implemented. It’s also context that survives - the agent loads it at the start of a task instead of rediscovering it from the code, and because the agent implements against it, you have something to check the result against.

Start spec-driven development with OpenSpec

If you’re new to spec-driven development, start with a framework rather than building your own. OpenSpec is a much better starting point than the homegrown commands I began with. It shows you what a good spec looks like and gives you a workflow to learn from, before you decide what you’d do differently.

Getting started:

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

Every change then follows the same loop:

• /opsx:explore - think through the options before committing to a plan
• /opsx:propose - create the change: a proposal, spec updates, a design and tasks
• /opsx:apply - implement the tasks
• /opsx:archive - merge the spec updates and archive the change

OpenSpec is a good fit for existing codebases. You can use it to scan the code and build on explicit requirements, which makes it useful for legacy projects, or when you want to work spec-first but the rest of the team doesn’t share your workflow.

Other spec-driven development frameworks

I haven’t used these three myself, but they’re among the best-known SDD tools and worth a look before you pick one:

• GitHub Spec Kit(opens in new tab) - an open-source toolkit from GitHub. Its specify CLI sets up the project, and the work moves through a constitution (the project’s principles), a specification, a technical plan, tasks and implementation.
• Kiro(opens in new tab) - an IDE and CLI built by AWS, with specs at its core. Each feature spec is three files: requirements.md (user stories with acceptance criteria), design.md and tasks.md.
• BMAD Method(opens in new tab) - an open-source method that covers product, architecture, UX, development and testing through specialised agents, with a PRD, an architecture document and stories carrying the context from one phase to the next.

Scale it up with a pipeline

For larger projects, the work can be split across a set of skills, each owning one stage, with the output of one as the input of the next. I wrote about how to plan, write and evaluate skills like these in Tips for writing efficient skills for LLM agents.

Keep specs alive with beads

Once a project is bootstrapped, the specs have to keep up with the code. For that, I work with beads directly.

This blog made that move in July 2026: its OpenSpec specs became closed beads issues, linked to the specs they depend on, and OpenSpec was retired. After the initial setup, OpenSpec felt like more process than most tasks needed. Trivial changes were easier to describe in a well-refined prompt, and bigger ones were easier to break down in beads.

That breakdown is the important part. A big task handed to a single agent bloats its context, and the more it carries, the more room there is for discrepancies between what was asked and what was built. So I ask the agent to split bigger work into reviewable chunks in beads, and each chunk goes to a separate agent with a smaller context.

Spec-driven development tips

These are the habits I’d keep, whatever tool you pick:

1. Start with a framework - learn what a good spec looks like from OpenSpec or a similar tool before you build your own workflow
2. Match the process to the task - a feature deserves a spec, a trivial change usually needs a well-refined prompt
3. One reviewable chunk at a time - break bigger work down, and give each chunk to an agent with a small, focused context
4. Keep a human in the loop - agents can review code, but a person verifies it
5. Watch the token usage - spec frameworks read and write a lot, so check what they cost you before making them the default for everything

Final thoughts

Since January, this blog has gone through three spec setups: homegrown commands, OpenSpec and beads. The tools changed every time. The idea didn’t: write down what the code should do, in a form an agent can load, break the work into pieces a person can review, and check the result.

If you’ve found an SDD setup that works for you, let me know in the comments. Coming back to a project after a few weeks shouldn’t mean starting from zero, for you or for the agent.

How this article changed

This article was first published in January 2026. Back then, my setup was a handful of homegrown slash-commands - /spec-create(opens in new tab), /spec-compact(opens in new tab), /spec-apply(opens in new tab), /spec-verify(opens in new tab) and /spec-refactor(opens in new tab) - and the original walkthrough used them to build the very component that renders those links. In February 2026, the specs moved to OpenSpec, and in July 2026, into beads. In October 2026, the article was rewritten around spec-driven development as a whole.

The original specs and their OpenSpec versions are archived in the blog’s repository: