The plan is the product: how I actually run Claude Code

The fastest way to waste a day with a coding agent is to describe a feature in a sentence and let it start typing. It will start typing. It types very fast, and forty minutes later you have a plausible diff across nine files that solves a problem adjacent to the one you had. Now you are reading it, half-understanding it, and deciding whether to patch it or throw it away. Either way the expensive part, the thinking, never happened. You outsourced the typing and kept none of the leverage.

I stopped working that way about a year ago. Boris Tane wrote up a version of the loop I had converged on independently, in how he uses Claude Code, and reading it was the first time I saw someone name the thing I had been doing by feel. So this is my version: the actual mechanics of how a task goes from an idea in my head to shipped code, and why the code is the least interesting step in it.

The one rule underneath all of it: Claude does not write code until I have read and approved a written plan. Everything else is machinery around that rule.

The prompt is not the unit of work. The plan is.

When people share their agent workflow, they share prompts. The clever system prompt, the magic phrasing, the trick that makes the model behave. I have almost nothing to say about prompts, because the prompt is not where my work goes. My work goes into a plan document, a markdown file that lives in the repo under plans/, and that file is the thing I actually build.

A prompt is ephemeral. You type it, the model acts, it scrolls out of view, and if the session compacts you cannot even retrieve exactly what you asked for. A plan document is durable. I can read it, edit it, annotate it, diff it, and hand it back. It survives the context window resetting. It is the one artifact in the session that holds full fidelity from the first minute to the last. Treating it as the real deliverable, and the code as a mechanical projection of it, changes everything downstream.

So the shape of a session is not “prompt, correct, prompt, correct.” It is: research into a document, turn that document into a plan, argue with the plan until it is right, then let the plan become code. The creative work is front-loaded into the two middle steps. By the time code gets written, all the decisions are already made.

Research is a read-only pass, and it is not optional

Before there is a plan there is a research step, and it has one job: understand the ground before proposing to build on it. I point the agent at the relevant slice of the codebase and ask it to read, not to change anything, and to write what it finds into a document. Not “look at the auth module.” Read the session handling in these three files, trace how a token is validated, and tell me where the assumptions live.

The output is a findings file I actually read. It catches the things that would have made the plan wrong: the existing pattern I forgot we used, the interface two other call sites depend on, the migration that already does half of what I was about to ask for. Skipping this step is how you get a plan that is internally coherent and completely wrong about the system it is supposed to fit into.

This is also the cheapest place to be thorough. Reading is cheap. A wrong plan that becomes wrong code and gets reviewed and reverted is expensive. Every hour I have ever saved by skipping research, I have paid back with interest later in the same session.

The annotation cycle is where the thinking happens

Boris calls this the annotation cycle and it is the right name, so I am keeping it. Once the agent produces a plan, I open the file in my editor and I argue with it. Inline. Directly in the document. Some notes are two words next to a step, not optional, or wrong, we don’t own this table. Some are a paragraph explaining a constraint the model had no way to know: this endpoint has to stay byte-for-byte backward compatible because a client I can’t redeploy is parsing the response.

Then I hand it back with an explicit guard: revise the plan, do not implement yet. And we go around again. Usually two or three times, sometimes six. Each pass the plan gets sharper and my notes get shorter, because there is less left to correct.

This loop is the whole game, and it is worth being precise about why. The model is genuinely good at understanding code and generating candidate solutions. What it does not have is my product priorities, my knowledge of which corners are safe to cut, my memory of the incident that made us do it the careful way. The annotation cycle is the channel I use to inject exactly that judgment, one note at a time, into a document we both share. It is the closest thing to shared mutable state between a human and an agent that I have found. By the time the plan is approved, every decision that required a human made contact with a human. That is the entire point.

Implementation should be boring

When the plan is right, I give one standardized instruction: implement all of it, mark each step complete in the plan as you go, run the typecheck continuously, and do not stop until it is done. Then I mostly get out of the way.

Implementation is boring by design. It should be. All the creative decisions were spent in the annotation cycle, so what is left is transcription, and transcription is exactly what the model is best at. My feedback during this phase is terse: a single sentence, or a screenshot when something in the UI looks off. I am not re-deciding anything here. I am checking that the boring work matches the plan.

And when it drifts, I do not patch. I revert and re-scope. A bad direction discovered mid-implementation is almost never a signal to bolt a fix onto the mess. It is a signal that the plan had a gap, so I go back to the plan, fix the gap there, and let the corrected plan regenerate the code. Patching the output leaves the plan lying, and a plan that lies is worse than no plan, because the next session trusts it.

The plan carries the context, so CLAUDE.md doesn’t have to

There is a temptation, once you feel how much context matters, to stuff every rule into the global instructions file and let it ride. I argued against that at length in the 200-line rule, and the plan-centric loop is what makes a short instructions file actually workable. The global file holds only the stable, always-true rules. Everything task-specific, the constraints, the invariants, the files in play, the acceptance criteria, lives in the plan document, where it is loaded exactly when the task needs it and nowhere else.

That separation is also what keeps the work cheap. A plan document read once and referenced across turns sits in the stable part of the context and caches well; a global instructions file you keep editing invalidates the cache every time you touch it. I went deep on that economics in most of your AI coding bill is cache, and the punchline holds here: the habits that make the output good are the same habits that make it cheap. A plan you argue with once and then hold stable is both.

Subagents get the brief, never the history

For work that genuinely splits, I fan out, but the plan is what makes fan-out safe. Each subagent gets a self-contained brief carved out of the plan: its exact task, the files it owns, the acceptance criteria, the constraints, and no assumption that it can see the conversation that produced them. File ownership is drawn so no two agents touch the same file. The interface between the pieces is settled in the plan before anyone starts.

I wrote about where that line sits in when I reach for a team of agents, and the short version is that most tasks do not clear the coordination cost. But when they do, the plan document is what turns a fan-out from a merge-conflict generator into three agents executing three unambiguous briefs. Without the plan there is nothing to carve the briefs out of, and the parallelism just multiplies the ambiguity.

What compounds

If I compress the whole loop into one line, it is this: the plan is the product, and the code is a build artifact of the plan.

That reframing is what changed my results, more than any model upgrade did. It moves the labor to where the leverage is. It gives me a durable object to reason about instead of a scrolling transcript. It survives compaction, it caches cheaply, it carves cleanly into briefs, and it forces every real decision through a human before any code exists. The bottleneck moved from typing to specifying a while ago; the plan document is just where I do the specifying, out in the open, in a file I can edit.

Try it once on something real. Refuse to let the agent write a line until there is a plan in front of you that you have read, argued with, and approved. The first time you ship a non-trivial change this way and realize you understood every decision in it, you will wonder how you ever worked from a prompt and a prayer.