Spec-Driven Development: Writing Specs, Not Code

The code writes itself. The spec does not.

A team at Amazon ships a feature in three days using spec-driven development. They wrote zero application code by hand. They wrote a spec: 47 lines of structured requirements, acceptance criteria, edge cases, and integration constraints. An agent read the spec and produced 2,300 lines of working code. The tests passed. The deployment went green. The feature hit production.

According to product.engineer's guide, this is spec-driven development: the practice of defining structured, machine-readable specifications that AI agents interpret and execute as working software. Instead of writing code directly, engineers write the requirements document that an agent uses to generate, test, and iterate on code autonomously. The spec becomes the source of truth. The code becomes an artifact.

The product.engineer framework for spec-driven development inverts the traditional engineering workflow. You stop being the person who types code. You become the person who defines what the code must do, how it must behave, and what constraints it must satisfy. The agent handles the implementation. You own the intent.

This matters because the role of a product engineer has always been about outcomes, not outputs. You ship working software that solves real problems for real users. Spec-driven development removes the lowest-value part of that loop (translating intent into syntax) and replaces it with the highest-value part (defining intent precisely enough that a machine can execute it). That translation from fuzzy human desire to precise technical requirement has always been the hardest part of building software. Now it is the only part that matters.

Amazon's Kiro, presented at AI Engineer Summit in 2025 (the talk has since accumulated over 48,000 views), formalized this approach for production use. Their system ingests structured specs and produces complete implementations including tests, error handling, and deployment configurations. The data from internal adoption was striking: teams using spec-driven workflows shipped 2.7x more features per sprint with 40% fewer production incidents compared to teams doing traditional development. The specs caught ambiguities and edge cases that humans typically miss during implementation because writing the spec forced the engineer to think through the problem completely before any code existed.

Why code is the wrong abstraction

For sixty years, the software industry assumed that code was the primary artifact. You hired engineers to write code. You measured productivity in lines of code, commits, or pull requests. Code reviews were the quality gate. Code was the thing.

That assumption is dissolving.

Code is not the intent. Code is one possible expression of the intent. When you write if (user.subscription.tier === 'enterprise' && user.seats > 100), you are expressing a business rule. But the code obscures the rule inside syntax, control flow, and implementation detail. The business rule is: "Enterprise accounts with more than 100 seats get volume pricing." That sentence is the spec. The code is a downstream artifact.

This distinction mattered less when humans were the only ones who could translate specs into code. You needed the code because the computer needed the code. But when an AI agent can reliably translate structured requirements into correct implementations, the code stops being the creative artifact. The spec becomes it.

GitHub's 2025 Octoverse report found that 47% of code committed to repositories with AI tooling enabled was generated by AI. At Shopify, internal metrics showed that 68% of merged pull requests in Q3 2025 contained AI-generated code. The human contribution was shifting upstream: toward problem definition, requirement specification, and review.

The product engineer who understands this shift stops optimizing their typing speed and starts optimizing their thinking speed. They invest in writing better specs, not faster code. They develop the skill of context engineering to ensure agents receive enough structured information to act correctly. And they recognize that the 25 minutes spent writing a precise spec often saves 4 hours of manual implementation and debugging.

The anatomy of an executable spec

Not all specs are created equal. A Google Doc with bullet points is not an executable spec. A Jira ticket with acceptance criteria is closer but still insufficient. An executable spec has specific structural properties that make it interpretable by an agent.

After studying how Amazon's Kiro, Vercel's v0, and OpenAI's internal tools handle specification inputs, a common structure emerges:

The five components of an executable spec

Each component serves a distinct function in the agent's execution loop. The intent statement guides overall approach. Acceptance criteria become test assertions. Edge cases prevent the most common failure modes. Integration constraints prevent the agent from reinventing existing infrastructure. Non-requirements prevent scope creep.

This structure is not arbitrary. It maps directly to how experienced engineers think through problems before writing code. The difference is that most engineers do this thinking implicitly, in their heads, while simultaneously typing. Spec-driven development makes that thinking explicit and external. You finish thinking before the agent starts working.

What makes a spec machine-readable

Three properties distinguish a spec that agents can execute from a spec that is just documentation:

Deterministic acceptance criteria. "The UI should feel fast" is not executable. "Page load completes in under 200ms for the 95th percentile of users" is executable. Every criterion must be verifiable by an automated test.

Explicit boundaries. Agents that encounter ambiguity will fill it with assumptions. Bad assumptions produce bugs. A good spec eliminates ambiguity by being explicit about constraints: "Use React Server Components, not client-side rendering." "Store state in the URL, not in local state." "Call the existing payment service at /api/v2/charges, do not create a new service."

Ordered priority. When requirements conflict (and they always do at the edges), the spec must tell the agent which requirement wins. "If PDF generation takes more than 30 seconds, return a partial result with a warning rather than timing out." Priority ordering prevents the agent from getting stuck in infinite loops trying to satisfy contradictory requirements simultaneously.

The Kiro framework: how Amazon operationalized it

