What Is Spec-Driven Development for Teams Using AI Agents?

An AI coding agent will execute a flawless spec flawlessly. It will also execute a spec that quietly contradicts a service three teams away — cleanly, with passing tests, and no warning that anything is off. The gap between those two outcomes isn't the model. It's who wrote the spec, and what they knew when they wrote it.

Spec-driven development for teams is a way of working where people make every decision — what to build, how it fits the existing system, how the work splits — and capture it in a reviewed specification before any AI coding agent writes code. It adapts spec-driven development — built around a single developer — to groups where no one person holds the whole picture.

Key Takeaways

• Spec-driven development (SDD) puts human judgment before machine execution: define the feature, plan how it fits the system, break it into tasks, then hand it to an agent.
• The method is reliable when the spec writer knows the whole codebase — because the spec and the system share one mental model.
• On a team, that condition doesn't hold: the PM knows the customer, a developer knows a few services, and no one knows all of it — so the spec gets written from partial information.
• A team version of SDD has to add what a solo developer carries in their head: live codebase context, independent workstreams, joint sign-off, and one spec that spans every repo a feature touches.

What spec-driven development is

Spec-driven development is a workflow for AI-assisted engineering that puts human judgment before machine execution. You define the feature, map it against the real system, and break it into ordered tasks — then hand those tasks to an agent. The idea is old; naming it, and tooling it, is what changed once agents got fast enough to build faster than anyone could correct them.

GitHub's Spec Kit — an open-source "Toolkit to help you get started with Spec-Driven Development" — states the definition plainly: "Define what and why before deciding how to build it. SDD turns your requirements into a specification, a technical plan, and actionable tasks, then guides implementation against those artifacts."

The division of labour is the whole point. Agents are execution engines: given an unambiguous instruction, they turn it into working code quickly and accurately. What they don't do is decide what should be built, whether something similar already exists, or how a change ripples through the rest of the system. SDD keeps those judgments where they belong — with people — and reserves the agent for the part it's actually good at.

Spec-driven development vs. just writing things down

Spec-driven development is not the same as writing a document before you code. The difference is sequence and authority: every decision that carries risk is made and reviewed before the agent starts, and the specification stays the source of truth the whole way through. A doc that gets written, ignored, and contradicted by the code is not SDD — it's paperwork.

The contrast people reach for is "vibe coding" — prompting an agent conversationally and steering it turn by turn. That works for a prototype one person owns. It fails the moment the output has to match a decision someone else made, because there's no artifact anyone agreed to and nothing to check the result against. SDD front-loads the disagreement: you argue about scope while it's cheap to change, not after a branch is merged. The difference between clean code and correct code is exactly this — an agent produces clean code from any instruction, including a wrong one.

The workflow, stage by stage

The spec-driven development workflow runs in three stages before an agent opens a file. Each stage answers a different question, and each is a human decision, not a generated artifact you rubber-stamp. Skipping a stage doesn't save time — it moves the missing decision downstream, where the agent makes it for you.

Stage one — Spec: what and why. Define the feature precisely enough that "done" is unambiguous. What should the user be able to do, what are the edge cases, what is explicitly out of scope. This is product judgment, and it's where most gaps are cheapest to close.

Stage two — Plan: how it fits. Map the feature onto the real system. Which service owns this, what data model fits, which APIs are involved, what already exists that you should reuse instead of rebuild. This is engineering judgment, and it's the stage solo guides assume you can do from memory.

Stage three — Tasks: ordered steps. Break the plan into units small enough to hand off one at a time, each with acceptance criteria the agent — and a reviewer — can check against. Small scope means cleaner agent decisions and a shorter distance between "wrong" and "caught."

Only then does the agent build, against a task whose every meaningful decision was already made. When SDD works, this is why: the human closed the ambiguities in advance, so the agent never had to guess.

Why spec-driven development for teams is a different problem

Spec-driven development for teams is harder than the solo version because it quietly depends on a condition teams don't meet. Classic SDD is reliable when the person writing the spec knows the entire codebase — because then the spec and the system share one mental model, and writing the spec is just converting memory into text. Break that shared model and everything downstream inherits the gap.

A team has no such person. A PM who has run the product for two years knows the customers cold and has probably never read the notification service. A developer seven months in knows their three services deeply and almost nothing about the other thirty-seven. When they write a spec together, it's built from partial information on both sides — and the agent executes it exactly as written.

The result is code that's technically correct and architecturally wrong: a duplicate table for data that already existed, an integration to a provider the team migrated off last quarter, a retry that isn't idempotent-safe in a service nobody assigned to the task knew existed. The tests pass. Production disagrees. These aren't edge cases — they're the predictable ways SDD breaks at team scale, and they show up within the first two sprints.

What a team version has to add

A team version of spec-driven development doesn't replace the discipline — you still make every decision before the agent starts, and you still keep scope tight. What it adds is the context a solo developer carries in their head and a team has to make explicit. Four things close the gap.

Ground the spec in live codebase state. Before anyone writes requirements, they should be able to ask the actual code — in plain language — whether a preferences schema already exists, which service owns it, what's currently integrated for SMS. A spec built on current facts produces a plan built on current facts.

Structure work as independent workstreams. Instead of one 40-page document where every section is entangled with every other, model the feature as separate tracks, each with its own requirements and acceptance criteria. Changing one track doesn't force a re-read of the rest, and each agent gets only the context its task needs.

Make sign-off explicit and joint. Both product and engineering approve the plan section by section before it becomes an instruction, so nothing moves forward on an assumption only one person made — and if scope changes mid-build, the change routes through the same review rather than around it.

Keep one spec across every repo. Requirements live at the feature level, not the repository level, so a change made in one place reaches every service and every agent instead of two SPEC.md files drifting apart until they contradict each other.

This is the shift Enact is built for — connecting the spec to the codebase, structuring it for parallel work, and keeping one approved source of truth across repos. If you want to size what the gap costs your team today, the rework ROI calculator estimates it from your own headcount and cycle time.

Spec-driven development is the right call for teams using AI coding agents. It just can't be the solo-developer version wearing a team's clothes. The method assumes a spec writer who knows the whole system; a team's job is to rebuild that completeness deliberately — in tooling, in review, in a spec that stays connected to the code — so the agent still gets what it needs: a decision, not a guess.