What is spec-driven development?

With the accessibility of AI tools and coding assistants, like Microsoft’s GitHub Copilot, Anthropic’s Claude Code or IBM’s Bob, the barrier to entry for code generation has lowered. An LLM-powered AI agent that uses sophisticated AI models, can run a series of iterative tasks in real-time at any moment, all with a single natural language prompt from the user.

For software development, this means that we can optimize and automate the development workflow for building prototypes, new features, unit tests and others. It has never been easier to generate code. However, there is a slippery slope vibe coders should be aware of: AI is only as good as the instructions it receives. 

You have likely seen technical debt in the real-world, perhaps without even realizing it. Technical debt predates vibe coding and has been part of software development for decades, accruing when shortcuts are taken in the name of speed. However, vibe coding accelerates technical debt by making it easy to generate large amounts of code without fully understanding or validating it. Perhaps there is pressure to ship quickly, or the vibe coder simply does not have the technical background to halt technical debt before it starts.  

Technical debt in AI-assisted development can take several forms: 

• Context drift occurs when a bug fix in one area inadvertently breaks functionality in another, a symptom of code that was generated without a complete understanding of the broader system.  
• Fragmentation is another common manifestation, where newly generated features fail to align with the existing architectural conventions, gradually eroding the consistency and maintainability of the codebase.  
• There is also an operational cost to consider. Without a clear specification to anchor the generation process, developers can find themselves caught in lengthy prompting cycles. This approach can consume thousands of tokens to resolve errors that a well-defined spec would have prevented entirely. 

Imagine a scenario many developers across the industry know well. You have been working on a new feature for several days or weeks, nearly ready to ship. Then, under the pressure of an approaching deadline, you rush the final tweaks through a series of AI-prompted changes.

The functions of the generated code, whether written in Python or another language, might look fine from the user’s perspective. However, in the process, several vulnerabilities have been exposed, dependency conflicts introduced and edge case handling and testing forgotten entirely.

A formal specification established upfront gives the team a shared source of truth to govern every phase of the software development lifecycle (SDLC), regardless of who was writing the code. 

There are several approaches and templates to spec-driven development with varying levels of spec maintenance and different tradeoffs. Rather than a strict “better” progression, the right choice depends on your codebase, team and problem space. Consider your team’s needs and constraints before selecting one.

In spec-first development, specification is written before any code is generated, in the form of a user story, acceptance criteria or a formal requirements document. When the initial clarity is provided and the code is generated, the spec is not necessarily maintained. The specification might grow outdated as the software evolves. Its primary purpose was to provide initial clarity without continued spec maintenance. This aspect is considered the “entry point to SDD.” ¹

In spec-anchored development, the specification evolves alongside the software. As requirements change and features are added, the spec is updated to reflect the current state of the system. This is especially useful for projects serving larger initiatives.

Automated tests serve as the bridge between documentation and implementation, often integrated into a CI/CD pipeline to ensure the two remain synchronized and executable throughout the development lifecycle. This balance of structure and flexibility makes spec-anchored development a practical and scalable approach for most engineering teams.¹

On the furthest end of the spectrum is spec-as-source development—the most AI-first form. In spec-as-source development, changes in the spec automatically trigger changes in the code. No human is ever directly refactoring the code.

This level of specification authority demands a high degree of confidence in the quality and consistency of the AI code generation pipeline, which remains inherently nondeterministic today. In practice, that means it can be less rigorous without strong human oversight. Before adopting this approach, teams should carefully evaluate the maturity of their tech stack and spec kit, the criticality of the systems involved and their capacity to validate AI-generated output.¹

In practice, many teams adopt hybrid approaches:

• Treating specs as stackable versioned artifacts, like architecture decision records (ADRs), rather than always keeping them fully up to date.
• Using external systems (for example, issue trackers) as the source of truth to introduce intentional separation.
• Avoiding heavy automation in high-complexity or community-driven projects where tight control over changes is critical.

Each approach has strengths and limitations; context matters more than strict adherence to any one model.

Depending on the level of specification authority you prefer, an effective specification might look different. However, assuming you fall somewhere in the middle of the spectrum and select spec-anchored development, a specification should describe what the system needs to do in clear, testable terms. This specification avoids getting you prematurely locked into how it will be implemented.

The spec should be detailed enough to include input and output definitions, the data schema, edge cases and success criteria. However, it should be lightweight enough to evolve as the problem becomes better understood. Above all, a good spec should accelerate development: if it’s not helping you write better code faster or reducing misunderstandings, it’s probably more detailed than it needs to be. 

To illustrate what an effective specification looks like in practice, consider this example for a user authentication feature: 

You are implementing a user login feature for a web application.  
Use the following specification as your single source of truth.  
Do not make assumptions about any requirement not listed here. 
 
FEATURE: User Login 
 
OVERVIEW: 
Allow registered users to authenticate securely using their email  
address and password. 
 
ACCEPTANCE CRITERIA: 
1. The login form must accept an email address and password 
2. If credentials are valid, redirect the user to the dashboard 
3. If credentials are invalid, display a generic error message  
   without specifying which field is incorrect 
4. Lock the account for 15 minutes after 5 consecutive failed  
   login attempts 
5. Transmit passwords over HTTPS only — never store in plain text 
 
OUT OF SCOPE: 
- Social login (OAuth) 
- Two-factor authentication 
- Password reset flow 
 
EDGE CASES: 
- Catch empty fields client-side before submission 
- Redirect expired sessions to the login page with an informational message 
- The form must remain functional if JavaScript is disabled 
 
Do not begin implementation until you have confirmed your understanding  
of the acceptance criteria.

These are similar to the functional specs product managers write, but scoped tightly to what the implementation must include, or its acceptance criteria, and how to handle edge cases gracefully.

Most commonly, this spec would live in the project repository (“repo”) on GitHub as a Markdown file likeSPEC.md or/docs/auth-login.md , versioned through Git alongside the codebase. The AI coding agent could access it by the user pasting it into the prompt or preferably, referencing the file through a CLI and the agent reading it from the project directory. For example, “Implement the feature described in /docs/auth-login.md .”

In more automated pipelines, the spec file is passed as part of the system prompt or context window at the start of the task, giving the agent its instructions before it begins.

As much time and technical debt that spec-driven development can save you, it’s also important to remember it is possible to spend too much time “over-engineering.” If you spend three weeks debating the name of a single JSON key or specific API endpoints for a feature that might be deleted in a month, this defeats the purpose of spec-driven development.  

Don’t focus too heavily on modeling every possible future. Favor lightweight, evolving specs over exhaustive, “final” ones. Write what you need to move forward, validate it quickly in code and iterate as reality changes. A general principle is that the cost of refining the spec should always be lower than the cost of fixing misunderstandings in implementation. When that balance flips, it’s a signal to stop polishing and start building.

With the emergence of AI coding assistance, test-driven development (TDD) and behavior-driven development (BDD) inspired a new wave: spec-driven development. Where TDD asks developers to define expected outcomes through tests, and BDD asks them to define behavior through collaboration, spec-driven development asks a more fundamental question first: have we clearly defined what we are building, and for whom?^2,3

As AI agents take on a larger share of the implementation work, the quality of that work becomes directly proportional to the quality of the instructions they receive. A well-authored specification does not constrain the development process, but rather accelerates it within the modern software system.