SDD in Practice: Learnings from 153 Commits in 10 Days

Day 5 of a desktop app project. I look at my docs/ directory: 102 Markdown files. Templates, patterns, feature specs. Then I re-read the Thoughtworks article about SDD — "Constitution → Specify → Plan" — and suddenly it clicks: What I've built over the last days IS Spec-Driven Development. I did it without knowing.

In Part 1 of this series, I explained what SDD is and why AI agents need structured specifications. Theory's important — but what does this look like in practice? Here's my authentic story: 153 commits, 4 phases, 10 days. No perfect plan. Just learning by doing.

Phase	Timeframe	Commits	What happened
1. Feature Blitz	Jan 19-21	18	18 features documented — fast but inconsistent
2. Framework Emergence	Jan 22-24	27	Templates, patterns, Reference-Style discovered
3. SDD Epiphany	Jan 25-26	79	Constitution → Specify → Plan recognized and implemented
4. Finalization	Jan 27	29	Audit, cleanup, 9.8/10 consistency reached

The Context

December 2024. Someone asks me for a desktop application. Entity management, resource management, transaction tracking — the full program. I start working on documentation, back then with RooCode, later with Claude. It gets more comprehensive than expected. In January 2025, the first commits emerge. Then the project sits dormant for a year.

January 2026. He reaches out again. He'd experimented with ChatGPT in the meantime, failed with Python on Windows. I pick up the project again — this time with Claude Code and a radical principle: I write no code myself. Everything goes through Claude Code. I review, validate, iterate — but don't type code myself.

5 DDD documents already existed from 2025: a Domain Model refined through 20 iterations (v1-v20), Bounded Contexts, Ubiquitous Language, technical architecture, and a project description. 21 commits, a full year old. This DDD foundation provided the domain structure — Entity Management, Transaction Management, Resource Management — but no spec structure for AI-assisted development.

The first task: transform the 2025 DDD documentation into feature specifications. Quickly became clear: the originally planned PWA with microservice architecture was too complex. Architecture pivot: Tauri desktop app with Svelte and Rust. Local-first instead of cloud-first, SQLite instead of PostgreSQL. Less infrastructure, faster development.

At this point, I'd heard about SDD (Q4 2025) but hadn't really understood it. My approach was structured dialogues with Claude Code. One session had 106 messages, another 263. It wasn't "generate code for me" — it was real ping-pong. Claude asked back: "Is entity management relevant in this scope?" "Which aspects should be simplified?" Feature by feature worked through, decisions made in dialogue.

Phase Timeline

Phase 1: The Feature Blitz

The first three days were a sprint. My goal: transform the old documentation into an implementation plan. Claude Code as co-author, me as conductor. The commit log tells the story:

IAM-001: First-Run Setup fully specified
IAM-002: User Management fully specified
EM-001: Entity Management fully specified
TM-001: Transaction Model Management fully specified
RM-001: Resource Management fully specified
...

18 features in 3 days, distributed across four bounded contexts: Identity & Access Management, Entity Management, Transaction Management, Resource Management.

The domain structure from my earlier DDD work proved its worth. Architecture decisions emerged in dialogue — the switch from PWA to desktop app came through Claude's questions about complexity. "Reduce status types, make address management optional, no complex family relationships" — simplifications like these emerged from conversation.

What went wrong: No consistent template structure. Specs got too long, some over 1,500 lines. Inconsistent pattern usage — some UI specs had DataTables, others didn't. No separation between WHAT and HOW. By January 21 evening, I looked at the specs: 18 documents, but each slightly different. Entity management had 2,361 lines, navigation only 300. Which was the standard? I needed structure.

Phase 2: Framework Emergence

The trigger was simple: "This needs to be more structured." I wasn't thinking about SDD yet. I was solving problems. And patterns emerged — organically, not planned.

January 22: Wizard standardization. Problem: 5 different wizard specs, all structured differently. Solution: One Universal Wizard Pattern as template.

January 23: The game-changer. Reference-Style Pattern discovery. entities-backend.md had 2,361 lines. Too much code in the spec. Complete implementations — if-statements, loops, error handling. Everything. But why? I don't need complete implementations in specs. I just need enough information for Claude Code to build the rest.

The solution was the Reference-Style Pattern. Instead of ~70 lines per function with complete implementation, just ~15 lines: function signature plus metadata table. Permission, validation, repository, activity log — that's all Claude Code needs. The rest is implementation detail. Result: entities-backend.md shrunk from 2,361 to 818 lines. Minus 65%.

January 24: Template System v3.0. Now I had patterns, but each spec type needed its own structure. So I developed 6 template types: Overview, UI, Implementation, Testing, Pattern, System. Simultaneously, Pattern Integration v2.0 — instead of a central pattern list at the beginning of each spec, pattern references now came directly at the relevant spot. The difference: In v1.0, I had to scroll up to see which pattern applies. In v2.0, it's right there where it's relevant.

