SDD isn't about managing AI agents, it's about managing context
The last post ended on a claim: the reason I can ship production software from a phone is that the thinking happens in specs and the typing happens elsewhere.
Spec-Driven Development is a methodology for managing context. The specs are the persistent memory that makes a stateless AI useful across sessions.
Why stateless is the real problem#
Claude Code does not remember the last session. Every session starts from zero, no memory of the stack, the conventions, the decisions from last week, the reason a particular function is implemented the way it is. This is the single most underappreciated fact about working with coding agents at scale.
Without specs, every session rebuilds context from scratch. The agent reads the codebase, guesses at conventions, infers design intent from whatever it happens to open first, and produces code that is plausible but not necessarily correct. Small changes land fine. Larger changes expose every gap.
With specs, a session that opens with "continue the contact form work" already has the stack, the conventions, the prior decisions, and the acceptance criteria. The spec is the handoff. Point a fresh session at it and the session is at full speed in one read.
The stateless/persistent split is the actual architecture:
- Claude Code, stateless execution. Given a spec, it writes the code. It does not need to remember anything between sessions because the spec carries everything.
- Perplexity Computer, persistent decisions. It remembers across sessions. It is where the thinking happens, where decisions are made, where specs get written.
The workflow depends on the right tool handling the right layer. Trying to make Claude Code carry state across sessions fails. Trying to make Perplexity implement features inside its planning context fails. Separation is the point.
The spec structure#
Three components do almost all the work:
A specs repo, separate from code, readable by both tools. This is not a /docs folder. It is its own repository, version-controlled, review-gated. See the public demo repo for a guided walkthrough of both package shapes, it is the public teaching artifact for the methodology behind my private work.
Two package shapes, chosen per project. An integration package (steering/ + feature/ + decision/) for evolving platform work where each feature lands into a live system with existing conventions. A domain package (product/ + domain/ + contracts/ + delivery/) for bounded greenfield apps where you are defining the domain as you go. One of each lives in the demo repo.
CLAUDE.md at every code repo root. The first file any AI session reads. It is a router, identity, folder structure, and a routing table that maps task types to the right specs. Forty to fifty lines, not four hundred. Routing table columns: task, go to, read first. That is the whole shape. A sample CLAUDE.md is in the demo repo.
The CLAUDE.md file is the most expensive real estate in the whole system. Every token in it is spent on every turn, in every session, forever. Treat it like one. Put routing there. Put everything else in workspace-level CONTEXT.md files that only load when the agent enters that workspace.
What breaks#
Three failure modes are worth naming.
Spec rot against a stateless reader. A spec describing a design that shipped differently becomes a wrong answer the AI trusts. The fix is not more process, it is a discipline to either update the spec when the code changes, or mark the spec deprecated. Drift is the single biggest risk.
Context window limits. Loading a full package into every session crowds out the code itself. The CLAUDE.md routing table exists precisely to avoid this. The agent reads the router, goes to the right workspace, loads only that workspace's context, and works. Planning context doesn't contaminate implementation context. Client A doesn't leak into Client B.
Treating the spec like documentation. Documentation describes something that exists. A spec describes something to build. When a spec turns into a write-up of the finished code, it has stopped doing its job. Specs are forward-looking artifacts that happen to survive as a record. The record is a side effect.
The persistent memory lives outside the agent#
What lets a stateless agent ship reliable production code is the context it loads on turn one. Spec-driven development gives a stateless tool a persistent memory that lives outside it, on purpose, where humans can review it, gate it, and change it.
That external memory is only as good as its upkeep. The moment a spec describes a design that shipped differently, the agent trusts a wrong answer with full confidence, and a stateless reader has no way to catch that the memory rotted. The discipline holds the whole system up, and it is never finished.
The next post is the numbers. Same week, same workflow, pulled straight from GitHub.
Previous in the series: I shipped two production sites and a blog from my phone
Read the methodology:
caskeycoding-specs-demo, public teaching artifact- ADR-001, Spec-Driven Development
- ADR-002, SDD File Structure
Questions this post answers
- How do specs preserve context across coding sessions?
- In my workflow, each coding session starts without the decisions from the prior session. I use a version-controlled spec as the handoff, so a fresh session can recover the stack, conventions, prior decisions, and acceptance criteria from one reviewed source.
- What are the core parts of this spec-driven setup?
- I use a separate, review-gated specs repository, choose one of two package shapes for each project, and place a short `CLAUDE.md` router at every code repository root. The router identifies the repository and points each task type to the relevant specs.
- How long should the root CLAUDE.md be?
- In my setup, the root `CLAUDE.md` stays around 40 to 50 lines. It holds identity, folder structure, and a routing table, while workspace `CONTEXT.md` files carry details that load only when needed.
- What failure modes can corrupt a spec-based context system?
- I watch for stale specs that disagree with shipped code, oversized context loads, and specs rewritten as after-the-fact documentation. I update or deprecate a stale spec, route each session to a scoped context, and keep specs forward-looking.