Spec-Driven Development Is Solving the Wrong Problem
2026-04-14
spec-driven-developmentsoftware-engineeringarchitectureai-first-development
2026-04-14
Spec-driven development is having its moment. Tools like Kiro, GitHub's spec-kit, and OpenSpec all promise the same thing: write structured specs before coding, let AI agents implement against them, and finally bring order to the chaos of vibe coding. The pitch is compelling. The tooling is growing fast. OpenSpec has nearly 40k GitHub stars.
But the more I look at these tools, the more I think they're repeating a pattern our industry keeps falling into: reaching for more structure and more artifacts when the real problem is putting knowledge in the right place.
Birgitta Böckeler from Thoughtworks tested Kiro on a small bug fix. The tool generated 4 user stories with 16 acceptance criteria for something that should have been a quick fix. She described it as using a sledgehammer to crack a nut. With spec-kit she found the opposite problem: too many verbose markdown files to review, repetitive with each other and with existing code. Her conclusion was direct - she'd rather review code than review all those markdown files.
This is the core tension. SDD tools create a parallel documentation layer that needs to stay in sync with the code. We have seen this fail before with Javadoc that drifted from implementations, Swagger specs that diverged from actual API behavior, and architecture diagrams that became snapshots of how things were designed rather than how they work. Adding more markdown files does not solve the "documentation goes stale" problem. It multiplies it.
Martin Fowler himself raised a pointed concern: SDD encodes the assumption that you won't learn anything during implementation that would change the specification. That assumption has been proven wrong by decades of software engineering. Requirements change. Understanding deepens. What seemed right in the spec often needs adjustment once you see the code running.
My issue with SDD is not the principle of thinking before building. That part is valuable and I practice it myself. My issue is with where SDD tools put the knowledge.
AI agents already have natural places to get project context. In my experience, the question is not "should I write specs?" but "where should each piece of knowledge live so the agent finds it without extra ceremony?"
Project-level agent files like CLAUDE.md or AGENTS.md are always loaded at the start of every session. This is where project-wide conventions belong: what libraries you use, how components are structured, what patterns to follow, how tests are organized. The agent reads this once and applies it to every task. Zero per-task overhead.
Rules files shape how the agent works. Always write tests. Never use any in TypeScript. Use European number formatting. These are behavioral constraints, lighter than project context but always active.
Skills are task-specific playbooks that get loaded only when relevant. A skill for "building a new chart component" or "writing an API endpoint" encodes your team's patterns for that specific type of work. The agent reads the skill when it needs it, not on every session. This is an underexplored pattern that I think will grow.
The codebase itself is the most honest source of truth. Existing components, tests, naming conventions, and patterns. A good agent can infer how things are built by reading what already exists. Your best chart component is the spec for how chart components are built in your project.
Issue trackers and design tools hold the per-task intent. A Jira ticket describes what needs to happen. A Figma file shows what it should look like. Both are accessible to agents via MCP without duplicating their content into markdown.
Technical contracts like OpenAPI specs, GraphQL schemas, and TypeScript interfaces are already machine-readable and already live in the codebase. They don't need a prose summary in a spec file.
When you add all of this up, the agent has: project context from CLAUDE.md, behavioral constraints from rules, task-specific patterns from skills, reference implementations from the codebase, intent from the issue tracker, visuals from Figma, and contracts from typed schemas. A spec markdown file is only needed when none of these sources adequately capture the complexity of what you're building.
I am not arguing against specs entirely. There are situations where writing a dedicated spec document is the right call:
Large, cross-cutting features where multiple stakeholders need to align on behavior and edge cases before anyone writes code. A "place an order" workflow that touches UI, API, payments, inventory, and notifications genuinely benefits from a written behavioral contract.
Features with non-obvious edge cases that the agent would otherwise invent inconsistently. What happens when payment fails mid-checkout? When inventory changed between cart and submission? When the user double-clicks submit? These details need to be written down somewhere, and a spec is a reasonable place.
New team patterns that don't have a reference implementation yet. If you're building your first chart component, a spec helps the agent understand what you want. Once that first component exists, it becomes the reference and future components need less specification.
But bug fixes? Small features? Refactors where the existing code tells the story? A spec is overhead that slows you down without adding value. The agent has your rules, your patterns, and your codebase. Let it work.
My vision is that specs should be opt-in, not the default workflow. Most daily development work should be covered by a well-maintained set of agent rules, skills, and a clean codebase with good patterns. You reach for a spec document when the complexity of a feature exceeds what those sources can communicate.
The decision boundary is simple: if you can describe the change in a ticket and the agent can implement it correctly using project rules and existing patterns, you don't need a spec. If the change involves multiple systems, stakeholder alignment, or non-obvious edge cases, write one. But keep it lightweight: behavioral intent and edge cases, not implementation instructions.
This also means the effort should go into maintaining your agent configuration (CLAUDE.md, rules, skills) rather than maintaining per-feature spec files. A well-maintained CLAUDE.md with clear conventions and reference implementations will produce better results across hundreds of tasks than a detailed spec will produce for one.
Software engineering has a recurring habit of reaching for new artifacts when things feel chaotic. The instinct is understandable, but the answer is rarely "more documents." It's usually "better-placed knowledge." SDD tools formalize that instinct into a workflow, and for most daily work the overhead is not worth it.
The teams that will navigate this well are the ones who figure out early that agent context should live where agents naturally look: in project memory, rules, skills, and the codebase itself. Not in a spec folder that requires its own maintenance lifecycle.