Spec-Driven Development with AI Agents: A Practical Guide
Key Facts
- Spec-driven development treats a written specification as the primary source of truth, and AI coding agents generate code from that specification instead of from ad hoc prompts.
- A typical spec-driven workflow moves from requirements and acceptance criteria to a technical plan, then to small tasks, and finally to implementation and verification.
- AI agents need project context, such as architecture notes, coding standards, and constraints, to produce code that fits an existing codebase.
- Guardrails such as test suites, linters, permission limits, and mandatory review reduce the risk of unchecked agent output.
- The method works well for new features and for incremental modernization of legacy systems, where behavior can be described and tested.
- The main costs are the time needed to write and maintain specifications and the continued need for human technical judgment.
- Small pilot features allow teams to evaluate the method before applying it across a product.
(Prefer videos? Watch a summary of this article below.)
SaM Solutions explains how spec-driven development with AI agents works, which context and guardrails agents need, and where the method delivers value. The article also covers the limitations that engineering leaders should weigh before adoption. Readers will find a step-by-step workflow, typical use cases, and a practical way to run a first pilot.
What Is Spec-Driven Development with AI Agents?
Spec-driven development with AI agents is a software delivery method in which a structured specification defines what the system must do, and AI coding agents implement that specification under human supervision. The specification contains requirements, acceptance criteria, and constraints, and it remains the reference for planning, implementation, and verification. Tools such as GitHub Spec Kit and AWS Kiro follow this pattern by separating specification, plan, and task list into distinct artifacts.
The method responds to a known weakness of prompt-by-prompt coding. When a developer describes a feature in a chat window, the intent lives in a conversation that disappears. A versioned specification keeps that intent visible to developers, reviewers, and agents. Spec-driven development AI agents therefore shift effort from writing code toward defining outcomes precisely.
However, companies should bear in mind that this approach can also lead to higher costs, explains Dzmitry Verasau, Tech Lead at SaM Solutions:
“Costs will inevitably increase, as using agents incurs additional expenses. If a solution already exists, you can try to generate specifications based on the existing code and then adapt them accordingly. This can be done incrementally, starting by migrating individual modules and gradually transitioning to a specification-driven approach. Nevertheless, I haven’t seen anyone successfully implement this approach in an existing project.”
Need expert guidance on designing and implementing AI solutions for your business?
How Does a Spec-Driven Workflow Work?
A spec-driven workflow moves through three connected stages. Teams first define requirements and acceptance criteria, then convert the specification into a technical plan and discrete tasks, and finally run implementation, review, and verification against the original specification. Each stage produces a written artifact that a human approves before the next stage begins.
| Stage | Main input | Main output | Human checkpoint |
| Define | Business goal, user needs | Requirements and acceptance criteria | Product owner approves scope |
| Plan | Approved specification, project context | Technical plan and ordered task list | Architect reviews design decisions |
| Implement | Individual tasks, guardrails | Code and tests per task | Developer reviews each change |
| Verify | Code, tests, acceptance criteria | Test results and traceability record | QA and product owner confirm outcome |
Define Requirements and Acceptance Criteria
The first stage describes what the feature must achieve and for whom, without prescribing the technology. Requirements state behavior, such as which inputs the system accepts and how it responds to invalid data. Acceptance criteria turn those statements into checks that can pass or fail, for example “a user with an expired token receives an authentication error and no data.”
Precise criteria matter because an AI agent cannot ask a colleague what a vague sentence meant. Teams should also record non-functional requirements, including performance limits, security rules, and compliance constraints, in the same document.
Turn the Specification into a Plan and Tasks
In the second stage, an architect or senior developer, often assisted by an agent, converts the specification into a technical plan. The plan names the components to change, the data structures involved, and the interfaces that must stay stable. The team then splits the plan into small tasks that each deliver a verifiable result.
Small tasks limit the damage when an agent misreads an instruction, because the error appears in a short diff instead of a large rewrite. Reviewing the plan before any code exists is the cheapest point at which to correct a wrong design decision.
Implement, Review, and Verify the Result
During implementation, one or several agents work through the task list, and each task is checked against its acceptance criteria. Automated testing runs after every task, and a developer performs code review before the change is merged. Final verification compares the delivered behavior with the original specification.
Linking each commit and test back to a numbered requirement creates traceability. Auditors, product owners, and new team members can then see which requirement a given piece of code satisfies and which test proves it.
What Context and Guardrails Do AI Agents Need?
AI agents need project context that describes the architecture, coding standards, and domain terminology, plus guardrails that limit what the agent may change and how its output is checked. Without context, agents produce plausible code that ignores existing patterns, and without guardrails, errors reach the main branch unnoticed. Both should live in the repositories where the agents work.
Typical context includes:
- an architecture overview and a list of approved libraries;
- coding conventions, naming rules, and error-handling patterns;
- API contracts and data schemas;
- a glossary of domain terms used in the requirements.
Many coding agents read a dedicated instruction file in the repository root, such as AGENTS.md or CLAUDE.md, for this purpose. Teams that keep such files current give every agent the same baseline knowledge.
Guardrails are the controls that constrain agent behavior. Examples include a mandatory passing test suite before merge, linters and static analysis in the CI pipeline, restricted file and command permissions, and required human approval for changes to security-sensitive modules. Guardrails work best when automated, because manual checks tend to erode under deadline pressure.
Where Does Spec-Driven Development Work Best?
Spec-driven development works best where behavior can be described and tested in advance. New products and features benefit from a clear specification at the start, while existing systems and legacy modernization benefit because the specification captures current behavior before anything is changed. Work that depends on open-ended exploration, such as early research prototypes, gains less from the method.
New Products and Features
In greenfield work, the specification defines the product before the first line of code exists. Product owners, designers, and engineers align on scope and acceptance criteria, and agents then build against that shared definition. Features with clear inputs and outputs, such as APIs, data pipelines, back-office workflows, and integrations, fit especially well.
Teams that run several features in parallel can assign separate specifications to separate agents. Interface definitions in the specifications keep parallel work compatible.
Existing Systems and Legacy Modernization
Legacy systems often lack current documentation, and the code itself is the only record of business rules. A team can first write down the existing behavior as a specification, supported by characterization tests that capture what the system does today. Agents then migrate or refactor one module at a time, and the same tests confirm that behavior has not changed.
The constraint is the quality of the available knowledge. If business rules are undocumented and no one remembers them, reconstructing the specification becomes the largest part of the project.
What Are the Benefits of Spec-Driven Development with AI Agents?
Spec-driven development with AI agents gives teams clearer requirements and fewer misunderstandings, better coordination across teams and agents, and more consistent code with easier verification. The written specification replaces scattered chat instructions and verbal agreements. Reviewers gain a fixed reference against which they can judge agent output.
What Are the Limitations of Spec-Driven Development with AI Agents?
The method has three main limitations. Creating and maintaining specifications takes time, ambiguous or outdated requirements lead to wrong output, and human review and technical judgment remain necessary. Teams should treat these as planning inputs and not as reasons to avoid the method.
Time Needed to Create and Maintain Specifications
Detailed specifications, plans, and task lists add upfront effort before any code appears. For a small bug fix or a throwaway script, that effort can exceed the cost of the change itself. Specifications also need updates whenever scope changes, and a team that stops updating them loses the benefit.
Teams should match the level of detail to the risk of the change. A short specification suffices for a low-risk change, while a payment workflow warrants full acceptance criteria.
Risks of Ambiguous or Outdated Requirements
An AI agent implements what the specification says, including its mistakes. Ambiguous wording allows several valid interpretations, and an outdated specification directs the agent toward behavior that no longer matches the business. The result can be code that passes every check and still solves the wrong problem.
Regular specification review, clear ownership, and version control in the repositories limit this risk. Each specification should carry an owner who is responsible for keeping the content current.
The Need for Human Review and Technical Judgment
Agents can generate code that compiles, passes tests, and still contains security flaws, performance problems, or design choices that conflict with the architecture. Developers must therefore review plans and code, and architects must approve decisions that affect system structure. A verification process that relies only on agent-written tests carries the risk that the tests share the agent’s misunderstanding.
Reviewing the plan before implementation and assessing the results remain mandatory steps in the process, emphasizes Dzmitry Verasau:
“Testing and manually reviewing all generated code are essential. You can try using a different AI model family for code reviews. However, this is no silver bullet.”
How Can Teams Start Using Spec-Driven Development?
Teams can start by choosing a small feature for a first trial, writing requirements and acceptance criteria, giving agents the relevant project context, reviewing the plan before implementation, and testing the result against the specification. A limited pilot exposes gaps in process and tooling at low cost. The results then show whether the method fits the team’s workflows.
Conclusion
Spec-driven development with AI agents gives teams a written, reviewable definition of what to build and a structured path from requirements to verified code. The method improves alignment, consistency, and traceability, while demanding disciplined specification upkeep and continued human review. A small pilot shows whether these trade-offs suit a given team before wider adoption.
FAQ
Who owns a specification when several teams share a product?
Each specification should have one named owner, typically the product owner of the capability it describes. Other teams contribute through review and comments but do not edit the document without the owner’s approval. Shared interfaces between teams should be defined in separate specifications with their own owners, so that changes remain visible to everyone affected.
Should specifications be stored in the same repository as the code?
Can a team switch coding agents without rewriting its specifications?
