What the SDD Playbook Did Not Cover

A year ago I wrote about spec-driven development and the folder architecture that makes it work. The argument was that specs should be the source of truth rather than chat history, that CLAUDE.md should be a minimal routing file, and that workspace structure, not multi-agent orchestration, is the real agentic architecture. Since then I have been running that playbook daily, across two production sites and a fleet of personal projects. Most of it held up. Three ideas the essay never mentioned turned out to matter more than anything in it. This post is about those three.

Implementation Reality#

The original essay named spec rot as a risk. It did not solve it.

Running the playbook surfaced the problem fast: specs drift from code faster than you expect, and in ways you cannot see from the spec alone. The mitigation I converged on is a section at the bottom of every package README called Implementation Reality. Four parts, updated at every reconciliation pass: what shipped (with commit or PR references), spec-but-not-in-code (requirements the spec describes that no code implements yet), code-but-not-in-spec (features built ahead of the spec, which need backfill), and the follow-up PRs the document anticipates.

In the package that drives my finance engine, Implementation Reality is more than half the README. It tracks five sprints of audit closures, eleven ADR pivots, and every dead config key the production code now ignores. It is the single most valuable document in that repo: the handoff artifact that lets the next session start on solid ground instead of trusting a spec that might describe a design that shipped differently.

If you adopt nothing else from the playbook plus this post, adopt this. Every package README gets a dated Implementation Reality section. Update it at every reconciliation. The spec captures intent. Code is the source of truth for what was built. Implementation Reality is the bridge.

ADRs amend each other#

The original essay treated architecture decision records as write-once.

In production they evolve. ADR-002 in a package's decision/ directory amends the API contract that ADR-001 established, which amended the default format the original feature spec set. The ritual that keeps this honest is the amendment note: both the amending ADR and the amended document carry a dated entry in their change logs, and the amending ADR's status block explicitly names what it supersedes. A "Supersedes:" line in an ADR header is load-bearing, not metadata.

Without the amendment ritual, specs silently diverge. With it, the chain of decisions is auditable: any future reader can trace which ADR currently governs a field, and why. The public demo repo shows the pattern in two files, a package-scoped ADR-002 that amends a feature's original API default, with the amendment recorded in both places.

The stateless and persistent tool split#

The original essay described a workflow in one tool. Now my workflow is two, and the split does real work.

A stateful assistant carries the deliberative work: planning, research, spec writing. It has repository access and memory across sessions, which is what lets specs evolve instead of restarting every conversation. Claude Code carries the stateless, fast work: reading a spec and opening a PR with working code. Each tool does the job it is good at. Specs are the handoff boundary between them.

This is not a preference. It is a structural answer to a structural problem. Implementation wants a fresh context per task, where state is overhead. Decision-making wants the opposite, where state is the whole point. Forcing one tool to do both collapses the workflow in predictable ways: either the implementation context fills up with design history it does not need, or the design session forgets what last week resolved. The tool split is what makes the routing table scale across the actual work.

A concrete example. A /finance route worked in the Lambda dispatcher but had never been registered in the API Gateway stack. The browser got a 403 Missing Authentication Token, CORS headers never attached, the page threw Failed to fetch. The obvious fix was a two-line infrastructure patch. Instead the spec amendment landed first, noting that handler routes and stack routes had drifted twice that month, with an explicit follow-up to add an infra test that compares the dispatcher's routes against the stack. Then the patch. The bug was real and urgent. The spec is what prevents the next one. Specs lead, code follows, and that discipline is only possible because the deliberative tool and the executing tool are separate.

What the original essay had right#

Most of it. Specs as source of truth. CLAUDE.md as a router, not a brain dump. Workspace context files for per-area loading. Separation of concerns as the operating principle. If you have not read that essay, start there; this post is the follow-up, not the primer.

The discipline is in the specs. The automation is in the pipeline. The tools are workers. And the receipts already exist: I published the production numbers after the first week and again after a full month, so you can check whether the playbook cashes out in shipped work rather than diagrams.

---

Related:

• Spec-driven folder architecture, the original playbook this post extends
• SDD is context management, why the method works at all
• June SDD production numbers, the receipts