How to Implement Spec-Driven Development with AI Coding Agents: A Step-by-Step Framework

“You describe your goal, get a block of code back, and often… it looks right, but doesn’t quite work.” That’s how GitHub’s own engineering team describes the core failure mode of vibe coding. The code compiles. The tests might even pass. But it solves the wrong problem, ignores an edge case, or quietly breaks something three files away.

Spec-driven development (SDD) is the industry’s answer: write a structured specification before you generate code, and let that spec — not a one-line prompt — become the source of truth for the AI agent. Most articles on this topic stop at explaining what SDD is. This one is different: it’s a concrete, step-by-step framework for implementing spec-driven development with real tools (GitHub Spec Kit, Kiro, Tessl), plus the pitfalls that only show up once you actually try it, based on hands-on trials published by Thoughtworks engineers.

By the end, you’ll know exactly how to set up your first spec-driven workflow, which tool fits your team, and when SDD is overkill.

What Is Spec-Driven Development?

Spec-driven development is a software methodology in which a detailed, structured specification is written and agreed upon before an AI coding agent generates any code. The spec — not the code — becomes the single source of truth for what to build and why.

It’s best understood as the AI-era descendant of two older disciplines: test-driven development (TDD), which asks developers to define expected outcomes through tests first, and behavior-driven development (BDD), which asks them to define behavior through structured collaboration. SDD asks a more fundamental question before either: have we clearly defined what we’re building, and for whom?

In practice, “spec-driven development” is not one fixed process — it’s a spectrum, and the tool you pick determines which point on that spectrum you land on.

Most teams starting out should aim for spec-anchored — it captures most of SDD’s benefits without requiring the near-total AI reliability that spec-as-source demands.

A Step-by-Step: How to Implement Spec-Driven Development

This framework combines the two most-documented public implementations — GitHub’s Spec Kit and AWS’s Kiro — into one tool-agnostic process you can adapt to whatever coding agent your team already uses.

Step 0: Establish Your Constitution (Do This Once)

Before writing your first spec, create a persistent rules file that captures your non-negotiables: tech stack, coding standards, security requirements, and architectural conventions. GitHub’s Spec Kit calls this file the constitution; Kiro calls the equivalent concept steering, split across product.md, tech.md, and structure.md .

Step 1: Specify — Define What and Why

Describe the feature in plain language, focused on user journeys and outcomes, not implementation. Who uses this? What problem does it solve? What does success look like? Deliberately leave out technical decisions at this stage.

A well-formed spec, per IBM’s guidance, should be:

• Written in clear, testable terms — inputs, outputs, data schema, edge cases, and success criteria
• Explicit about what’s out of scope, not just what’s in scope
• Lightweight enough to evolve, not a monument to every hypothetical future case

Kiro structures this as a requirements document: a list of user stories (“As a…”) each paired with acceptance criteria in GIVEN/WHEN/THEN format. Spec Kit generates an equivalent spec.md via its /specify command.

Step 2: Plan — Translate Intent into a Technical Blueprint

Now bring in the technical detail: architecture, data models, API contracts, dependencies, and any constraints from legacy systems or compliance requirements. In Spec Kit, this is the /plan command; in Kiro, it’s the design document, which typically includes a component architecture diagram plus sections for data flow, error handling, and testing strategy.

If your organization standardizes on specific frameworks or has integration constraints, this is where you state them explicitly — the agent can’t infer conventions it was never told about.

Step 3: Break Work into Small, Testable Tasks

Decompose the plan into concrete, isolated units of work — each scoped so it can be implemented and verified independently. GitHub recommends tasks like “create a user registration endpoint that validates email format” rather than a broad instruction like “build authentication”. Kiro’s task list explicitly traces each task back to a requirement number, so nothing gets built without a reason.

Step 4: Implement — Generate, Review, Verify

The agent now generates code for one task at a time. Your job shifts from writing code to verifying it: does this match the spec? Did the agent miss an edge case? Kiro adds an extra layer here — property-based tests that check behavioral rules across a range of inputs, rather than a handful of examples, to catch issues unit tests miss. Review focused, task-sized changes — not thousand-line dumps. If a task’s output doesn’t match intent, the fix starts at the spec, not the code.

Step 5: Treat the Spec as a Living Document

Once shipped, don’t let the spec go stale. In spec-anchored development, any future change starts by updating the spec first, then regenerating the plan and tasks from it. This is what actually delivers SDD’s long-term payoff: a maintained, versioned record of why the system works the way it does.

