Vibe coding got you here fast. Spec-Driven Development keeps you from rebuilding everything in 18 months. Here's the honest case for making the switch — and how tools like Kiro and Claude make it practical.
~3 min read · Senior Architect's Perspective
TL;DR
- Vibe coding (prompt → code) is great for prototypes and solo work — but doesn't scale to production teams or long-lived systems.
- Its core flaw: the AI has no memory of your architectural decisions, so every session risks contradicting the last.
- Spec-Driven Development (SDD) fixes this by making a machine-readable spec the persistent context for every AI code generation call.
- The spec encodes your domain boundaries, layer rules, and security requirements — so the AI executes a plan, not a guess.
- Kiro manages specs as repo artefacts; Claude authors and reasons over them. Together they cover the full workflow.
- Start with three files: a domain model spec, an ADR set, and a security NFR catalogue. One sprint is enough to begin.
Velocity without direction is just fast drift
Vibe coding works. Until it doesn't. The inflection point is usually around the time you need your second engineer, your first compliance audit, or your third refactor of the same module.
Describing what you want in plain language and watching an AI build it is genuinely powerful. Prototypes that took days now take hours. That is real. But an LLM generating code has no memory of the architectural decisions you made last week, no awareness of the security boundary your team agreed to, and no stake in the codebase's health six months from now. It optimises for the prompt. Every time.
The result is not bad code, exactly. It's code that makes local sense but accumulates global incoherence — business logic bleeding into HTTP handlers, no consistent layering, security rules applied in some places but not others. Technical debt at machine speed.
| 🟠 Vibe Coding | 🟢 Spec-Driven Development | |
|---|---|---|
| Approach | Prompt → code, right now | Spec → constrained code |
| Strengths | Extremely fast first draft | Slower start, faster long term |
| Great for PoCs and solo work | Built for team + production | |
| Low barrier to entry | Architectural rules enforced | |
| AI fills architectural gaps | AI executes a human-authored plan | |
| Risks | ⚠️ No persistent design intent | ✅ Security as a first-class input |
| ⚠️ Compounds into mixed concerns | ✅ Spec is the persistent memory |
What Spec-Driven Development actually means
SDD is not a framework, a tool, or a process overhaul. It is one discipline: write a machine-readable specification before you prompt the AI to generate code — and feed that spec as context on every generation call.
The insight is simple: an AI model is only as good as the context it receives. Give it a well-formed specification encoding your domain boundaries, your layering rules, your security requirements, and your acceptance criteria, and it generates code that actually belongs in your system. Give it a vague prompt and you get plausible-looking code that may or may not fit.
⚠️ The Specification Vacuum
Every AI code generation call is stateless. The model does not remember that you chose event sourcing for your order service, or that your team banned direct DB access from the HTTP layer. Without a persistent spec the AI can read, every session risks contradicting a previous one.
The spec-first workflow
The difference between a vibe prompt and a spec-grounded prompt is the difference between "build me a login endpoint" and this:
Context: @requirements.spec.md @domain-model.spec.md @architecture.spec.md
Task: Implement LoginUseCase in the Application layer.
- Must satisfy NFR-SEC-01 (bcrypt ≥12), NFR-SEC-02 (rate limit 5/min)
- Must emit AuthenticationAttempted domain event
- Must NOT import infrastructure — use IUserRepository port only
- Write unit tests alongside implementation
Do NOT generate controllers, routes, or HTTP types.
The AI is no longer free-forming. It is executing a plan written by engineers who understand the system. Security rules are constraints, not afterthoughts. Layer boundaries are instructions, not suggestions.
Kiro and Claude as spec-first partners
These two tools approach SDD from complementary angles. Used together, they cover the full workflow from spec authoring to code generation.
| Kiro (IDE-Native) | Claude (AI Reasoning) | |
|---|---|---|
| What | Amazon's agentic IDE treats specs as first-class project artefacts that live in the repo alongside code — not in a chat history that disappears. | Claude's large context window and instruction-following make it the ideal spec authoring and code generation partner when specs are supplied as context. |
| Key features | Spec files committed to version control | 200k context — full spec sets fit in one session |
| Agents reference specs on every task | Strong domain modelling from natural language | |
| Steering docs enforce architectural rules | Generates ADRs and spec docs from discussions | |
| Hook system for spec-compliance checks | Enforces layer rules when explicitly stated | |
| Built for multi-session continuity | Claude Code integrates spec files as project context |
✅ Recommended Pairing
Use Claude to author specs — domain model discussions, ADR drafting, security NFR catalogues. Commit those files to your repo. Use Kiro's agent to execute code generation tasks against that persistent spec. Each tool does what it does best.
When to vibe, when to spec
This is not a case against vibe coding everywhere. It is a case for knowing when structure earns its cost.
| Context | Approach | Why |
|---|---|---|
| Hackathon / throwaway PoC | 🟠 Vibe | Code gets discarded. Speed wins. |
| Solo project, no compliance risk | 🟠 Vibe | No team alignment needed. |
| Early MVP, shape still unknown | 🔵 Lightweight spec | Domain model only, skip full arch spec until stable. |
| Production service, team of 3+ | 🟢 Spec-Driven | Multi-session continuity requires persistent context. |
| Regulated domain (finance / health) | 🟢 Spec-Driven | Compliance requirements must be first-class spec citizens. |
| Greenfield platform, 2+ year horizon | 🟢 Spec-Driven | Best time for discipline is before debt accumulates. |
Your first spec-driven sprint
You do not need to rewrite your codebase. You need three artefacts and a habit.
Artefact 1 — Domain model spec. Open a Claude session and describe your system's problem domain in plain language. Ask it to produce a domain model — entities, boundaries, events, rules. Review it with your team. Commit it as docs/specs/domain-model.md.
Artefact 2 — Architecture Decision Records. For each significant architectural decision — your database, your auth mechanism, your service boundaries — write a one-page ADR using Claude. Store them in docs/adr/. These become standing instructions for every future AI prompt in that area.
Artefact 3 — Security NFR catalogue. Add your security non-functional requirements as numbered, referenceable statements. Tie them to specific modules. Reference them in every AI task prompt that touches authentication, data handling, or external integrations.
✅ One Sprint Is Enough to Start
Dedicate one sprint to these three artefacts before writing new feature code. Teams that do this report dramatically more predictable AI-assisted development — and code reviews shrink because the spec handles the architectural discussion before the PR exists.
The vibe was never the problem
Vibe coding gave developers something real: the ability to translate intent into implementation at a speed that was previously impossible. Dismissing it would be a mistake.
But velocity without direction is not progress — it's drift. The AI can only execute, at enormous speed, whatever you point it at. A spec is what you point it at. That is the entire argument.
References: Andrej Karpathy — "Vibe Coding" (2023) · Amazon Kiro Documentation (2025) · Anthropic Claude Docs (2025) · McKinsey Technology — Developer Productivity & AI Report (2024) · Michael Nygard — Documenting Architecture Decisions (2011)
Top comments (0)