Spec Driven Development: A Practitioner's Guide
Spec driven development explained clearly: workflow, benefits, and how specs connect requirements, implementation, and testing for real engineering teams.
Write the spec before asking an agent to code. That advice leaves out the hard part: checking whether anyone agrees on its meaning. Consider a hypothetical handoff: an engineer saves a requirement, launches an implementation skill, and expects a failed operation to remain retryable. The agent treats failure as final. Both interpretations fit the text.
Why a Saved Spec Is Not a Shared Spec
A saved specification becomes shared when readers can inspect its decisions and challenge unresolved interpretations. File access doesn't establish agreement. Neither does polished prose.
The obvious diagnosis is missing context. Sometimes that's correct. But adding background won't settle whether partial success permits a retry, or whether cancellation must undo completed work. Those are decisions. Someone must make them.
Spec driven development earns its overhead only when inspection makes conflicting decisions observable before a handoff is accepted.
Requirements research supports that distinction: a tailored inspection caught ambiguities that later formalization missed. Formal syntax doesn't remove the need for review. A longer prompt doesn't either.
Review rule: Record the disagreement before asking an agent to resolve it.
A useful review names a requirement owner and records the accepted interpretation beside a testable example. Unresolved choices remain visible. They shouldn't become silent defaults.
That distinction also changes agent context management. Agents need enough information to act, but reviewers need evidence that the information means the same thing across handoffs. A shared recipe still fails when nobody agrees whether “done” means browned outside or cooked through.
How Specs Connect to Implementation and Testing
Specs connect to delivery through explicit relationships between requirements, work records, code changes, and verification evidence. Copying text into another prompt doesn't establish those relationships.
The desktop workspace provides a concrete setting: editor, backlog, requirements, terminal, and Git views share a window. Its project records cover goals, tickets, requirements, test cases, dependencies, and history. MCP exposes that state to connected agents. Agents can query records instead of relying on pasted summaries.
Specs vs Prompts vs Shared State
| Approach | Where it lives | Cross-agent visibility | Revision history |
|---|---|---|---|
| Saved spec | Project document | Depends on access and retrieval | Depends on document tracking |
| Copied prompt | Agent session | Requires explicit forwarding | Session-dependent |
| Shared project state | Repository database | Available through connected MCP tools | Project history records |
The table describes storage choices, not quality levels. A shared database can contain bad requirements. A short document can contain excellent ones.
Requirements traceability adds a testable obligation: each required relationship must exist. For example, a cancellation requirement should identify its implementation ticket and the test that checks cancellation after partial completion. The resulting Git change needs a recorded connection too.
Traceability research defines tasks through explicit target relationships and measurable evaluation. For a workflow, that means defining the required relationships before measuring coverage. Record storage alone doesn't create them. An agent or reviewer still has to establish and check each connection.
What a Specification Must Actually Say
A useful specification names branches, system states, failure behavior, and observable outcomes. Anything an agent would otherwise guess deserves inspection.
Consider these hypothetical requirements: “Handle errors gracefully. Let the user retry when appropriate.” Neither sentence defines a test. “Gracefully” hides the outcome. “Appropriate” hides the decision.
A reviewable replacement could read:
If an operation times out, preserve completed results and mark unfinished work as waiting. Retry unfinished work only after explicit user approval. If required input is missing, request it without repeating completed actions. Tests must distinguish timeout from partial success and verify that retries don't duplicate completed actions.
That paragraph still needs domain review. Timeout policy remains unspecified. So does who may approve a retry.
Those gaps are useful findings. They give a reviewer something concrete to resolve before implementation starts, rather than letting an agent choose behavior during coding.
- Inspect boundaries. Check empty input, interrupted work, and transitions between waiting and failure.
- Demand observable evidence. Replace “reliable” or “intuitive” with an outcome a test can reject.
The working rule is compact: name the condition, the resulting state, and the evidence. Specification inspection should also record rejected interpretations. Otherwise, a later agent may reasonably propose the same behavior that reviewers already ruled out.
When the Overhead of Spec Driven Development Stops Paying
Specification overhead stops paying when reviewers spend more effort maintaining detail than that detail helps them decide or verify. Document length isn't a useful target.
A 2026 study of 88,052 pull requests across 119 repositories found no statistically significant difference in defect introduction after propensity-score matching, with a difference of -0.6 percentage points and p = 0.133. The study attributed the raw association to task complexity. Difficult work attracted specifications.
That result limits the claim. Adding a spec doesn't establish a quality gain.
A requirements-first language-model study reported improved evaluated quality, but tested a single low-difficulty to-do application. That scope doesn't establish the same benefit for legacy migrations or unclear business rules.
How much detail deserves review
A reversible label change may need an expected result and a focused test. A migration across services needs compatibility rules and recovery behavior because a failed assumption can affect work outside the changed component.
Changing requirements complicate the choice. More detail means more revision work. Write stable constraints carefully; avoid specifying unsettled implementation choices as permanent requirements.
Sizing principle: Spend review effort where a wrong assumption is expensive to detect or undo.
The product makes a related storage decision: project data is kept in a repository-resident SQLite file. That supports local access without a separate database service. It also requires an explicit policy for backups and concurrent writes. Sharing needs a policy too. Keeping a file beside code doesn't decide whether it belongs in version control.
Measure rework and escaped defects alongside review time. Clarifying questions identify gaps, but asking one can be the correct action. Preventing questions would reward guessing.
Making a Spec Executable in an Agent Workflow
A spec becomes executable when a check can reject work that violates a recorded requirement. The orchestrator needs an honest result. A completion summary isn't enough.
MCP servers expose schema-defined tools, discovered through tools/list and invoked through tools/call. Supporting agents can use those operations against shared project records. Connection support still needs checking.
In Settings → Agent, importing a JSON dynamic-provider configuration registers an external CLI after schema validation. No recompile or plugin API is needed. The provider describes the CLI harness. The desktop acts as a meta-harness.
Skills combine a prompt with provider, model, and permission mode. Configured directories supply them. Combos run ordered skills. Agents execute locally as PTY child processes, and a failed process stops the chain.
That creates a practical gate for AI agent testing: a verification skill should report failure when required checks fail or required evidence is missing. Coverage gating needs that check implemented. Record availability doesn't imply automatic enforcement.
Each following skill receives a cleaned terminal tail, with ANSI sequences removed and interface clutter filtered. That handoff helps continuity. It doesn't replace test records, and a successful process exit proves only that the process reported success.
The Sentence That Travels to Any Tool
A useful spec makes a wrong decision observable. Its format can change without losing that property, provided reviewers can still identify the disputed choice and find evidence that would reject it. An unresolved interpretation should remain visible. Approval should have a recorded owner. A test should be able to fail. Those habits remain useful after an editor or agent changes, because they define what counts as acceptable work without depending on a particular conversation.
AuricIDE offers an open-source desktop workspace for coordinating local CLI agents through shared project records and ordered skills. Visit it to assess a workflow where a requirement can be inspected before implementation and checked before the next handoff.