Choosing Your Tools: Spec Kit vs. Kiro vs. Tessl

Pick Kiro if your team is new to SDD and wants the simplest on-ramp. Pick Spec Kit if you want SDD to work across whatever coding agent your developers already use. Consider Tessl only once you’re ready to commit to spec-as-source for tightly scoped components — it’s still in beta.

It’s worth noting these three aren’t the whole picture. BMAD (Breakthrough Method for Agile AI-Driven Development) takes a heavier, multi-agent approach — simulating an entire agile team (Analyst, PM, Architect, Developer, QA) rather than a single spec-to-code pipeline. It’s a better fit for complex, regulated, or greenfield enterprise builds than for the day-to-day feature work Spec Kit and Kiro target.

If you want the full picture — including OpenSpec, GSD, and Hermes — Reenbit’s BMAD vs Spec Kit vs OpenSpec: Choosing Your Spec-Driven AI Framework walks through a five-question decision framework the team uses with clients.

Writing a Spec That Actually Works

IBM’s documentation offers a concrete example of a right-sized spec for a login feature — one that states acceptance criteria, explicitly lists what’s out of scope, and calls out edge cases like disabled JavaScript and expired sessions. Two rules from that guidance are worth internalizing:

• The spec should describe what, not how. Getting locked into implementation details too early defeats the purpose of separating intent from execution.
• Watch for the “over-engineering trap.” If you’re spending three weeks debating a JSON key name for a feature that might not exist next month, you’ve inverted the cost equation. The cost of refining a spec should always be lower than the cost of fixing a misunderstanding in code — once that flips, stop polishing and start building.

Common Pitfalls

• Wrong-sized workflow for small changes. Using Spec Kit’s full workflow to fix a minor bug turned it into four user stories and sixteen acceptance criteria — “using a sledgehammer to crack a nut.” Match the workflow’s weight to the size of the problem.
• Markdown fatigue. Spec-kit-style tools can generate large numbers of repetitive markdown files to review. Reviewing that volume of documentation can end up costing more time than reviewing the code directly would have.
• A false sense of control. Even with detailed specs, constitutions, and checklists, agents sometimes ignore instructions — or follow them too rigidly. More context in the window doesn’t guarantee the agent uses all of it correctly.
• Blurry line between “what” and “how.” Teams frequently struggle to keep specs purely functional, echoing a decades-old struggle with requirements documents in traditional software development.

On the technical-debt side, IBM identifies three specific failure modes that a good spec prevents: context drift (a fix in one area breaks another because the agent lacked full system context), fragmentation (new code that doesn’t match existing architectural conventions), and unnecessary operational cost (long prompting cycles burning tokens to fix errors a spec would have prevented).

That operational cost is easy to underestimate on multi-agent frameworks in particular, since each agent re-ingests its full context on every call. Reenbit’s own cost breakdown, BMAD Method: Token Budget, Context Engineering & ROI, found that context re-injection — not model output — accounts for the majority of token spend in a typical multi-agent pipeline, and shows how tiered context loading and prompt caching cut that cost by 3–10×.

Spec-Driven Development vs. Vibe Coding: When to Use Which

Kiro’s own FAQ frames the trade-off well: vibe coding keeps the speed and fun of prompting but struggles on complex tasks or large codebases, where it’s hard to track — or document for a team — every decision the AI made along the way.

Use vibe coding for prototypes, throwaway scripts, and exploratory work where being wrong costs nothing. Use spec-driven development for anything that will live in production, get maintained by a team, or touch an existing codebase where “looks right” isn’t good enough — the more complex or long-lived the system, the more SDD’s upfront cost pays for itself.

Conclusion

Spec-driven development isn’t a single tool or a silver bullet — it’s a spectrum, from a lightweight spec you write once to a spec-as-source pipeline where code is fully generated and regenerated on demand. The practical path for most teams is to start spec-first with a tool like Kiro or Spec Kit, move toward spec-anchored as specs prove their value, and reserve spec-as-source for narrow, well-understood components. Match the weight of your workflow to the size of the problem, keep specs focused on what rather than how, and treat the constitution or steering file as the highest-leverage document you’ll write.

Not sure whether SDD is worth the overhead for your codebase? That’s exactly the question worth answering before you adopt a tool. Reenbit’s team can review your setup, recommend the right point on the spec-first → spec-as-source spectrum, and help you pilot it on a real feature. Get in touch!