TL;DR: Spec-driven development for AI agents works by anchoring every code-generation session to a structured specification document, so the model always knows the intended behavior and cannot silently drift toward a different interpretation. Tools like Kiro, BMAD-METHOD, and GitHub Spec Kit formalize this contract upfront. Inside Claude Code, loading a completed spec before any prompt eliminates the regenerate-from-scratch cycles that kill multi-session feature work.
Key Takeaways
- Intent drift is the core failure mode: AI coding agents produce code that compiles and runs but misses what the feature was supposed to do.
- A spec is a contract, not documentation: a structured spec file gives the AI a fixed source of truth instead of gap-filled assumptions.
- Four main tools enforce spec-first workflows differently. Choose GitHub Spec Kit for editor-agnostic repo workflows, Kiro or BMAD-METHOD when pipeline enforcement is the bottleneck, and OpenSpec when drift happens at the service-boundary layer.
- Claude Code needs a spec anchored to every session. Without one, each prompt resets context and the agent drifts from original feature intent.
- Spec-driven development front-loads decision-making. That upfront cost can eliminate the larger cost of rebuilding code that runs correctly but serves the wrong purpose.
Introduction
Claude Code and similar agentic coding tools are now daily infrastructure for many senior engineering teams. The velocity gains are real, and so are the failure modes practitioners keep pushing back on.
The failure mode that keeps surfacing: agents produce syntactically correct code that completely misses what the feature was supposed to do. Each new session resets the agent's understanding, and gap-filling begins again.
The real insight is not documentation discipline. It is architectural: a spec is the stateful memory layer Claude Code was never designed to have.
Why do AI coding agents drift from the original feature intent?
AI coding agents drift from feature intent because they have no persistent memory of prior decisions, and each new prompt resets their understanding of what the feature is supposed to do.
Claude Code has a finite context window. Decisions made in session 1 (your data model, error-handling approach, auth pattern) are invisible by session 3 unless you explicitly reload them. The agent fills that gap with statistically plausible code, and that code may compile while being wrong for your feature's actual purpose.
This is an architectural problem with context window amnesia across sessions, not an AI quality problem. A spec is the architectural fix.
What does a spec artifact actually contain, and how does it work as an executable contract?
A spec is not a requirements document. Requirements describe what the business wants; a spec describes what the AI is allowed to build. As Augment Code puts it: SDD turns specifications into executable contracts that constrain what AI agents generate. That word "constrain" marks a real difference between guiding the AI and governing it.
Based on practitioner guidance, a useful spec artifact typically addresses at minimum: a plain-English feature intent statement, data contracts and validation rules, an explicit list of behavioral boundaries, and a log of architectural decisions already made. The goal is to leave the agent as little room as possible to fill gaps with assumptions.
Heeki Park's spec-driven Claude Code workflow is the clearest practitioner example available as of July 2026: spec written first, committed to the repo, explicitly loaded at every session open.
Which spec-driven tool fits your team: GitHub Spec Kit, Kiro, BMAD-METHOD, or OpenSpec?
As of July 2026 GitHub Spec Kit, Kiro, BMAD-METHOD, and OpenSpec all enforce spec-first workflows, but they sit in different places in your stack and suit different compliance bottlenecks. As a practical rule of thumb used in this guide: choose GitHub Spec Kit for editor-agnostic repo workflows, Kiro or BMAD-METHOD when pipeline enforcement is the bottleneck, and OpenSpec when drift happens at the service-boundary layer rather than the feature-logic layer.
GitHub Spec Kit was open-sourced by GitHub as a repo-native, editor-agnostic toolkit. It is worth considering for teams that want spec-first workflows without changing their existing tooling or introducing new dependencies.
Kiro is among the tools analyzed in independent landscape reviews as taking a spec-first approach to AI-assisted development. Its inclusion in those reviews reflects its positioning around spec compliance in the workflow, which matters most when teams have a habit of skipping optional steps under deadline pressure.
OpenSpec sits closest to the OpenAPI tradition and is most relevant when drift happens at the service-boundary layer rather than the feature-logic layer.
| Tool | Enforcement model | Where it lives | Best for |
|---|---|---|---|
| GitHub Spec Kit | Repo-native markdown | Repo (any editor) | Any team, any editor, no new tooling |
| Kiro | Spec-first workflow integration | IDE and pipeline | Teams prioritizing spec compliance enforcement |
| BMAD-METHOD | Agent orchestrator | Multi-agent pipeline | Multi-agent coordination and pipeline control |
| OpenSpec | API schema contract | Service boundary layer | Service-boundary drift prevention |
How do you apply spec-driven development inside a Claude Code session, step by step?
Write and commit a structured spec file first, then open every session by explicitly loading that spec into Claude's context before any implementation prompts.
The following workflow is the framework used in this guide, synthesized from practitioner examples including Heeki Park's documented approach.
- Write the spec before opening Claude Code. This is the actual work, not overhead on top of it. The spec defines what the agent is allowed to build before generation begins.
- Commit the spec to the repo. It becomes the source of truth, not a temporary notepad that disappears after the session.
- Open every session with an explicit spec load. Start with: "Read
specs/feature-name.mdand treat it as the authoritative contract for this session. Do not deviate from the data contracts or behavioral boundaries defined there." - Anchor decisions to the spec during generation. When the agent proposes something ambiguous, ask: "Does this match the behavioral boundaries in the spec?"
- Update the spec, not just the code, when requirements change. A stale decision log is drift waiting to happen.
FAQ
Does spec-driven development slow down initial development speed? Writing a spec adds upfront time; for multi-session features, that cost is typically recovered by eliminating mid-feature regeneration cycles. For single-prompt tasks, the overhead is likely not worth it. The tradeoff is most favorable on work that extends across sessions, where the alternative is spending hours rebuilding code that ran correctly but served the wrong purpose.
How does a spec-first approach differ from using a CLAUDE.md file in Claude Code? A CLAUDE.md file is a convention. Claude reads it if you tell it to, but nothing in the tooling enforces compliance. Spec-first tools position the spec as the source of truth before generation begins, which changes where in the workflow the constraint is applied, from optional context to enforced contract.
What is the difference between GitHub Spec Kit and BMAD-METHOD for agentic AI workflows? GitHub Spec Kit is repo-native and editor-agnostic, providing structured spec and workflow without imposing new tooling. BMAD-METHOD targets multi-agent pipeline coordination. A hands-on comparison across 13 dimensions covering both is the best place to evaluate them against your specific workflow.
Conclusion
The spec is an architectural artifact, a stateful memory layer that compensates for the context-window amnesia Claude Code was never designed to overcome. As of mid-2025, the tooling landscape has matured enough that spec-first workflows are practical for any team size, but tooling choice matters less than the practice itself: commit the spec to the repo, load it into every session, and update it when requirements change. The teams that fail are most often those who write a spec once and never reference it again.
The spec does not make the AI smarter. It makes the AI accountable to a decision you already made.
Pick one feature currently in development, write a spec using GitHub Spec Kit's open-source structure, commit it, and open the next Claude Code session by loading it explicitly. One feature, one session. The practice is easier to evaluate by doing it than by reading about it.
Learn from me
Claude Code in Practice, my Maven cohort. Master Claude Code from fundamentals to advanced orchestration: skills, subagents, hooks, MCP, and production automation. Join the next cohort →
Hire us
Traversaal.ai. We're a team of forward deployed engineers solving the toughest AI problems for Fortune 100 companies: document intelligence, agentic data platforms, and real-time web intelligence, deployed in production. Work with our team to deploy your next agentic ecosystem. Talk to Traversaal.ai →
Join us
Want to solve these problems with us? We're always looking for forward deployed engineers who want to ship production AI. jobs@traversaal.ai
