Spec-driven development, with AI doing the heavy lifting
Coding agents have gotten impressively good at generating code from a description. But the output can still miss the mark: code that doesn't compile, solves only part of the problem, or ignores the intended architecture. The gap usually isn't the model's coding skill—it's the input. Treating an agent like a search engine and expecting it to infer every unstated requirement is a recipe for guesswork.
A new open source toolkit from GitHub, Spec Kit, aims to fix that by making the specification itself the engine of development. Instead of writing a spec and shelving it, the spec becomes a living artifact that drives implementation, task breakdowns, and checklists. The developer's job shifts from writing every line of code to steering and verifying what the agent produces.
Four phases, each with a checkpoint
Spec Kit structures work into four sequential phases. The rule: don't advance until the current phase's output has been reviewed and validated.
- Specify: You give a high-level "what" and "why"—the user journeys, experiences, and outcomes that matter. The agent generates a detailed specification capturing who the users are, what problem it solves, and how success looks. Technical stacks are deliberately left out of this phase.
- Plan: Here you introduce the technical constraints. Provide your stack, architecture, compliance rules, or performance targets, and the agent produces a technical plan. If your internal docs are accessible, the agent can incorporate your architectural standards directly. You can also request multiple plan variations to compare approaches.
- Tasks: The spec plus plan gets decomposed into small, reviewable chunks. Each task should be implementable and testable in isolation—e.g., "create a user registration endpoint that validates email format" instead of "build authentication." This granularity gives the agent a way to validate its own work.
- Implement: The agent works through the task list, one item at a time or in parallel where it makes sense. Instead of reviewing a thousand-line diff, you review focused changes that solve a specific, well-defined problem.
The process leans on explicit checkpoints at each phase where you reflect and refine. Does the spec capture your intent? Does the plan respect real-world constraints? Are there gaps or edge cases the agent missed? The AI generates artifacts; you verify they're correct before moving forward.
Getting started with Spec Kit
Spec Kit integrates with coding agents including GitHub Copilot, Claude Code, and Gemini CLI. Setup begins with installing the specify command-line tool, which initializes your project directory structure.
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>From there, you steer the agent with three slash commands:
/specify— provide your high-level prompt and the agent generates the full specification, focused on the "what" and "why."/plan— supply your technical direction and constraints, and the agent produces a detailed implementation plan./tasks— the agent translates the spec and plan into a list of actionable, ordered tasks for implementation.
This workflow converts a vague prompt into explicit intent the agent can execute reliably, without needing to read your mind about unstated requirements.
Why upfront specificity beats prompting
Large language models excel at pattern completion, not telepathy. A prompt like "add photo sharing to my app" forces the model to guess at potentially thousands of unstated assumptions. Some guesses will be wrong, and you may not discover which until deep into implementation. A clear specification, technical plan, and focused task list eliminate much of that ambiguity—the agent knows what to build, how to build it, and in what order.
This holds across technology stacks. Whether the project is in Python, JavaScript, or Go, the underlying challenge is the same: translating intent into working code. The spec captures intent, the plan encodes technical decisions, and the tasks break it into implementable pieces.
For larger organizations, Spec Kit also provides a centralized place for requirements that often live in scattered wikis, Slack threads, or individual heads. Security policies, compliance rules, and design system constraints can go directly into the spec and plan, where the agent can actually use them—baked in from day one rather than retrofitted later.
The iterative nature is another advantage. Unlike traditional development, where early decisions tend to lock you in, spec-driven development makes course correction straightforward: update the spec, regenerate the plan, and the agent handles the rest.
Where this approach shines
Spec-driven development with tools like Spec Kit is particularly effective in three contexts:
- Greenfield projects: A modest upfront investment in writing a spec and plan ensures the agent builds what you intend, rather than producing a generic solution from common patterns.
- Feature work in existing codebases: Specifying a new feature forces clarity on how it should interact with the existing system. The plan encodes architectural constraints so new code feels native to the project. Advanced context engineering practices may be needed for complex systems, which will be covered separately.
- Legacy modernization: When original intent has been lost over time, you can capture the essential business logic in a fresh spec, design a new architecture in the plan, and let the agent rebuild the system from scratch without inheriting technical debt.
The core benefit is separating the stable "what" from the flexible "how," allowing for experimentation and rapid iteration without expensive rewrites.
Intent as the source of truth
The broader shift underway is from "code is the source of truth" to "intent is the source of truth." As AI makes specifications directly executable, the spec becomes the definitive artifact that determines what gets built. Spec Kit is GitHub's experiment in making that transition practical—open sourced because the process itself is the innovation, larger than any single tool or vendor.
Future coverage will explore combining spec-driven practices with context engineering for more advanced capabilities. GitHub is also seeking input on improving the workflow's usability, potential VS Code integrations, diffing multiple implementations, and managing specs at organizational scale. Feedback and ideas can be shared on the Spec Kit issue tracker.
