Spec-driven development on an existing codebase

Published 18 October 2026

On an existing codebase, spec-driven development works one change at a time: you write a spec for the change you are about to make, not for the system you already have. Spec Kit, OpenSpec, Kiro and BMAD now all say so in their own guides. What that leaves out is the behaviour you are not changing — it is written down nowhere, so neither the agent nor the reviewer can see what a change might break.

It seems like all the frameworks I’ve come across make at least one of two assumptions:
1) The project is greenfield and will be able to adopt the workflow from the start.
2) All contributors to this project will adopt the same workflow, so will have a consistent view of the state of the world.

— a question on r/ExperiencedDevs, November 2025, 93 comments

Can you use spec-driven development on an existing codebase?

Yes, but most of what is written about it starts from an empty folder, and the early reviews of brownfield use were not kind:

For large existing codebases, SDD is mostly unusable.

— Marmelab, November 2025

A commenter agreed: “I am also finding larger apps built using SDD steadily get harder to extend” (Hacker News). Trying three tools for martinfowler.com, Birgitta Böckeler found that for two of them “it also seems to be even more work to introduce them into an existing codebase”. Someone who used Spec Kit with Claude Code for two months: “Retrofitting SDD onto an existing 30k-LOC codebase without prior specs is months of work, not days” (r/LocalLLaMA, May 2026).

Others report the opposite: “I still find tools like spec kit give reliably good results in brownfield codebases” (Hacker News, February 2026). Spec Kit’s documentation lists community walkthroughs that extend a 420,000-line Java runtime with no prior specs. What separates the two experiences is mostly how the work is cut — and on that, the tools’ own guides now agree.

The rule every tool now gives: specify the change, not the system

You do not document your whole codebase to start. You write specs only for what you’re about to change.

— OpenSpec: using OpenSpec in an existing project

Spec Kit’s guide says the same: the new spec “defines the change you intend to make, not a retroactive specification of every existing behavior”, and it warns against making “document the entire existing system” your first feature (Spec Kit: adopting Spec Kit in an existing project). BMAD goes further: “Most of the knowledge about this application is already encoded in its source”, and feeding an agent descriptions of what it can read in the code “creates contradiction, ambiguity, and context-window bloat” (BMAD: start in an existing codebase).

So the shape is the same everywhere: the existing system stays in the code, a short file of project rules sits beside it, and the spec covers the change.

How Spec Kit, OpenSpec, Kiro and BMAD handle a brownfield project

Spec Kit. Start: specify init --here in the repository. The project’s rules: constitution.md, principles already true for the code. What gets a spec: the next bounded change.
OpenSpec. Start: openspec init. The project’s rules: context: in openspec/config.yaml. What gets a spec: the next change, as a delta — added, modified, removed.
Kiro. Start: Generate Steering Docs, in the IDE. The project’s rules: product.md, tech.md and structure.md in .kiro/steering/. What gets a spec: each feature — requirements, design and tasks.
BMAD. Start: bmad-project-context, optional. The project’s rules: a short block in AGENTS.md. What gets a spec: the change; a PRD only when it needs one.

Spec Kit on an existing project

Commit or stash your work and create a branch, so every file Spec Kit adds shows up in review.
Run specify init --here --force --integration <your-agent> from the repository root. --force may replace files at paths Spec Kit manages; it does not delete your application. Review the diff.
Run /speckit.constitution with rules that are already true — taken from the README, architecture decisions and CI. The guide is blunt: “Do not invent standards merely to fill the constitution template.”
Choose a bounded first change and say what must not change. The guide’s example adds a CSV export and says “do not change the existing JSON API response”.
Continue as usual: clarify, plan, tasks, analyze, implement.
Before the second change, decide how specs will age: each feature folder kept as a historical record, spec.md kept as a living contract, or discoveries allowed to flow back from the code.

