Spec-Driven Development with Claude Code — one year later, retrospective
A year ago I wrote about SDD as a methodology. After 12 months of heavy use I have data: what actually pays off, what I no longer recommend, and when SDD hurts.
12 months ago I wrote a post on Spec-Driven Development in Claude Code. The methodology: requirements → design → tasks → implementation, each step as an artifact in .kiro/. A year later I have enough data to assess what works and what doesn't.
What held up
1. Requirements as EARS are a game changer
Format: When [event], the system shall [response]. Forces "conditions + behavior" thinking rather than "nice feature to add".
After a year: 90% of requirements I write in EARS are easy to test, easy to review. Disproportionately more than user-stories.
2. The design phase saves time
Writing design.md before code in the style "documenting architectural choices, alternatives I considered, why I picked this", pays back 3:1.
Concretely: last feature (auth refactor), 1 hour of design + 4 hours of code = 5h total. Previously (without design) similar work took 8h, with 2 false starts.
3. Spec → tasks decomposition works great with AI
The agent gets requirements.md + design.md, spits out tasks.md with a concrete list. 80% of tasks are well-broken-down. 20% need manual cleanup. Acceptable.
What did NOT hold up
1. Strict gating between phases
Original idea: don't start design until requirements are accepted, don't start implementation until tasks are accepted.
In practice: between design and implementation I revisit requirements many times. Strict gating is LARP. Real-world workflow is zigzags.
What I changed: moved to "soft phases", artifacts exist, but can be modified in parallel.
2. Task estimation in hours
tasks.md had an "estimated time" column. After 6 months estimates were ±200% off reality. Dropped it.
What I kept: a "complexity (S/M/L)" column. Less precise, but matches reality.
3. SDD for small tasks
A spec for a feature like "add a toggle switch in settings" is overkill. I tried for 2 months, eventually quit. SDD makes sense for things > 4 hours.
When SDD CLEARLY helps
Three task classes where the payoff is obvious:
1. Multi-file refactors. A change touching 5+ files. Without a spec → drift, scope creep, 1/3 of the change gets postponed. With a spec → one move, predictable.
2. Cross-team features. Anything requiring review from someone else. requirements.md + design.md is the context they read instead of a 50-message Slack thread.
3. Risky migrations. Schema change, infra rewrite, auth flow change. A spec forces thinking about rollback and backwards compatibility. Without a spec, higher chance of production fuckup.
When SDD CLEARLY hurts
1. "What's even here" exploration. You don't know what you want, spec is performance theater. Explore first, spec later.
2. Hot fix. Bug in production, customers calling. SDD = 30 minutes of overhead. Fix, document later.
3. UI iteration. "Change color, see". Every change a new design.md? No way. For UI I use a quick-iter workflow without SDD.
Numbers from the year
From my workspace:
- Total specs: 47
- Average requirements.md length: 35 lines
- Average design.md length: 80 lines
- Average tasks.md length: 25 tasks
- Specs that shipped to prod without design changes: 60%
- Specs abandoned mid-flight: 12%
12% abandonment is a meaningful number. Some were "I realized it was a bad idea" (good outcome, the spec stopped me early). Some were "scope went sideways" (bad, sunk cost).
My workflow today
- Triage: task < 4h → directly. Task > 4h → SDD.
- Requirements: max 1 page, EARS. If sliding to 3 pages, scope too big, split.
- Design: only "Key Decisions" + "Alternatives Considered" + "Critical Files" sections. The rest is unnecessary.
- Tasks: 5-15 items. Fewer = too coarse. More = not SDD but a bug tracker.
- Implementation: in plan mode for non-trivial work. ExitPlanMode → execute.
- Post-implementation: I update design.md if reality drifted from the original plan.
What I'd tell myself a year ago
Don't treat SDD as religion. It's a tool. Works great for some task classes, not at all for others. The decision rule matters more than the checklist.
Invest in design.md, save on requirements.md. Design solves 80% of future questions. Requirements is the last-line check.
Accept abandonment. I dropped 12% of specs. No regrets. In the old methodology I'd have finished those 12% out of "well, I started". Now that's the sunk cost fallacy.
SDD after a year: stays as my default for medium and large tasks. With deliberate modifications and no orthodoxy. Most important lesson: the form of the artifact matters less than the thinking ritual it forces.