Repository navigation
Expand file tree
/
Copy pathhandbook.html
More file actions
152 lines (135 loc) · 12.3 KB
/
Copy pathhandbook.html
File metadata and controls
152 lines (135 loc) · 12.3 KB
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
<!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="Combine spec-driven development with type-driven design: model domain rules, valid states, typed transitions, and runtime boundaries before implementation.">
<link rel="icon" type="image/svg+xml" href="/assets/dog.svg">
<link rel="canonical" href="https://specdog.github.io/handbook">
<link rel="stylesheet" href="/assets/site.css">
<script src="/assets/site.js" defer></script>
</head>
<body>
<a class="skip-link" href="#main">Skip to content</a>
<header class="site-header">
<nav>
<a href="/" class="brand"><img src="/assets/dog.svg" width="28" height="28" alt="">specdog</a>
<a href="/dotdog">dotdog</a>
<a href="/about">about</a>
<a href="/handbook" class="active" aria-current="page">guide</a>
<a href="/agents">for agents</a>
<a href="/blog">blog</a>
<a href="/leash">leash</a>
<a href="/collar">collar</a>
</nav>
</header>
<main id="main" class="page">
<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>Coding agents need project-specific names, constraints and relationships. Scanning prose can miss relevant details; a compiled graph provides a structured index for targeted queries.</p>
<p>Dotdog compiles human-written specs into a graph and keeps intended behavior distinct from observed code. Token costs depend on the source, retained metadata and query scope; graph compilation does not prevent hallucination or prove implementation correctness.</p>
<table>
<tr><th></th><th>Without SDD</th><th>With SDD</th></tr>
<tr><td>Agent input</td><td>Source documents</td><td>Selected graph context and source evidence</td></tr>
<tr><td>Entity names</td><td>Read from source</td><td>Queryable identifiers and labels</td></tr>
<tr><td>Relationships</td><td>Read or inferred</td><td>Explicit edges with available provenance</td></tr>
<tr><td>Verification</td><td>Review and tests</td><td>Spec checks plus review and application tests</td></tr>
</table>
<h2>The DAG: a compressed index, not a summary</h2>
<p>A <code>.dag</code> is an index of the compiled model, not a replacement for source evidence or tests. Prefer bounded context, impact and path queries over loading every artifact.</p>
<p>Spec graphs retain entities, properties, states, lifecycles, relationships and descriptions. Imported and observed graphs carry their own identities, provenance and coverage. Missing edges and truncated queries do not prove independence.</p>
<h2>Practical field guides</h2>
<div class="grid"><div class="card"><a href="/guides/type-driven-development/">Type-driven development</a><p>Model states, inspect a selected TypeScript contract, query its graph, and reject invalid usage.</p></div><div class="card"><a href="/guides/rea-graphs/">REA and Ghidra graphs</a><p>Import a versioned native-call export and follow its evidence without running the binary.</p></div></div>
<h2>The practice</h2>
<ol>
<li><strong>Specify</strong> — write <code>.dog</code> files: entities with properties, states, lifecycles, and relationships</li>
<li><strong>Design with types</strong> — translate domain rules into types and operation signatures before implementation. <a href="#type-driven-design">Model valid states and explicit failures.</a></li>
<li><strong>Validate</strong> — inspect spec completeness and resolve reported gaps; a score is not application verification.</li>
<li><strong>Compile</strong> — build a <code>.dag</code> graph, or use <code>refresh</code> to update spec/code graphs together.</li>
<li><strong>Expose</strong> — use the local stdio MCP server's eleven tools for entity, path, context, impact and workspace queries. See the <a href="/agents">tool reference</a>.</li>
<li><strong>Verify</strong> — use <code>status</code> for freshness, explicit scenario/reference checks for recorded mappings, and the project's own compiler and tests for behavior.</li>
</ol>
<h2 id="type-driven-design">Type-driven design</h2>
<p>These are three distinct practices: <strong>spec-driven design</strong> defines intended behavior and constraints; <strong>type-driven design</strong> shapes implementation through types; <strong>graph mapping</strong> records entities and relationships for navigation and traceability. A graph can connect the artifacts, but is not a type system.</p>
<p>Specs describe the intended behavior. Type-driven design turns the rules a language can express into types and function signatures, then uses the type checker to guide implementation. This complements spec-driven development and test-driven development; it does not replace either. <a href="https://idris-lang.org/">Idris describes this types-first approach</a>, including dependent types that can express relationships between values.</p>
<ol>
<li><strong>Name domain values</strong> — distinguish identifiers, units, and validated values where mixing them would be an error. Use opaque types or controlled constructors when a plain alias provides no protection.</li>
<li><strong>Model alternatives</strong> — use unions or enums for distinct states, with each state's required data. Avoid independent flags and optional fields that permit invalid combinations. See <a href="https://fsharpforfunandprofit.com/posts/designing-with-types-making-illegal-states-unrepresentable/">Scott Wlaschin's domain-modeling example</a>.</li>
<li><strong>Define operations first</strong> — specify accepted states, returned states, and failure cases before writing function bodies. For ownership-sensitive workflows, <a href="https://doc.rust-lang.org/embedded-book/static-guarantees/typestate-programming.html">Rust typestate</a> can consume an old state when producing the next.</li>
<li><strong>Parse at boundaries</strong> — check external data and return a domain value or an explicit error. Preserve what the check established in the returned type instead of discarding that information. This is <a href="https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/">Alexis King's “Parse, don't validate” principle</a>.</li>
<li><strong>Verify both layers</strong> — type-check valid usage and examples that must fail to compile. Test runtime parsing, business behavior, and integration failures separately.</li>
</ol>
<h3>Example: state-specific data</h3>
<p>Suppose the spec requires a receipt for a paid order and a tracking reference for a shipped order. A TypeScript discriminated union keeps those fields with their states:</p>
<pre><code>type Draft = { state: "draft"; id: string };
type Paid = { state: "paid"; id: string; receipt: string };
type Shipped = {
state: "shipped";
id: string;
receipt: string;
tracking: string;
};
type Order = Draft | Paid | Shipped;
function markShipped(order: Paid, tracking: string): Shipped {
return { ...order, state: "shipped", tracking };
}</code></pre>
<p>A typed caller cannot pass a <code>Draft</code> to <code>markShipped</code>, and a <code>Shipped</code> value requires tracking data. Use <a href="https://www.typescriptlang.org/docs/handbook/2/narrowing.html#exhaustiveness-checking"><code>never</code> exhaustiveness checks</a> when handling all order variants. This function only records a transition; it does not arrange delivery or prove payment occurred.</p>
<p>TypeScript does not consume the original order, so this signature does not prevent repeated calls. Strings also do not prove that receipt or tracking references are genuine or nonempty. Boundary parsing and runtime business checks remain necessary; <a href="https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions">a type assertion performs no runtime checking</a>.</p>
<h3>Use it with dotdog</h3>
<p>Record domain rules in <code>SPEC.dog</code>, properties and lifecycle rules in <code>data-model.dog</code>, and implementation and verification tasks in <code>plan.dog</code>. Compile the specs so agents can query the model, then implement the corresponding types in the project's language. Review spec and type changes together.</p>
<p><code>dotdog validate</code> checks spec completeness; <code>dotdog compile</code> produces the graph. Neither command type-checks application code or proves that lifecycle rules are enforced. Run the project's own type checker and tests as separate checks.</p>
<p>Dotdog 1.0 also offers opt-in <code>types inspect</code> for selected TypeScript 7.0.2 contracts and saved REA/Ghidra graph import. See <a href="/dotdog/type-contracts">type contracts</a> and the <a href="/dotdog#rea--ghidra-evidence">saved native-evidence workflow</a> for supported inputs and limitations.</p>
<h2>The loop</h2>
<div class="code-wrap"><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></div>
<h2>The spec file anatomy</h2>
<p>Spec projects can use these files; minimal scaffolds need not contain every optional document:</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>Validation reports structural completeness, not whether requirements are correct or implemented.</p>
<h2>Why specs as ground truth?</h2>
<p>Specs record project-specific intent: entity names, lifecycle rules and invariants. Graph queries make that model easier to navigate and cite.</p>
<p>When code and specs disagree, inspect freshness and evidence, then resolve the discrepancy through review. Neither a graph nor an agent should silently decide which requirement is correct.</p>
<h2>Agent integration</h2>
<p>Install repository-scoped skills with <code>dotdog skills install --agent both</code>, or connect <code>dotdog serve</code> through a supported stdio MCP host. Hooks are optional and removable. Run independent CI checks rather than relying on editor automation alone.</p>
<h2>Where it fits</h2>
<ul>
<li><strong>New projects</strong> — spec before code. <code>dotdog init --minimal</code> scaffolds in seconds.</li>
<li><strong>Existing codebases</strong> — run <code>dotdog refresh</code>, query observed code, and add explicit spec mappings.</li>
<li><strong>Teams</strong> — run pinned CLI checks and application tests in CI; use local stdio MCP sessions.</li>
<li><strong>Smart contracts</strong> — record invariants, then verify them with appropriate compiler, runtime and security checks. Graphs do not enforce them.</li>
<li><strong>AI agents</strong> — <a href="/agents">agent instructions</a> for working with dotdog projects.</li>
</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>
<li><a href="https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html">Martin Fowler on SDD</a></li>
</ul>
</main>
<footer>
<p>specdog · Feed the dog. Ship with specs.</p>
<p>Created by <a href="/about#justin-diclemente">Justin DiClemente</a> · <a href="https://github.com/specdog">GitHub</a></p>
</footer>
<script>
</script>
</body>
</html>