This post was also published on Elevate Tech Blog on Medium
Introduction
You're prompting your AI coding assistant, iterating on a feature. Within an hour, you have working code. This is vibe coding: spontaneous AI-assisted development that feels magical.
Then reality hits. No tests. No documentation. No architectural plan. Just 1,200 lines of AI-generated code nobody fully understands. When asked "why did we implement it this way?", you have only chat history. That's technical debt, not documentation.
Spec-driven development (SDD) offers a better approach: specifications become executable artifacts that generate implementations. This article compares three SDD tools (spec-kit, Kiro, and OpenSpec) and shows when to use each.
The Problem with Vibe Coding
Vibe coding feels powerful: describe what you want, watch code appear. But it breaks down at scale:
- No architectural alignment: Each feature optimized for the moment, not the system
- Impossible validation: Can't test against non-existent specifications
- Lost knowledge: Decisions buried in code, context leaves with team members
- Inconsistent patterns: Same problem solved five different ways
- Nothing transfers: Best practices stay tribal knowledge
Bottom line: Vibe coding optimizes for the first iteration. Spec-driven development optimizes for the next hundred.
What Is Spec-Driven Development?
SDD inverts the traditional relationship: specifications become executable artifacts that generate implementations, not just guidance.
For decades, code was king. Documentation was aspiration. They inevitably drifted apart.
SDD flips this: code serves specifications. When specs directly generate code, there's no translation layer, no drift, no ambiguity. AI makes this possible by understanding complex specifications and producing implementations.
The implications: Maintaining software means evolving specifications. Debugging means identifying which spec generated incorrect behavior. Code becomes regenerated output (important, but no longer the primary artifact).
Core Principles
Specifications Drive Development Teams discuss specs, not implementation details. Code expresses specifications in a particular language.
Precision Enables Execution "The system should be fast" won't work. "API responses complete within 200ms at p95 under 1000 concurrent users" will.
Continuous Refinement AI analyzes for ambiguity, contradictions, and gaps. Specifications improve through ongoing dialogue.
Reality Feeds Back Production metrics update specifications. Performance bottlenecks become requirements. Security incidents become constraints.
Three Tools for Spec-Driven Development
These principles sound compelling in theory, but how do you actually practice SDD? Three tools operationalize these concepts, each optimized for different scenarios: spec-kit for comprehensive greenfield projects, Kiro for integrated IDE experiences, and OpenSpec for lightweight brownfield development.
spec-kit: Comprehensive Governance
What it is GitHub's open-source CLI toolkit for greenfield projects (0→1) requiring extensive governance and validation. Integrates with 15+ AI assistants including Claude Code, Copilot, Cursor, and Gemini.
Workflow
Five core commands (plus optional clarify step):
- Constitution (
/speckit.constitution) - Define immutable architectural rules - Specify (
/speckit.specify) - Describe what to build (functional requirements only) - Clarify (
/speckit.clarify) - Optional: Fill requirement gaps through structured questioning - Plan (
/speckit.plan) - Specify tech stack, generates 8+ files (architecture, data models, API contracts) - Tasks (
/speckit.tasks) - Create ordered task list with dependencies - Implement (
/speckit.implement) - Generate tested, documented code
Unique advantages
- Constitutional principles ensure consistency across all features
- Extensive validation with checklists at every step
- Research integration for informed tech stack decisions
- Template-driven constraints prevent common LLM failures
- Complete audit trail from requirements to implementation
Best for Large greenfield projects, enterprise governance, detailed audit trails, complex tech stack decisions
Avoid for Small features (high overhead), quick iterations, teams preferring minimal documentation
Kiro: Integrated IDE Experience
What it is Standalone desktop IDE (VS Code-based) with built-in SDD for macOS, Windows, and Linux. Unlike CLI toolkits, Kiro provides a complete development environment where specs, code, and AI assistance live together.
Workflow
Three-step process with visual UI:
- Requirements - Write user stories with acceptance criteria in GIVEN/WHEN/THEN format (requirements.md)
- Design - Define architecture, data flow, error handling, testing approach (design.md)
- Tasks - Generate actionable task list with built-in UI to run and review changes (tasks.md)
Steering files guide AI behavior across all features: product.md (goals), tech.md (standards), structure.md (organization).
Unique advantages
- Built-in spec management UI (no context switching between tools)
- Hooks for workflow automation (auto-run tests on save, sync translations, spell-check docs)
- One-click VS Code migration (imports extensions and settings)
- MCP server support (connect external tools and data sources)
- Lowest learning curve of the three tools
Best for All-in-one IDE solution, developers new to SDD, workflow automation needs, simple to medium features
Avoid for Very small bugs, CLI-only workflows, extensive customization needs
OpenSpec: Lightweight Brownfield Development
What it is Lightweight CLI toolkit designed for brownfield projects (1→n), where you're evolving existing codebases rather than building from scratch. Works with 20+ AI tools via native slash commands or AGENTS.md. No API keys required.
Workflow
Four-step process with delta-based specs:
- Proposal (
/openspec-proposal) - Create change folder with proposal, tasks, and spec deltas (ADDED/MODIFIED/REMOVED) - Review (
openspec show,openspec validate) - Iterate until team alignment - Implement (
/openspec-apply) - AI works through tasks referencing agreed specs - Archive (
openspec archive --yes) - Merge updates into source of truth, move to archive
Two-folder model: specs/ (truth), changes/ (proposals), archive/ (completed).
Unique advantages
- Delta-based specs show exactly what changed (not full rewrites)
- Clean separation of current state vs. proposed changes
- Minimal overhead (4-5 files per change vs. spec-kit's 8+)
- Change tracking built-in with archive workflow
- Optimized for cross-spec changes spanning multiple features
Best for Brownfield projects, changes spanning multiple specs, minimal overhead, clear change tracking
Avoid for Complete beginners (less guidance), highly opinionated workflows needed, greenfield (0→1) projects
Common Pitfalls
1. Verbosity Overload
Problem: Too many markdown files to review Solution: Start with smaller features, adjust workflow
When specs become more tedious to review than code itself, you've defeated the purpose. Match documentation depth to problem complexity.
2. False Sense of Control
Problem: AI ignores instructions despite specs Solution: Keep specs focused, validate frequently
Larger context windows don't guarantee AI will follow every instruction. Just because specs exist doesn't mean implementation will be perfect. Validate early and often.
3. Over-Engineering Small Tasks
Problem: Using "sledgehammer to crack a nut" Solution: Match tool complexity to problem size
Not every bug fix needs a full specification workflow. Reserve SDD for features where upfront design prevents costly refactoring.
4. Review Burden
Problem: Reviewing specs harder than reviewing code Solution: Use deltas or simpler workflows
If your team finds extensive markdown review tedious, you're creating resistance to adoption. Choose tools and processes that fit your team's preferences.
Success pattern: Start with a pilot project. Establish principles. Create precise specs. Generate and validate implementations. Run retrospectives. Scale gradually based on learnings.
Conclusion
AI changes the equation. When specs directly generate implementations, traditional trade-offs reverse:
- Precision cheaper than ambiguity
- Documentation free (generated from specs)
- Pivots systematic (regenerate from updated specs)
- Quality enforceable (constitutional principles)
- Knowledge retained (specs outlive developers)
Vibe coding optimizes for the first iteration. SDD optimizes for the entire lifecycle.
Vibe coding still works for throwaway prototypes and personal projects. But for systems that matter (maintained, scaled, compliant, long-lived), spec-driven development is necessary.
The tools exist: spec-kit, Kiro, OpenSpec. Early adopters see 10x code quality improvements and dramatic technical debt reductions.
The question isn't whether to adopt SDD, but how quickly you can build competency before competitors do.
Start small. Pick one project. Establish principles. Write specs. Generate implementations. Validate. Learn. Iterate.
The future is writing specifications that generate code. That future is here.
Get Started
spec-kit
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init my-project --ai claude
github.com/github/spec-kit | Works with 15+ AI assistants
Kiro
Download for macOS, Windows, Linux: kiro.dev docs.kiro.dev | Integrated specs, hooks, MCP support
OpenSpec
npm install -g @fission-ai/openspec@latest
openspec init
github.com/Fission-AI/OpenSpec | Works with 20+ AI tools
Pick one. Start small. Build competency. Don't wait for competitors.
Are you using spec-driven development in your organization? What challenges have you encountered? What successes have you achieved? Share your experiences in the comments below.