That gap — between an agent that looks like it works and an agent you can prove works — is the entire course. It starts today.

What’s live: Lesson 0. Free, no signup wall. Clone the repo, run one command, watch the same agent succeed once and fail once, and write down your own guess for why — sealed in a file the course checks against your answer nine lessons from now. Thirty minutes. No gate, no grading. Just the question.

What comes after: 54 lessons across ten phases, each one shipping something that either passes or doesn’t — a make verify you run yourself, not a quiz. Ten gates mark the real turns: gold patches reproducing at 100% before any agent exists, a swarm forced to beat a single agent at equal cost or lose the argument, a held-out benchmark you never tuned against, a stranger reproducing your own result from your public repo with no help from you.

Three ways to take it, depending on what you actually want:

• Core — build it, measure it, ship it.

• Full — the above, plus retrieval, multi-agent, and production operations.

• Evaluation-only — just the harness. If you want to be the person who can tell whether a number is real, this is the fast path.

Every lesson lives in two places on purpose: the article here, the full runnable code on GitHub, tagged per lesson, frozen once published. A lesson number, once it ships, never moves again — link to it in six months and it still points at the same thing.

New lesson, most weeks, starting now. If you want the honest version of what building an AI agent takes — including the parts where the plan was wrong and had to be corrected in public — Lesson 0 is below.

[Run Lesson 0 →]

This lesson is the hard sell. No harness, no gate, no code you’ll keep. Just watch something work, then watch the exact same kind of thing fail in a way you cannot explain — and carry that unanswered question into everything that follows.

Status: this lesson is specified but its code hasn’t been built yet — unlike Lessons 1–10, there’s no apr demo on GitHub to actually run today. What follows describes the intended experience and interface; the commands below are the design, not yet a working build.

Why this exists at all

Every lesson from here through Lesson 10 postpones the thing you actually want to build. That deferral is correct, but correct isn’t the same as motivating, and a reader who doesn’t feel the cost of not measuring won’t feel the relief of finally being able to. So before Phase 0 asks for patience, it shows you exactly what patience is buying.

What you’ll actually run

Clone the repo, supply your own model API key, and run one command. A pinned, dependency-frozen agent — a model with a bash shell, roughly eighty lines of control flow, nothing clever — is pointed at a real SWE-bench instance and left to work. It reads the issue, explores the repo, writes a patch, and stops. Read the diff. It’s a real fix, produced by a real model, and it’s genuinely impressive the first time you watch it happen live instead of reading about it in a paper.

Then point the same agent at a second prepared instance. Same code, same model, same amount of time. It fails — the patch it produces doesn’t resolve the issue.

The question you can’t answer, and why that’s the point

Open the second run’s transcript and try to say why it failed. You won’t be able to, and it isn’t because you’re new to this. Four explanations are equally consistent with everything in front of you: the model reasoned about the bug incorrectly. The patch it wrote doesn’t apply cleanly to the actual file. The test suite was already broken before the agent touched anything. Or the agent found and read the hidden test file, and “fixed” the issue by special-casing exactly what the test checks rather than the underlying bug.

Each of those is a different problem with a different owner. A wrong-reasoning failure needs a better model or a better localization step. A patch-application failure needs the diff-extraction discipline Lesson 6 builds. A pre-broken test needs the environment validation from Lesson 4. A leaked test needs the firewall Lesson 8 builds and then deliberately breaks to prove it catches. Right now, from the outside, all four look identical: a red X and a transcript that doesn’t distinguish between them.

That’s not a gap in your understanding. It’s a gap in your tooling — you have no instrument capable of telling these apart, because you haven’t built one yet. Every lesson in Phase 0 exists to close exactly this gap, one failure mode at a time, until “not resolved” stops being one bucket and becomes a diagnosis. Lesson 9 gives that diagnosis a name for each of these cases specifically.

Predict now, or find out later?

