Learnings from a No-Code Library: Keeping the Spec-Driven Development Triangle in Sync
TL;DR
Drew Breunig shipped whenwords, a
relative-time-formatting library that contains no code
— just a SPEC.md and a tests.yaml, from which
a coding agent regenerates the .py — to press the question,
"if the agents are good enough, do we need to share code?" That reframes
software as a spec-driven development (SDD) triangle:
specs (what/why/sometimes how) + tests (verifiable behavior) = code
(implementation). The insight of the talk is that generating code from a
spec is the easy part; the standing problem is that spec, tests, and
code are three redundant representations of one intent and therefore
drift — bug-fixes add code and tests with no spec
change, and agents make implementation decisions the spec never
captured. Drift is detectable from signals you already emit (git diffs
of code and of the spec, test-coverage tools, and agent traces), and the
fix is to extract the intent — a decision log.
Breunig's demo tool Plumb runs on each commit: it identifies
decisions from code diffs and agent traces, dedupes them, presents them
to a human to approve, updates the spec, and reports spec-to-test and
spec-to-code coverage. The payoff (agents refer to the spec instead of
searching the whole codebase; a durable answer to "why does this code
exist?"; even hacks get logged, never silently dropped) is real but
honestly bounded: dedup is fuzzy, decision-rejection reversal doesn't
work yet, and it's untested on large projects. He closes noting this
rediscovers old ground (Dijkstra; Claire Le Goues' 2009 automated
software repair) — "inventing from first principles often means
rediscovering from first principles."
Concepts introduced
- Spec-Driven Development — define the program in a spec (+ tests) and let an agent implement it; the spec↔︎tests↔︎code triangle and its inevitable drift are the whole subject.
- Decision Log — capturing why code exists (decisions from diffs + agent traces, deduped and human-approved) and folding it back into the spec is the triangle's sync mechanism.
Held, not dropped (themes touched, no concept page yet — spin out on demand):
- SDD as rediscovery of formal methods / automated program repair. Dijkstra's 1972 "programming has become a gigantic problem" and Le Goues' 2009 genetic-programming approach to automated software repair are the lineage; worth a "prior art of agentic SWE" page eventually.
- Context engineering. "Claude can refer to the spec for implementation understanding without entire-codebase search" is a context-engineering benefit; Breunig's O'Reilly Context Engineering Handbook is the pointer. Hold until a second source lands.
- AI coding output outpacing human review. The talk's "AI Coding Boosts Output But Overwhelms Human Reviews" beat corroborates the attention-bottleneck thesis; already covered under Agent Supervision, noted there rather than spun out.
Key claims
- Spec, tests, and code are redundant representations of one intent, so they drift; the sync cost, not the generation, is the real problem. principle → Spec-Driven Development
- When agents are reliable enough, the spec (+ tests) can be the durable artifact and code becomes regenerable — you may not need to share code. (best practice) — context: contingent on agent reliability for the domain; shown at toy scale, "untested on large projects," and the same bet failed for a $20k/16-Claude C compiler. → Spec-Driven Development
- Drift is detectable from signals you already emit — git diffs of code and spec, coverage tools, and agent traces. (best practice) — context: version-controlled SDD projects; these are proxies (coverage ≠ spec-fidelity). → Spec-Driven Development
- Bug-fixes and hot-fixes add code and tests with no spec change — a systematic drift source. observation → Spec-Driven Development
- Capture the decisions behind changes, not just the diffs — that's what answers "why does this code exist?" principle → Decision Log
- Log even bad or sloppy decisions; never silently drop them. principle → Decision Log
- Extract decisions from diffs + agent traces, dedupe, get human approval, update the spec. (best practice) — context: the Plumb per-commit workflow. → Decision Log
- Making implicit agent decisions explicit surfaces weird, silent LLM behaviors you'd otherwise miss. observation → Decision Log / Agent Supervision
- Decision identification and dedup are fuzzy and locally specific — the human approval gate is load-bearing, not optional. (best practice) — context: honest limitation. → Decision Log
- Inventing from first principles often means rediscovering from first principles. observation — SDD re-derives formal specification and automated program repair. → Spec-Driven Development
Why this is novel (and what it corroborates)
No existing concept in the graph covers spec-driven development or the intent/decision log, so the dominant stance is novel: two new concept pages (Spec-Driven Development, Decision Log). But it lands squarely against several existing spines and strengthens them:
- Corroborates Eval-Driven Development. SDD makes "tests are the new unit tests / measure, don't vibe" structural: tests are the executable, verifiable half of the spec. An independent source (a live talk + shipped library) converging on tests-as-source-of-verifiable-truth — noted, not duplicated.
- Corroborates Agent Supervision. Plumb's "dedupe decisions and present them to the user to approve," plus the "AI coding overwhelms human review" framing, is exactly attention-routed, legible review with the human as the scarce resource — a second source for the supervision thesis.
- Builds on Reusable Workflow Library. "If agents are good enough, do we need to share code?" is the same move one altitude up: share the definition (spec), not the rebuilt implementation — the library-without-code is a workflow-library argument for application code.
Illustrated walkthrough
- t=00:00 — Framing. Title card: "A Software Library With No Code — And the Spec-Driven Development Triangle."
- t=01:18 — The provocation. Full-screen: "If the agents are good enough, do we need to share code?" This is the thesis question the whole talk interrogates.
- t=03:17 — The triangle defined. "What is Spec
Driven Development? Exhaustively (hopefully) define your program, then
let an agent sort it out." Three file icons:
.mdSpecs ("defines what, why, and sometimes how") +.yamlTests ("measures and validates verifiable behavior") =.pyCode ("implements and executes specified behavior"). - t=03:47 — The existence proof. The
whenwordsGitHub repo (1.1k stars, 65 forks): files areINSTALL.md,LICENSE,README.md,SPEC.md,tests.yaml— and no.py. About blurb: "A relative time formatting library, with no code." - t=04:32 — Others made the same bet. "Larger Teams Shipped Larger Projects": Vercel's just-bash (simulated bash env in TypeScript), Pydantic's Monty (minimal Python interpreter in Rust), and "Anthropic threw 16 Claudes and $20k at a spec suite to build a Rust-based C compiler. (This didn't really work…)" — the honest ceiling on the bet.
- t=13:23 — Why this is hard, historically. Dijkstra (1972): "…now we have gigantic computers, programming has become an equally gigantic problem." Paired at t=10:08 with "Inventing from first principles often means rediscovering from first principles."
- t=15:06 — The pressure. A "Today's News" card: "AI Coding Boosts Output But Overwhelms Human Reviews" — output is cheap now; review is the bottleneck.
- t=16:44 — The mess. A Mad Max "Gas Town" still (flare stacks, smoke) — the visual metaphor for the gigantic, entropic problem of unmanaged complexity.
- t=18:30 — The core problem, drawn. The triangle broken apart: Specs floating top-right, Tests and Code bottom, disconnected. Spec, tests, and code have drifted out of sync.
- t=21:09 — The escape hatch. "Thankfully, There are Signals That Indicate Gaps": code changes tracked by git (compare to spec), test-coverage tools (what's tested ≠ whether tests reflect the spec), spec updates tracked by git, bug-reports/hot-fixes that add tests+code with no spec change, and agent implementation that generates decisions recoverable from agent traces.
- t=23:10 — The sync workflow. "The Main Workflow for Keeping Things in Sync — Extracting intent from new work. On each commit, Plumb: (1) identifies decisions from code diffs and agent traces, (2) dedupes and presents them to the user to approve, (3) updates the spec, (4) reports spec-to-test coverage, (5) reports spec-to-code coverage."
- t=26:55 — Decisions as data. A JSON array of
extracted decision records —
id,source_file: "plumb_spec.md",text: "The hook must write pending decisions to branch-specific decision log files…",ambiguous: false,last_seen_commit: null— the machine-readable Decision Log. - t=27:40 — The tool. "plumb — An example tool to manage the SDD Triangle, to keep things 'true.'" Links spec↔︎requirements↔︎code↔︎tests and decisions↔︎requirements; lets you edit the spec, test, or code to drive the others forward. (Image: a plumb-bob — the tool that checks true vertical.)
- t=30:17 — Honest limits. "Known Limitations": only
pytest, only tested with Claude Code; decisions interrupt flow; dedup
isn't perfect and is locally specific; code reversal on rejection
doesn't work yet; needs better spec-management (sharding, Q&A);
tunable "just enough" structure
(
—dangerously-approve-all-decisions); untested on large projects; works best when the spec is ahead of or aligned with the code. - t=32:14 — Benefits so far. "Using plumb to build plumb has been wild": Claude refers to the spec instead of searching the whole codebase; the decision log answers "why does this code exist?"; it's a code review that captures intent; it spots weird, silent LLM behaviors better; and "hacks get documented… those decisions are logged."
- t=34:19 — Sync in practice. A merged GitHub PR
editing
plumb_spec.md("Branch-sharded decision log…"): dedup via Jaccard similarity across chunks, a "Question Synthesizer," decisions written withstatus: "pending"— the workflow eating its own dog food. - t=38:29 — Lineage. "Thanks to Claire Le Goues" (CMU) for the CS-history section — she's worked on AI for software engineering "since halfway through the last AI winter" and published "A genetic programming approach to automated software repair" in 2009.
- t=39:12 — Plug. O'Reilly's The Context Engineering Handbook: The Art & Science of Structuring Information for AI, edited by Drew Breunig.