Spec-Driven Development (SDD) is a methodology that makes software specs the ground truth for AI coding agents. Instead of the agent reading prose and guessing, it queries a compiled knowledge graph.
AI coding agents are powerful but imprecise. Give them 600 lines of prose in a .dog file and they'll waste 8,015 tokens scanning for the 4 lines that matter. They hallucinate entity names, invent relationships, miss required fields. The longer the spec, the more they drift.
SDD solves this by compiling human-written specs into a positional DAG graph — a token-efficient structure the agent loads in one shot. The DAG is 94% smaller than source. It doesn't replace reading — it replaces scanning.
| Without SDD | With SDD | |
|---|---|---|
| Agent input | ~8,100 tokens of prose | ~740 tokens of graph |
| Entity names | Extracted by guesswork | Exact, from DAG |
| Relationships | Invented or missed | Pre-compiled edges |
| Hallucination | Common | Near-zero |
| Verification | Manual review | Automated (dotdog validate) |
If the agent ignores the DAG and reads .dog files directly, they waste 8,015 tokens. The DAG is a compiled index — it doesn't replace reading the spec, it replaces scanning 600 lines of prose to find which 4 lines matter.
A .dag file stores entities, properties, states, lifecycles, and relationships in a v2 positional format — no JSON keys, no whitespace overhead. The agent gets the exact graph: 11 entities, 5 relationships, every property typed, every lifecycle transition mapped. One file. All structure.
.dog files: entities with properties, states, lifecycles, and relationships.dag graph. 94% smaller than source. Token-efficient.getEntity, traverse, search, schema, summary, listProjects.dotdog verify --init auto-maps entities to code files.npm install -g dotdog # install
dotdog init my-app # scaffold specs
dotdog validate # score completeness
dotdog compile # build .dag graph
dotdog serve # expose to AI agentsA complete spec project has 7 .dog files:
| File | Purpose |
|---|---|
SPEC.dog | Product description, user stories |
constitution.dog | Hard constraints, scope (in vs out) |
data-model.dog | Entities + relationships + lifecycles |
plan.dog | Phased implementation order |
INDEX.dog | Agent entry points, issue→task mapping |
COPY.dog | Optional: copyright / license info |
DESIGN-SYSTEM.dog | Optional: design tokens, surfaces |
Three files are required for validation scoring. Four are optional. A complete spec pushes from 95% to 100%.
AI agents are trained on the internet — they know every framework, every API, every pattern. What they don't know is your project. Your entity names. Your lifecycle rules. Your invariants.
When specs are in prose (READMEs, docs, comments), the agent has to interpret them. Interpretation means drift. Drift means wrong code.
When specs are in a DAG, the agent queries instead of interpreting. No guessing entity names. No inventing properties. No missing required fields. The DAG is a database for the agent's brain.
Every developer has an AI agent in their editor, in their CLI, in their CI pipeline. These agents will read your codebase whether you prepare for them or not. The question is: do they read structured ground truth, or do they read prose and guess?
SDD makes your codebase agent-native. The .dag is the agent's entry point. The MCP server is its query interface. The pre-commit hook blocks regressions. The agent never ships code that violates the spec — because the spec is law, not suggestion.
dotdog init --minimal scaffolds in seconds.dotdog verify --init auto-maps entities.