Write down a guess before you know the answer, or skip straight to Lesson 1? Skipping costs you nothing today and everything three lessons from now. If you don’t commit to an explanation while the failure is fresh and the four possibilities are still open, you’ll retroactively convince yourself you always knew which one it was — the same hindsight bias this course’s claims ledger exists to prevent everywhere else. Writing one sentence now, sealed and unread until Lesson 9’s failure taxonomy actually exists to check it against, costs you thirty seconds and gives you a real, falsifiable prediction instead of a memory you can’t trust.

A real model call, or a scripted stand-in? A scripted agent that fakes success and failure on cue would make this lesson safe, reproducible, and pointless. The entire experience this lesson delivers — genuine surprise at the first result, genuine confusion at the second — depends on the model actually reasoning about a real bug it hasn’t seen the answer to. That means this is the one lesson in the course that needs your own API key and produces a result nobody, including whoever wrote this course, can fully predict in advance.

What ships

1. The pinned agent. A single file, dependency-frozen, deliberately unambitious: a system prompt, a bash tool, a loop that stops when the model says it’s done or a turn cap is hit. No planner, no reviewer, no retrieval — the minimal scaffold this course keeps returning to as a baseline through Phase 1 and beyond.

# demo_agent.py — the shape of the whole thing
while turns < MAX_TURNS:
    response = model.call(system_prompt, history, tools=[bash_tool])
    if response.is_done:
        break
    history.append(run_bash_tool(response.tool_call))
    turns += 1

2. Two prepared instances. Real SWE-bench issues, chosen so that one resolves and one doesn’t under this minimal scaffold — which one does which is not disclosed anywhere in this lesson, on purpose.

3. Full transcript capture. Every tool call, every model response, saved to disk — the same discipline Lesson 10 formalizes into a trace store with a schema, applied here by hand.

Run it

export APR_MODEL_API_KEY=...   # your own key; nothing in this lesson works without one
make setup
apr demo --instance a          # watch it resolve
apr demo --instance b          # watch it not

Both runs write a full transcript to .apr/demo/. Read both before moving on — the transcript is the artifact this lesson is actually about, not the pass/fail line at the end of it.

Seal your prediction

apr demo predict "your one-sentence guess" > predictions.txt

One sentence: your best guess at why instance B failed, chosen from the four explanations above or a fifth you’ve spotted yourself. This file is sealed — nothing in this lesson or the next nine checks it against anything. Lesson 9 does, once its failure taxonomy actually exists to grade your guess against.

Where this actually confuses people

• “It worked both times” — rerun it. This scaffold is deliberately minimal and the two instances were chosen to be right at the edge of what it can do; a different model, a different day, or a different temperature can occasionally flip one. If it happens, that’s data too — note it, and move on.

• “I don’t have an API key” — this is the one lesson in the course you can’t fully complete without one. If you’re not ready to spend on model calls yet, read the transcripts in fixtures/reference_transcripts/ instead — real captured runs from the reference agent, not a substitute for running it yourself, but enough to feel the same confusion.

• “The transcript is too long to read” — that’s not a bug, it’s the point. A real agent transcript against a real repository is long and noisy in exactly the way a five-line summary can’t convey. Skim for the moment the strategy commits to something, and look there first.

What Lesson 1 assumes you now believe

You cannot tell, from a transcript alone, why an agent failed — and that gap is expensive precisely because it’s invisible until someone builds the instrument to close it. Lesson 1 starts that build, with the least glamorous piece imaginable: counting tokens correctly, because every other measurement in this course depends on getting that one right first.

Get the code

Not yet shipped. Every other lesson in this course ships code before its article publishes — this one’s the exception, on purpose disclosed rather than papered over: the scaffold described above (demo_agent.py, the two prepared instances, reference transcripts) hasn’t been built or pushed to github.com/sysdr/coding-agent yet, and running it end to end needs a real model API key this environment doesn’t hold. Building it is the next concrete step before this lesson can honestly claim the tree above.

Next: Lesson 1 — LLM Foundations for Agentic Coding