Spec driven development with AI

Traditional software projects often start with vague requirements that evolve during implementation. AI coding agents magnify this problem because they follow prompts literally and cannot infer hidden assumptions. Spec driven development (SDD) addresses this by writing a clear specification before coding begins. The specification becomes a contract: the agent derives code from the spec and validates its work against it. This post explores SDD with GitHub Spec Kit, Kiro, Claude Code and Codex.

Why spec driven development

Spec driven development flips the relationship between specs and code. GitHub's Spec Kit describes this as flipping the script on traditional software development, where for decades code has been king and specifications were just scaffolding. Specs capture the reasoning behind decisions and become living documents that evolve alongside the code.

In an article on Martin Fowler's site, Birgitta Boeckeler describes three levels of spec driven development. Spec-first means a well thought out spec is written first and then used in the AI assisted workflow for the task at hand. Spec-anchored means the spec is kept after the task is complete, to keep using it for evolution and maintenance of that feature. Spec-as-source means the spec is the main source file over time, the human only edits the spec and never touches the generated code. These three framings help teams decide how much process they actually need.

GitHub Spec Kit

Spec Kit is an open source toolkit that operationalises SDD. You install the specify CLI from the Spec Kit repository with uv, then scaffold a project with specify init:

specify init my-project

Once initialised, you create a project constitution and then drive the workflow with slash commands inside your agent:

• /speckit.constitution sets high level principles for the project.
• /speckit.specify creates the feature specification with requirements and constraints.
• /speckit.plan creates a technical plan outlining architecture and tasks.
• /speckit.tasks generates tasks from the plan.
• /speckit.implement executes the tasks using an AI coding agent.
• /speckit.taskstoissues turns tasks into GitHub issues for collaboration.

Additional optional commands such as /speckit.clarify, /speckit.analyze and /speckit.checklist help refine and cross-check the spec. Spec Kit treats the spec as a living document: update it when decisions change and regenerate the tasks to keep the implementation aligned.

Kiro specs

Kiro's workflow is inherently spec driven. You begin with a requirements document written in EARS (Easy Approach to Requirements Syntax) notation, which captures testable acceptance criteria in the form WHEN a condition THE SYSTEM SHALL a behaviour. The agent then generates a design document and a tasks document, breaking the work into actionable steps. Code changes happen only after the three documents exist. Every spec produces three files: requirements.md (or bugfix.md for a bug fix), design.md and tasks.md. Kiro can run independent tasks concurrently to speed up execution. Persistent project context lives in steering files such as product.md, tech.md and structure.md.

Plan based workflows in Claude Code

Claude Code does not require a full specification, but its plan mode encourages a similar discipline. Plan mode is a read-only mode where the agent researches the codebase and proposes changes without making them. You enter it with Shift+Tab, by prefixing a prompt with /plan, or with the --permission-mode plan flag. Claude presents a plan in the session for you to review, and you can open the proposed plan in your editor with Ctrl+G. Only after you approve the plan does Claude switch to a write capable mode and implement the changes. This is lighter than Spec Kit or Kiro, but it serves the same purpose: agree on the approach before any code is written.

Where Codex fits

Codex does not ship a formal multi-document spec workflow. Instead it reads standing instructions from AGENTS.md files and plans multi-file changes inside its agentic loop before executing them. If you want spec-like discipline with Codex, put your requirements, constraints and conventions in AGENTS.md and review the diffs the agent proposes. This gives you a persistent contract without the document scaffolding that Kiro and Spec Kit provide.

Differences and similarities

All of these approaches share one idea: write down what you want before coding. Spec Kit and Kiro formalise this into multiple documents with defined structures, while Claude Code offers a lighter plan mode and Codex relies on AGENTS.md plus its planning loop. Spec Kit integrates tightly with GitHub and provides commands to create specs, plans and tasks. Kiro uses EARS notation and separates requirements, design and tasks. Claude Code emphasises an approve-before-edit plan step. The right choice depends on how much process overhead your team can absorb and how complex the work is. In every case, keeping the spec or plan up to date is what prevents the agent from drifting away from the intended design.

Conclusion

Spec driven development gives AI coding agents a clear contract to follow. By defining requirements, constraints and plans before implementation, teams reduce ambiguity, enforce architecture and capture decisions for later. GitHub Spec Kit, Kiro, Claude Code plan mode and AGENTS.md driven Codex each support this workflow at a different level of formality. The discipline of writing and maintaining a specification remains the core of the practice, whatever tool you pick.