You’ve been using AI coding assistants long enough to know the pattern: you describe something, the agent builds something, it’s almost right, you nudge it, it drifts, you nudge again, and two hours later you’re not sure what you actually wanted in the first place.
That’s vibe coding — and it’s costing you more than you think.
Spec-driven development (SDD) is the structured alternative. Write a spec that captures what and why before you write code, use it as the shared source of truth for you and your AI agent, and get predictable, reviewable outcomes instead of accumulated decisions you can’t explain.
GitHub’s Spec Kit makes this concrete with a lightweight CLI and a slash-command workflow you can drop into your existing agent setup today.
This article covers what SDD actually is, how Spec Kit works end-to-end, where it shines, and where it can trip you up.
What Is Spec-Driven Development?
Spec-Driven Development (SDD) is a documentation-first approach to AI-powered software delivery. Instead of jumping straight into code, teams begin with a structured specification that defines what needs to be built, why it matters, and how it should work. That specification then guides both developers and AI tools throughout the implementation process.
The core idea behind SDD is simple: code is not the best place to define requirements. Once development starts, changes become more expensive. Architecture decisions begin to solidify, assumptions get embedded into the system, and the codebase often becomes an accidental form of documentation that is difficult to review and even harder to fully understand.
SDD changes that workflow by making intent clear before implementation begins. Rather than discovering requirements too late, teams can review, refine, and align on a shared specification upfront. The result is better collaboration, clearer requirements, and a more reliable way to use AI in modern software development.
SDD flips this: make intent explicit and reviewable before it gets encoded in code.
Three Levels of SDD
Not all “spec-first” tools are the same. Thoughtworks identifies three levels:
| Level | What it means | Maintenance cost |
|---|---|---|
| Spec-first | Write a spec for the current task; discard it after | Low — it’s a planning aid |
| Spec-anchored | Spec persists and evolves with the feature | Medium — needs upkeep |
| Spec-as-source | Spec is the primary artifact; you don’t edit code directly | High — inherit both overhead and non-determinism |
Most teams starting out benefit from spec-first or spec-anchored. Full spec-as-source is ambitious and brings its own risks.
How SDD Compares to TDD and BDD
If you’re coming from test-first practices, here’s how SDD fits in:
| Practice | Primary artifact | Main goal |
|---|---|---|
| SDD | Natural-language specs, plans, task lists | Align intent before code locks in decisions |
| TDD | Automated tests written first | Drive design and correctness via executable behavior |
| BDD | Given–When–Then scenarios | Shared vocabulary between technical and business stakeholders |
SDD doesn’t inherently guarantee test coverage the way TDD does — it primarily guarantees intent capture and artifact structure. You can layer TDD inside an SDD workflow, but don’t confuse one for the other.
GitHub Spec Kit: SDD Made Practical
Spec Kit is a small open-source toolkit from GitHub that operationalizes SDD as a CLI and a set of slash commands you use inside your coding agent.
The pitch: replace ad-hoc prompting with a repeatable phase workflow — constitution → specify → plan → tasks → implement. Each phase produces a reviewable artifact. Each artifact feeds the next.
Architecture
Spec Kit is intentionally simple:
- A Python-based CLI (
specify) for bootstrapping projects - A set of templates and helper scripts (bash or PowerShell) under
.specify/ - A constitution (
memory/constitution.md) encoding your non-negotiables - Slash commands your agent uses to drive each phase
After specify init, your repo gets:
.specify/
├── memory/
│ └── constitution.md # Your project principles
├── scripts/ # Phase helpers
└── templates/ # Spec, plan, task templates
All artifacts live in your workspace — no black boxes, no hidden state.
Supported Agents
Spec Kit is explicitly cross-agent. It supports a wide range of tools out of the box:
| Category | Examples |
|---|---|
| IDE / editor agents | GitHub Copilot, Cursor, Windsurf |
| CLI coding agents | Claude Code, Gemini CLI, Codex CLI, Qwen Code |
| Others | Kiro CLI, Amp, Roo Code, Jules |
| Bring your own | Generic mode with custom commands directory |
The Workflow: Phase by Phase
specify init → constitution → specify → clarify? → plan → tasks → analyze? → implement → iterate
Step 1: Bootstrap
# Install the CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
# Initialize in current directory, bound to your agent
specify init . --ai copilot
# Check prerequisites
specify check
Step 2: Create Your Constitution
/speckit.constitution Create principles focused on code quality,
testing standards, user experience consistency, and TypeScript strict mode.
The constitution is what the agent references throughout the entire workflow. Put your non-negotiables here: stack constraints, testing expectations, naming conventions, performance requirements. Think of it as your project-level contract.
Step 3: Write the Functional Spec
/speckit.specify Build a photo album organizer that lets users
group photos by event, tag people, and export albums as ZIP files.
This generates a PRD-style artifact focused entirely on what and why. No technical decisions yet — the spec phase explicitly excludes those.
💡 Pro tip: Your first prompt quality matters a lot here. Detailed initial requirements lead to better specs and less time fixing downstream artifacts. Don’t be vague.
If the spec has gaps, run clarify before moving on:
/speckit.clarify
Step 4: Technical Plan
/speckit.plan The application uses Vite, React, and the File System Access API.
Keep dependencies minimal.
This produces a plan plus supporting artifacts: research notes, data contracts, API specs, and a quickstart. This is where how gets decided and documented.
Step 5: Break Into Tasks
/speckit.tasks
Generates a tasks.md with ordered, dependency-aware tasks. Parallel tasks are marked [P], and each task includes the file paths where changes belong.
Optionally run a cross-artifact check before implementation:
/speckit.analyze
Step 6: Implement
/speckit.implement
The agent works through the task list using all the artifacts as context. After each implementation session, review both the code and the artifacts — update the spec if reality diverges.
What Works Well
Context durability across tools. Because artifacts live in the repo, switching agents or onboarding a new developer is much smoother. The spec and plan are already there.
Forcing decisions early. The workflow surfaces assumptions before they turn into bugs. Architecture choices become explicit and reviewable instead of scattered across Slack threads.
Brownfield modernization. Spec Kit explicitly targets existing codebases. At least one reported use case: organizing a legacy project, removing dead code, and coordinating API changes over a few weeks — meaningfully more structured than ad-hoc prompting.
Multi-step refinement over one-shot prompting. The phase structure naturally prevents “just do it all in one go” prompting, which is where most AI-assisted projects go wrong.
Where It Can Trip You Up
Artifact overhead. Spec Kit can generate a lot of Markdown — spec, plan, research notes, contracts, checklists, tasks. If reviewing all of that feels heavier than reviewing the actual code, engineers disengage and the “shared source of truth” degrades fast.
False sense of control. Templates and checklists don’t guarantee agent compliance. Agents can ignore instructions, misread research notes as requirements, or apply guidance over-zealously. More context ≠ guaranteed adherence. Plan for iteration.
Not worth it for small tasks. Applying the full constitution → spec → plan → tasks workflow to a small bug is using a sledgehammer on a nail. Adopt a “right-sized SDD” norm: full workflow for medium-to-large features, lightweight notes or nothing for small changes.
UI-heavy work is awkward. The workflow is text-first. Visual artifacts (Figma, wireframes) need to be integrated separately — Spec Kit doesn’t solve this out of the box.
⚠️ Warning: If your spec and code diverge and you stop updating the spec, you now have the worst of both worlds: maintenance overhead and misleading documentation.
Best Practices
Treat the constitution seriously. It’s not boilerplate — it’s what keeps the agent’s decisions consistent across sessions. Encode your actual standards: what testing framework you use, what you absolutely don’t want, which patterns to avoid.
Use clarify before plan. Don’t skip /speckit.clarify when the spec has open questions. Ambiguity at the spec phase multiplies at the implementation phase.
Verify don’t assume. First-draft artifacts are starting points, not finished products. The value of the workflow comes from the review-and-refine loop, not from one-shot generation.
Scope carefully. Pick changes above a threshold (say, anything touching more than two components or taking more than a day) for the full workflow. Everything else: just prompt normally.
Is It Worth It?
SDD with Spec Kit makes the most sense when the cost of misalignment is high: complex features, cross-component work, team environments, or projects where you’re switching between AI tools frequently.
For solo work on clear, bounded tasks? The overhead probably isn’t worth it.
For team-scale work on evolving systems where context gets lost between sessions and between people? The investment in structured artifacts pays back in reduced churn.
The workflow itself is solid. The tooling is lightweight. The risk is treating it as a magic process rather than a discipline that requires genuine review attention.
Start with the constitution and a single spec. See if the artifacts improve your next implementation session. If they do — build out from there.