End of Phase 2: 102 specs documented, templates v3.0 established, Reference-Style works, consistency felt like 7/10. I thought I was building a documentation framework. I didn't realize: This IS Spec-Driven Development.

Phase 3: The SDD Epiphany

Morning, January 25. I re-read the Thoughtworks article about SDD. "Constitution → Specify → Plan" it says. I look at my folder structure: docs/specs/. Suddenly it clicks: My templates v3.0 are the Specify phase (WHAT). My implementation specs should be the Plan phase (HOW). My architecture.md — that's Constitution! I'd built SDD without knowing it. This wasn't a typical SDD adoption. Normally you'd start with Constitution, then Specify, then Plan. I'd already documented 18 features and only then discovered that what I was doing had a name. Applying SDD retrospectively to existing documentation — no textbook describes that. But it wasn't properly separated yet.

The restructuring took 12 hours. A 1,125-line blueprint, 97 specs migrated to new directories, 500+ references updated. The result was a clear three-phase structure: constitution/ for architecture (9 docs), specify/ for WHAT (88 docs), plans/ for HOW (design docs).

52 commits on January 25. 27 commits on January 26. 79 commits in two days. That was intense. I worked from 9 AM to 9 PM, with short breaks. Claude Code created every commit — I reviewed, corrected, iterated, but typed nothing myself.

The metrics after transformation: Consistency from 7/10 to 9.8/10. Error-handling compliance from 14/16 to 15/15. Wizard structure from 4/5 to 5/5.

Consistency Metrics

Phase 4: Finalization

The last polish. I'd done the big transformation, but now it needed a complete audit. Every spec checked for correct permission references, missing ones added. Error handling standardized — before, 7 different variants existed in specs (Error Enum, Error Handling, Fehlerbehandlung, Error-Handling, Errors...), after: 2 standards. Backend uses Error Enum, frontend uses Error Handling, documented in ADR-0002.

Find implicit business rules and document them explicitly. Eliminate redundancies between CLAUDE.md and README.md. 141 broken @-mentions found and fixed after the big migration. 38 spec documents had no references section — added.

Final consistency: 9.9/10. The last 0.1 is missing because perfection's a myth.

Key Learnings

The most important insight: SDD principles often emerge organically. I didn't start with "now I'm doing SDD." I solved problems, sought structure, developed templates. In the end it was SDD — but I learned it in the process. That's perhaps the most important point: You don't need to plan perfectly before starting. You can start, iterate, and discover the methodology along the way.

The Reference-Style Pattern was the biggest single improvement. Just function signatures plus metadata tables instead of complete implementations. 65% size reduction, better scannability. Pattern references belong directly at the relevant section — not in a central list at the beginning. 200 lines later, nobody remembers which pattern applies.

Interactive dialogues with Claude Code were crucial. The longest session had 263 messages. Claude asked back, posed the right questions, helped with architecture decisions. The switch from PWA to desktop app emerged in such a dialogue. This isn't one-prompt-and-done — it's real collaboration.

Define templates early — saves refactoring. If I'd defined templates after feature 3, I wouldn't have had to retrospectively adjust 15 features. And SDD works retrospectively too — I'd already documented 18 features (Phase 1), then the SDD structure came (Phases 2-4). Not "throw everything away and start over," but migrate existing docs.

What I'd Do Differently

Understanding SDD principles before starting would've been helpful — but learning-by-doing was authentic. Sometimes you need to make the mistakes to understand why the methodology exists. Track metrics from the beginning would've made progress more visible. Smaller commits would've been better — 79 commits in two days was too much at once. And a second pair of eyes probably would've seen earlier that I was building SDD without knowing it.

Recommendations

If you want to try SDD: Start simple. Begin with a constitution.md and 1-2 feature specs. Not 18 features at once like me. Learn the system with small scope, then scale. After the second or third feature, you should have a template. Which sections does each spec need? What's MUST, what's CAN? How do I reference other specs?

Perfection doesn't exist. Your first template version won't be the last. I had v1.0, v2.0, v3.0 — and v3.0 still isn't perfect. Define a consistency score, even if it's subjective. "7/10 → 9.8/10" is more motivating than "it feels better."

Claude Code's excellent for spec work. Structured documents, clear rules, iterative refinement — exactly what AI does well. Use it.

Conclusion

SDD isn't a perfect methodology. It's a structured alternative to the chaotic "vibe coding" that dominates some AI development. The core remains simple: Specify first, then implement. Constitution defines the system. Specify describes WHAT. Plan describes HOW. And only then comes code.

You don't need to do SDD perfectly from the start. You can begin, iterate, and discover the methodology in the process. The result's the same: Structured specifications that AI agents can understand and implement.