Hypothesis-driven development is what you do with an idea whose effect you could measure.
Before you build it, you state the intervention as a hypothesis: if we build this feature, our AI will do 10% better on defeasible reasoning tasks — the kind where new information can overturn a conclusion you had already drawn. You name the measure that would settle it. Then you run the experiment that produces the number.
The part almost nobody does comes next. The hypothesis, the measure and the experiment live on the same board as the engineering work, tied to it and to each other by real relationships — so "which experiment validates this hypothesis?" is a question you can ask, rather than something you go and read prose to work out.
Not a lab notebook sitting beside a ticket tracker. One graph, one board, both kinds of work in it.
That is the whole thing. The rest is making it cheap enough to do fifty times.
This handbook teaches it by having you do it. By the end of the first chapter your prediction is on the record — timestamped, pushed, beyond quiet revision. The second chapter closes the loop. Neither is a reading exercise.
Which way in?
One question — and it is about what you have done before, not what you call yourself:
Have you built something with a coding agent before?
That is the axis these tracks actually sort on. "Are you a developer?" is the wrong question: it is a job title, and the two readers below can share one.
Start from scratch →
You have not done this before, and you would rather describe what you want than write it. No programming language, no tools to choose between — but chapter one does need a paid Claude plan, and says so before you start.
Go straight to the tools →
You already work with agents and you resent being walked through things. All four chapters are written, and every tool they walk is real, public, and linked below.
If you are not sure, take the first one. It is thirty minutes and it will not teach you anything wrong — the second track assumes the first track's ideas without re-explaining them.
Just want the code?
yurtle-kanban — file-based kanban. Your work items are Markdown files; git is the database. Python, MIT.
pip install yurtle-kanban
yurtle-kanban init --theme software
arrow-kanban — the same idea built for AI agents rather than people: Arrow tables in-process, no server, no network. Rust 1.85+, MIT.
cargo install --git https://github.com/Congruentsys/arrow-kanban arrow-kanban
arrow-kanban init --theme software
⚠ Two things that will bite you otherwise: install from git (the crates.io name is an empty placeholder), and name the package explicitly — the repo builds two binaries, so without the trailing arrow-kanban cargo refuses rather than guessing.
acf-framework — 12 dimensions, 75 measures and 16 hypotheses for testing whether an AI system actually understands something. commons — the methodology specs, CC-BY-4.0. Everything else.
Why two tracks rather than one with signposts
Because the difference between these two readers is not pace, it is prior knowledge — and the guidance that helps someone new to a subject measurably slows down someone who already knows it. Scaffolding is not neutral. A reader who already understands version control does not need the paragraph explaining it, and making them skip past it repeatedly is its own tax.
So the two tracks share ideas and a reference core, but neither makes the other read its scaffolding.
This is about expertise, not "learning styles" — the idea that people have fixed styles instruction should match has been tested and does not hold up.
You do not need to install anything to start
The first track uses a text file, a folder, and about half an hour. No board, no database, no project tool.
That is not a simplification for beginners. It is the actual claim: hypothesis-driven development is a discipline, not a tool. A board makes it cheaper to do fifty times; it is not what makes it work. So you learn the thing first and pick up a tool later, when you can feel what you want one for.
All eight chapters are written — both tracks, end to end.
If you want the thinking behind it
The essays under Approach go into why this works, what it cost us to learn, and the times it went wrong.
You do not need any of them. They are linked from inside the chapters at the points where they get interesting, so you can follow one when you feel like it and ignore the rest.
Where this method came from
We did not invent it. Hypothesis-driven development is an old idea, borrowed from how experiments are run in science and from lean product practice.
What changes when you work with AI agents is the price. An experiment that used to cost a fortnight can cost twenty minutes — and once that is true, the expensive thing is no longer the experiment. It is the belief you never got round to testing. That is the whole reason this is worth learning now.
The method, in full → · Why we publish our failures →
⚠ Both are more technical than these chapters. Skip them freely.