specdog.github.io/handbook.html at docs/landing · specdog/specdog.github.io · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Spec-Driven Development | specdog</title>
<meta name="description" content="Spec-Driven Development: write specs first, compile to a graph AI agents can query, eliminate hallucination.">
<link rel="icon" type="image/svg+xml" href="/dotdog/assets/dog.svg">
<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #fff; color: #1a1a2e; max-width: 720px; margin: 0 auto; padding: 40px 24px; line-height: 1.75; }
  nav { display: flex; justify-content: center; gap: 24px; padding: 0 0 32px; }
  nav a { color: #6b7280; text-decoration: none; font-size: .9em; font-weight: 500; }
  nav a:hover { color: #d97706; }
  nav a.active { color: #d97706; }
  h1 { font-size: 2.2em; margin-bottom: 8px; }
  h2 { font-size: 1.35em; margin: 36px 0 12px; border-bottom: 1px solid #e5e7eb; padding-bottom: 6px; }
  h3 { font-size: 1.08em; margin: 24px 0 8px; }
  p { margin-bottom: 12px; color: #374151; }
  pre { background: #1e293b; color: #e2e8f0; padding: 14px 18px; border-radius: 8px; font-size: .85em; overflow-x: auto; margin-bottom: 16px; position: relative; }
  code { background: #f1f5f9; padding: 2px 6px; border-radius: 4px; font-size: .9em; }
  pre code { background: none; padding: 0; color: #e2e8f0; }
  a { color: #d97706; text-decoration: none; }
  a:hover { text-decoration: underline; }
  ol, ul { margin: 0 0 16px 26px; color: #374151; }
  li { margin-bottom: 6px; }
  blockquote { border-left: 4px solid #f59e0b; padding-left: 16px; margin: 16px 0; color: #6b7280; font-style: italic; }
  table { width: 100%; border-collapse: collapse; margin: 16px 0; }
  th, td { text-align: left; padding: 8px 12px; border-bottom: 1px solid #e5e7eb; font-size: .9em; }
  th { font-weight: 600; color: #1a1a2e; }
  td { color: #374151; }
  .copy-btn { position: absolute; top: 8px; right: 8px; background: none; border: none; color: #94a3b8; cursor: pointer; padding: 4px 6px; border-radius: 4px; line-height: 1; }
  .copy-btn:hover { color: #e2e8f0; background: rgba(255,255,255,0.08); }
  .copy-btn.copied { color: #4ade80; }
  .copy-btn svg { width: 16px; height: 16px; }
  footer { margin-top: 48px; padding-top: 20px; border-top: 1px solid #e5e7eb; color: #9ca3af; font-size: .8em; }


  /* shared navigation */
  body { padding-top: 24px; margin-top: 0; }
  nav {
    display: flex;
    justify-content: center;
    align-items: center;
    gap: 18px;
    flex-wrap: wrap;
    width: min(calc(100vw - 48px), 960px);
    margin: 0 auto 32px;
    padding: 8px 0 0;
    position: relative;
    left: 50%;
    transform: translateX(-50%);
  }
  nav a { color: #6b7280; text-decoration: none; font-size: .9em; font-weight: 500; line-height: 1.4; }
  nav a:hover, nav a.active { color: #d97706; }
  /* end shared navigation */
</style>
<link rel="canonical" href="https://specdog.github.io/handbook">
</head>
<body>
<nav>
  <a href="/">specdog</a>
  <a href="/dotdog">dotdog</a>
  <a href="/about">about</a>
  <a href="/handbook" class="active">guide</a>
  <a href="/agents">for agents</a>
  <a href="/dogfood">dogfood</a>
  <a href="/blog">blog</a>
  <a href="/leash">leash</a>
  <a href="/collar">collar</a>
</nav>
<h1>Spec-Driven Development</h1>
<p>Spec-Driven Development (SDD) is a methodology that makes software specs the <strong>ground truth</strong> for AI coding agents. Instead of the agent reading prose and guessing, it queries a compiled knowledge graph.</p>

<h2>What problem does it solve?</h2>
<p>AI coding agents are powerful but imprecise. Give them 600 lines of prose in a <code>.dog</code> 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.</p>
<p>SDD solves this by compiling human-written specs into a <strong>positional DAG graph</strong> — a token-efficient structure the agent loads in one shot. The DAG is 94% smaller than source. It doesn't replace reading — it replaces <em>scanning</em>.</p>

<table>
<tr><th></th><th>Without SDD</th><th>With SDD</th></tr>
<tr><td>Agent input</td><td>~8,100 tokens of prose</td><td>~740 tokens of graph</td></tr>
<tr><td>Entity names</td><td>Extracted by guesswork</td><td>Exact, from DAG</td></tr>
<tr><td>Relationships</td><td>Invented or missed</td><td>Pre-compiled edges</td></tr>
<tr><td>Hallucination</td><td>Common</td><td>Near-zero</td></tr>
<tr><td>Verification</td><td>Manual review</td><td>Automated (<code>dotdog validate</code>)</td></tr>
</table>

<h2>The DAG: a compressed index, not a summary</h2>
<p>If the agent ignores the DAG and reads <code>.dog</code> files directly, they waste 8,015 tokens. The DAG is a compiled index — it doesn't replace reading the spec, it replaces <strong>scanning 600 lines of prose to find which 4 lines matter</strong>.</p>
<p>A <code>.dag</code> file stores entities, properties, states, lifecycles, and relationships in a <strong>v2 positional format</strong> — 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.</p>

<h2>The practice</h2>
<ol>
<li><strong>Specify</strong> — write <code>.dog</code> files: entities with properties, states, lifecycles, and relationships</li>
<li><strong>Validate</strong> — score completeness before every commit. The score must not decrease.</li>
<li><strong>Compile</strong> — build a <code>.dag</code> graph. 94% smaller than source. Token-efficient.</li>
<li><strong>Expose</strong> — MCP server for AI agents. Six tools: <code>getEntity</code>, <code>traverse</code>, <code>search</code>, <code>schema</code>, <code>summary</code>, <code>listProjects</code>.</li>
<li><strong>Verify</strong> — detect drift between spec and code. <code>dotdog verify --init</code> auto-maps entities to code files.</li>
</ol>

<h2>The loop</h2>
<pre><code>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 agents</code></pre>
<button class="copy-btn" onclick="copyBlock(this)" title="Copy">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>
</button>

<h2>The spec file anatomy</h2>
<p>A complete spec project has 7 <code>.dog</code> files:</p>

<table>
<tr><th>File</th><th>Purpose</th></tr>
<tr><td><code>SPEC.dog</code></td><td>Product description, user stories</td></tr>
<tr><td><code>constitution.dog</code></td><td>Hard constraints, scope (in vs out)</td></tr>
<tr><td><code>data-model.dog</code></td><td>Entities + relationships + lifecycles</td></tr>
<tr><td><code>plan.dog</code></td><td>Phased implementation order</td></tr>
<tr><td><code>INDEX.dog</code></td><td>Agent entry points, issue→task mapping</td></tr>
<tr><td><code>COPY.dog</code></td><td>Optional: copyright / license info</td></tr>
<tr><td><code>DESIGN-SYSTEM.dog</code></td><td>Optional: design tokens, surfaces</td></tr>
</table>

<p>Three files are required for validation scoring. Four are optional. A complete spec pushes from 95% to 100%.</p>

<h2>Why specs as ground truth?</h2>
<p>AI agents are trained on the internet — they know every framework, every API, every pattern. What they don't know is <em>your</em> project. Your entity names. Your lifecycle rules. Your invariants.</p>
<p>When specs are in prose (READMEs, docs, comments), the agent has to interpret them. Interpretation means drift. Drift means wrong code.</p>
<p>When specs are in a DAG, the agent <strong>queries</strong> instead of interpreting. No guessing entity names. No inventing properties. No missing required fields. The DAG is a database for the agent's brain.</p>

<h2>AI agents aren't optional anymore</h2>
<p>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?</p>
<p>SDD makes your codebase <strong>agent-native</strong>. The <code>.dag</code> 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.</p>

<h2>Who uses this</h2>
<ul>
<li><strong>New projects</strong> — spec before code. <code>dotdog init --minimal</code> scaffolds in seconds.</li>
<li><strong>Existing codebases</strong> — add specs alongside code. <code>dotdog verify --init</code> auto-maps entities.</li>
<li><strong>Teams</strong> — validate in CI, share MCP server. Score gates on every PR.</li>
<li><strong>Smart contracts</strong> — one bug costs millions. Spec the invariants first, let the DAG enforce them.</li>
<li><strong>AI agents</strong> — <a href="/agents">agent instructions</a> for working with dotdog projects.</li>
      <a href="/dogfood">dogfood</a>
</ul>

<h2>Further reading</h2>
<ul>
<li><a href="/dotdog/tutorial">Tutorial: Build a spec-driven project</a></li>
<li><a href="/dotdog/adopting">Adding dotdog to an existing project</a></li>
<li><a href="/dotdog/integrations">Integrations: CI, pre-commit, MCP</a></li>
<li><a href="/agents">For AI Agents: how to work with dotdog projects</a></li>
      <a href="/dogfood">dogfood</a>
<li><a href="https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html">Martin Fowler on SDD</a></li>
</ul>

<footer>dotdog@<span id="version">0.5.0</span> &middot; <a href="https://github.com/specdog/dotdog/blob/main/LICENSE">MIT</a></footer>
<script>
async function loadVersion(){try{const r=await fetch('https://registry.npmjs.org/dotdog/latest');const d=await r.json();document.getElementById('version').textContent=d.version;}catch(e){}}
loadVersion();
function copyBlock(btn){const pre=btn.parentElement.querySelector('pre');navigator.clipboard.writeText(pre.textContent).then(()=>{btn.classList.add('copied');btn.innerHTML='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>';setTimeout(()=>{btn.classList.remove('copied');btn.innerHTML='<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';},2000);});}
</script>
</body>
</html>