Amazon's Kiro system, revealed at the AI Engineer Summit, represents the most mature production implementation of spec-driven development at scale. It is not a research prototype. It runs in production across multiple Amazon teams.

The workflow has four phases:

Phase 1: Spec authoring. The engineer writes a structured specification following a predefined schema. Kiro provides templates, but the spec is human-authored. This is the creative work. This is where product judgment lives.

Phase 2: Spec validation. Before execution begins, the system analyzes the spec for completeness, ambiguity, and internal contradictions. It asks clarifying questions. This is critical because a five-minute conversation at the spec stage prevents five hours of debugging after implementation. Kiro's validation step caught an average of 3.2 ambiguities per spec in internal testing, each one a potential bug that would have been discovered much later in traditional development.

Phase 3: Implementation. The agent generates code, tests, documentation, and deployment configuration from the validated spec. It runs tests iteratively. If a test fails, it debugs and retries. The engineer observes but does not write code. They intervene only when the agent is stuck or headed in a wrong direction.

Phase 4: Review and refinement. The engineer reviews the generated implementation against the original spec. Not line by line (that is the agent's job) but outcome by outcome. Does the PDF look right? Does the export complete in under 30 seconds? Does the error handling match what the spec required? This is the quality gate.

Internal metrics from Amazon teams using Kiro showed:

• Average time from spec to merged PR: 3.4 hours (down from 14.2 hours for similar complexity features)
• Test coverage on generated code: 87% average (compared to 64% for manually written code on the same teams)
• Production incident rate: 0.3 per 100 deployments (compared to 0.8 per 100 for manual implementations)

The test coverage number is particularly telling. Humans cut corners on tests. Agents do not. When the spec says "test these edge cases," the agent writes those tests. Every time.

What spec-driven development demands from engineers

This is not a story about engineers becoming obsolete. It is a story about the job changing shape. Spec-driven development raises the bar for the skills that actually matter and lowers the bar for the skills that were always commoditized.

Skills that become more valuable

Precise thinking. Writing an executable spec is harder than writing code. Code lets you be vague because you can muddle through ambiguity during implementation. A spec forces you to resolve every ambiguity upfront. You cannot write "handle errors appropriately" in a spec. You must specify exactly which errors can occur and exactly what happens for each one.

System design. When you are not writing code, you are designing systems. You are deciding what the components are, how they interact, what contracts they maintain. This is the architectural thinking that was always the most valuable part of senior engineering. Spec-driven development just strips away the implementation noise and makes it the primary output.

Domain expertise. An agent cannot tell you what the right product behavior is. It cannot interview users. It cannot interpret ambiguous business requirements from stakeholders. The product engineer who understands the domain deeply writes better specs, which produce better software. Domain knowledge becomes the competitive advantage, not typing speed.

Written communication. There is a direct connection between spec-driven development and the ability to communicate precisely in writing. Specs are written artifacts. Their quality depends entirely on the author's ability to express complex ideas with precision and completeness. Engineers who write well spec well.

Skills that depreciate

Raw coding speed no longer differentiates. Memorizing API surfaces matters less when the agent knows them all. Debugging syntax errors is not a skill when the agent produces syntactically correct code by default. These were never the high-value skills, but they were the visible ones. The skills that differentiate in a spec-driven world are all upstream of code.

My experience with spec-driven workflows

I started experimenting with spec-driven approaches at AWS in early 2025, initially with internal tools and later with customer-facing features. The first thing I noticed was how poorly most engineers (including myself) specify requirements when forced to make them explicit.

We think we know what we want. Then we try to write it as a deterministic spec, and we discover six ambiguities in what seemed like a simple feature. "Add a search bar to the dashboard." Search what? By which fields? What happens with zero results? Is it case-sensitive? Does it filter in real-time or on submit? What is the maximum query length? These are decisions we normally make unconsciously during implementation. Spec-driven development forces them into the open.

Having coached over 12,000 engineers and hired more than 600, I can tell you that the ability to think precisely about requirements before writing code is the single strongest predictor of engineering effectiveness I have ever observed. It correlates more strongly with output quality than years of experience, language expertise, or algorithmic knowledge. Spec-driven development formalizes this skill and makes it the primary job.

The teams I work with that have adopted spec-driven workflows report the same pattern: the first two weeks feel slower. You are writing specs instead of code, and it feels like you are not "building." By week three, the velocity difference becomes undeniable. Features land faster, with fewer bugs, and with better test coverage. By week six, nobody wants to go back.

Spec-driven development and agentic engineering

Spec-driven development is one piece of a larger shift toward agentic engineering. It answers a specific question: what does the human do when the agent writes the code? The human writes the spec.

But it connects to other patterns:

• Context engineering provides the agent with the information it needs to execute the spec correctly. A spec without context (which codebase? which existing patterns? which style conventions?) produces generic code that does not fit the system.
• Review engineering is what happens after the agent generates code. The product engineer reviews outcomes against the spec, not implementation details against their preferences.
• Iteration loops handle the cases where the first generation does not fully satisfy the spec. The engineer updates the spec or provides additional constraints, and the agent iterates.

Together, these patterns form the workflow of the modern product engineer: specify, provide context, review outcomes, iterate. None of these steps require writing code by hand. All of them require deep product and technical judgment.

Getting started with spec-driven development

You do not need Amazon's Kiro to start practicing spec-driven development. The principles apply with any AI coding tool.

A practical starting framework

1. Before you open an editor, write the spec. Use the five-component structure: intent, acceptance criteria, edge cases, integration constraints, and non-requirements. Keep it in a markdown file at the root of the feature branch.

2. Feed the spec to your agent. Whether you are using Claude Code, Cursor, or GitHub Copilot Workspace, paste the full spec as the initial prompt. Let the agent ask clarifying questions. Answer them, then add those answers to the spec.

3. Review against criteria, not code. When the agent produces an implementation, do not read every line looking for style issues. Run the acceptance criteria. Do the tests pass? Do the edge cases behave correctly? Does it integrate with existing systems as specified?

4. Iterate on the spec, not the code. If something is wrong, do not manually fix the code. Update the spec to be more precise, and let the agent regenerate. This keeps the spec as the source of truth and prevents drift between what you specified and what exists.

5. Version the spec with the code. The spec file ships with the PR. Future engineers (and future agents) can read the spec to understand intent, not just implementation. This is documentation that writes itself because it was written first.

Common mistakes

Under-specifying edge cases. The happy path is easy to specify. The failure modes are where bugs live. Force yourself to enumerate at least five edge cases for every feature, even simple ones.

Over-specifying implementation. The spec should say what, not how. "Sort the list alphabetically" is a spec. "Use Array.prototype.sort with a locale-aware comparator" is an implementation detail. Let the agent choose the how unless you have a specific constraint.

Skipping the non-requirements. Without explicit non-requirements, agents will over-build. They will add features you did not ask for because they seemed logical. "Does not support bulk export" prevents the agent from spending three hours building bulk export when all you needed was single-item download.

The economics of spec-driven development

The economic argument is straightforward. In traditional development, the bottleneck is implementation. A senior engineer costs $200-400 per hour fully loaded. They spend 60-70% of that time writing and debugging code. Spec-driven development shifts their time to the 30-40% that was always the high-value work: understanding problems, designing solutions, and validating outcomes.

Stripe's internal productivity research (shared at their 2025 engineering offsite, later referenced in their engineering blog) found that their most impactful engineers spent less than 40% of their time writing code even before AI tools. They spent the majority on specification, review, and cross-team coordination. Spec-driven development is not a radical change for these engineers. It is a formalization of what they were already doing.

For teams adopting this approach, the math works out clearly. A feature that took one engineer five days now takes one engineer two days (one day specifying, one day reviewing and iterating). The three days saved compound across dozens of features per quarter. At scale, this is not a marginal improvement. It is a structural change to engineering economics.

Key takeaways

• Spec-driven development treats the specification as the primary creative artifact and code as a downstream output.
• Engineers define intent, acceptance criteria, edge cases, and constraints; agents generate the implementation.
• A feature that took five days now takes two (one day specifying, one day reviewing and iterating).
• The spec must be machine-readable, structured, and precise enough for agents to execute without ambiguity.
• This approach compounds at scale, creating a structural change to engineering economics across dozens of features per quarter.

FAQ

What is spec-driven development?

Spec-driven development is the practice of writing structured, machine-readable specifications that AI agents interpret and execute as working software. Engineers define what the software must do (intent, acceptance criteria, edge cases, constraints) and agents generate the implementation. The spec is the primary creative artifact; the code is a downstream output.

Does spec-driven development replace software engineers?

No. It changes what engineers do, not whether they are needed. Spec-driven development requires deeper product thinking, system design skill, and domain expertise. It removes the manual translation of intent into syntax. The engineering judgment required to write a good spec is the same judgment that made someone a good engineer before AI tools existed.

What tools support spec-driven development today?

Amazon's Kiro is the most formalized implementation. However, the principles work with Claude Code, Cursor, GitHub Copilot Workspace, Vercel's v0, and any AI coding assistant that accepts structured input. The key is providing the agent with a complete spec rather than ad-hoc instructions. The tool matters less than the discipline of specifying before generating.

How is spec-driven development different from writing good tickets?

Good tickets describe intent for humans. Executable specs describe intent for machines. The difference is precision: tickets can contain ambiguity because a human implementer will ask questions or make reasonable assumptions. Specs must be unambiguous because agents will fill gaps with potentially wrong assumptions. A good spec eliminates every ambiguity a ticket would leave open.

Can junior engineers do spec-driven development?

Junior engineers can start but will produce weaker specs initially because they have less intuition about edge cases, system constraints, and failure modes. Spec-driven development raises the floor of output quality (the agent writes good code regardless of the spec author's coding ability) but the ceiling is still determined by the engineer's ability to think through problems completely. The skill develops with practice and mentorship.

Related reading

• What Is a Product Engineer?
• Context Engineering: The Skill That Replaced Prompt Engineering
• Agentic Engineering: How Product Engineers Build with AI
• Written Communication for Product Engineers
• Don't Build Agents, Build Skills