Two things trip people up later. Re-running specify init --here --force to get newer templates can overwrite your constitution.md and customised templates (spec-kit #916) — protect them first. And a community extension, Brownfield Bootstrap, reads the codebase to draft the constitution for you (spec-kit #1436).

OpenSpec on an existing project

openspec init
/opsx:explore
/opsx:propose add-api-rate-limiting
/opsx:apply
/opsx:archive

OpenSpec calls itself “built for brownfield”. /opsx:explore has the agent read the area you are about to touch before it proposes anything. The proposal holds a delta spec — what is added, modified or removed — and archiving merges it into openspec/specs/, which “starts nearly empty and accumulates”. Existing PRDs are treated as “source material for exploration, not as specs to convert”.

Kiro and BMAD on an existing project

Kiro creates three steering files — product, tech stack, project structure — and includes them in every interaction by default. They describe the project to the agent; they are not a spec of what the system does. Features then get their own requirements, design and tasks.

BMAD has deprecated its old bmad-document-project workflow. For a small change, bmad-build reads the repository first and writes down what to reuse and what not to change. The original greenfield PRD is archived, kept “out of reach of an ordinary change”.

Should you reverse-engineer specs from existing code?

Some say you have to:

For legacy projects you need to import that context upfront. A “backfill” if you will.

— r/ExperiencedDevs, November 2025

Tools for it exist — Tessl can document a file from its code, and Spec Kit’s Brownfield Bootstrap drafts the constitution — and OpenSpec users have asked for it: teams “need a way to generate specs and documentation retroactively from the existing code” (OpenSpec #724). Three things to know first:

The code says what the system does, not what was agreed. A spec read from the code records the bugs as requirements, and leaves out every rule that was never coded. Someone who knows what the system should do has to confirm it before anyone builds on it.

A backfilled spec starts going stale the day it is written. OpenSpec’s guide: “Writing specs for code you aren’t changing feels productive and usually isn’t. Those specs go stale, because nothing forces them to track reality.” That is spec drift, from day one.

Agents misread descriptions of existing code. Böckeler asked Spec Kit for a feature that built on existing code; its research step described the existing classes, and then:

the agent ignored the notes that these were descriptions of existing classes, it just took them as a new specification and generated them all over again, creating duplicates.

— martinfowler.com, October 2025

If you backfill, backfill only the area your next change touches, and have it confirmed.

What specifying only the change leaves out

The behaviour you are not changing. In Spec Kit’s example, “keep the filters, keep the authorization, don’t change the JSON response” is written by hand into the change. What nobody thinks to write is not checked. On a large brownfield project, one Spec Kit user found that “those with deep knowledge of the project provided architectural guidance that I had to stuff into the spec to then regenerate things” (spec-kit #806).

The specs after the change. Spec Kit’s own issue about existing projects lists “Specs diverge from codebase as the project evolves” (#916), and the most-supported request on the topic, with 115 reactions, opens: “Multiple users find it difficult to update, refine, or iterate on existing specs in Spec Kit without creating new branches and redundant specification artifacts” (#1191).

The people who do not use the workflow. That is the second assumption in the question above. A hotfix, a manual change, a teammate who does not run the agent — the specs never hear about it. OpenSpec’s request for reverse-engineering starts from the same place: “Teams adopting OpenSpec often have members who prefer implementing features manually with minimal AI assistance” (#724).

The people who know what it should do. On an old system, the intended behaviour often lives with a product owner, a client or a support lead — not in the repository, and not in git. See who reviews the spec.

How to start spec-driven development on an existing codebase

Start on a branch, so everything the tool adds can be reviewed like code.
Write down only the rules that are already true — from the README, architecture decisions and CI, not from the template.
Pick one bounded change you need anyway, not a tour of the whole system.
Let the agent read the area first, before it proposes anything.
Write what must not change beside what will. Name the APIs, data and behaviour the change has to leave alone.
Have anything read from the code confirmed by someone who knows what the system should do.
Decide how specs age before the second change: one folder per change kept as history, or one living spec you update.
Agree what happens to changes made outside the workflow — hotfixes, manual fixes, other teams — or they will not be in the specs.

Where Specroot fits

This is the problem Specroot works on: a specification that lives outside the repository, covers the behaviour you are not changing as well as the change, and can be reviewed by the people who know what the system should do. Specroot for teams using AI coding agents.