DeepLearning.AI and JetBrains run a good course on spec-driven development. Paul Everitt teaches it. You write a constitution, then a spec, then code. The discipline is the point, and the discipline travels.
What doesn’t travel is the substrate. The course uses markdown. Markdown is fine for a tutorial, but the second you put it in front of a real project — agents propagating changes across requirements, specs, code, tests, variants — you hit the wall I wrote about in The 6x Tax. Plain text doesn’t tell you what links to what. Your agents reload the whole thing every turn, miss artifacts they were never told about, and burn tokens proving they didn’t.
So I rebuilt the course. It lives at patdhlk/spec-driven-development.
Same discipline, different substrate
Twelve lessons. Same arc as Everitt’s: constitution, feature, implementation, validation, the rest. The differences are where it counts.
Specs are sphinx-needs, not markdown. Every requirement, spec, test, decision, and risk gets a typed ID and typed links. req is specified by spec. spec is implemented by impl. impl is verified by test. Decisions constrain. Risks mitigate. The graph is enforced by schemas.json — malformed specs fail before they reach code.
The application is Rust + Actix-web, not TypeScript + Hono. Familiar territory for the automotive and embedded folks I work with. SQLite via rusqlite, Askama for compile-time-checked HTML templates, PicoCSS for styling, no build step.
The capstone uses Pharaoh. Once your specs are a graph, you can ask the graph things. Pharaoh is the AI assistant that does the asking — impact analysis, gap detection, traceability traversal, all driven from skill markdown instead of a runtime binary. I built it for exactly this scenario.
The domain is AgentClinic. AI agents are patients. Ailments are degradation modes — Hallucination, Context Rot, Persona Collapse. Treatments are prescriptions: Context Infusion, Prompt Recalibration. Visits go triage → diagnosis → prescription → follow-up. It’s a real CRUD app with a domain that’s silly enough to keep you reading the lesson at 11pm.
Self-contained lessons
Each Lesson_NN/ directory is a complete project snapshot. Copy the folder, start there. You don’t need Lesson_03 to do Lesson_07. If you want to see what needtable traceability matrices look like in practice, jump to Lesson_05. If you want to reverse-engineer specs from existing code, Lesson_09 is a project with code and no docs.
cp -r Lesson_02/ my-agentclinic/
cd my-agentclinic
cargo run
That’s it. No setup wizard. No Lesson_00.5 prerequisites. The lessons stand alone because the code stands alone.
What you actually learn
Lesson 02 teaches you to write a constitution as decision:: and feature:: directives, validated against a schema. Lesson 03 introduces req, spec, and test with traceability links. Lesson 04 lands impl::, and the schema starts enforcing impl→spec links. Lesson 05 is where the work pays off — you generate a needtable traceability matrix and watch the graph tell you what’s not covered.
By Lesson 11 you’re running Pharaoh skills against the corpus. pharaoh:change enumerates the impact of a single requirement change before any LLM token is spent. pharaoh:mece finds orphans, dangling links, gaps. pharaoh:trace walks the graph in any direction. Same agent, different prompt, structured input.
The course doesn’t teach you Rust. It assumes you can read it. It doesn’t teach you Sphinx either. It teaches you to write specs that a machine can traverse, which is the whole game.
“But I don’t use Rust”
Most teams who’d benefit from this don’t use Rust. That’s fine. The discipline is portable. The substrate is the point.
If you’re already on GitHub’s spec-kit, there’s an open PR — useblocks/spec-kit#1 — that adds an opt-in format = "rst" toggle. Same spec-kit slash commands, same workflow, but the output is sphinx-needs directives instead of markdown bullets. spec.rst, plan.rst, tasks.rst, plus an auto-rendered coverage.rst with needtable filters and a needflow diagram. sphinx-build -W becomes the consistency oracle. You get the typed graph without leaving spec-kit.
The concept is mine; Bartosz Burda did most of the work. Same idea as the course, applied to a tool a lot of people already use.
Why bother
Because spec-driven development is the right idea, and markdown is the wrong substrate for it. You can practice the discipline on markdown and ship a small project. You can’t audit it, you can’t query it, and you can’t hand it to four parallel agents and expect them to converge.
The course is the shortest path I know to writing specs that scale. Pick a lesson. Copy the folder. Start.
Repos referenced: patdhlk/spec-driven-development (the course), useblocks/pharaoh (the AI assistant framework used in the capstone), useblocks/spec-kit#1 (RST mode for spec-kit).
