Chapter 3 · Part 1
Plan before it builds
Here's the failure mode that burns the most time with an agent: it misunderstands the task, executes the misunderstanding flawlessly across nine files, and hands you a large, confident, wrong diff. Now you get to read all of it to find out where it went off.
The wrong approach costs almost nothing to fix while it's still a paragraph. It costs a lot once it's a diff. So: make it plan first.
Ask for the plan, not the code
The cheapest habit in this whole course is one sentence at the end of your request.
Before you change anything: read the relevant files and tell me how you'd
approach this. Which files you'd touch, what you'd add, anything you're
unsure about. Don't write code yet — I want to agree on the approach first.What comes back is a plan you can read in thirty seconds, and it is remarkably good at surfacing the thing you forgot. Half the time you'll reply "yes, except don't touch X" — and that one clause just saved you a wasted round trip.
Claude Code also has a dedicated plan mode, where it researches and proposes an approach
without touching a single file, then waits for your approval before executing. Same idea with
guardrails: it can't start editing while it's planning. Check /help for how to toggle it in
your version — it's worth wiring into your muscle memory.
- The task touches more than two or three files.
- You're in code you don't know well (you need the plan as much as it does).
- There's more than one reasonable approach and you have a preference.
- It's hard to undo — migrations, deletions, anything touching data.
For "fix this typo," skip it. Judgement, not ceremony.
Read the plan for the thing that's missing
A plan is only useful if you actually read it. You're scanning for three things:
- Did it understand the goal? Not "does this sound smart" — does it solve your problem?
- What's it about to touch? An unexpected file in the list is a signal. Ask why before you approve, not after.
- What did it not mention? The migration. The other caller. The test that'll break. Its blind spots are the ones you can see and it can't.
That third one is where you add the most value. It has read more code than you; you know more about this codebase's history and what's coming next quarter.
One session, one job
The other half of planning is scoping. Agents are excellent at bounded tasks and unreliable at sprawling ones — not because they run out of intelligence, but because a vague task has no finish line, so there's nothing to verify against and no way to tell "done" from "gave up."
"Clean up the auth module."
Clean up how? Done when? Every diff is defensible and none of them are checkable.
"Split auth.ts into auth/session.ts and auth/tokens.ts, keeping the public API in
auth/index.ts identical. No behavior changes. pnpm test auth should pass unchanged."
Now "done" is a command that either passes or doesn't.
The best tasks have a checkable finish line: a test that goes green, a command that exits zero, a page that renders. If you can't state one, that's not an agent task yet — it's a design question wearing an agent-task costume, and you should answer it first.
A three-part feature isn't one big session — it's three small ones, each ending in a working, committed state. You get a reviewable diff at every step and a place to stand if step two goes wrong. Ask it to break the work down, then run the pieces one at a time.
Let it ask you things
If a request is genuinely ambiguous, the useful move is inviting the question rather than letting it guess:
If anything about this is ambiguous, ask me before you start rather than
picking an option and running with it.One clarifying question costs you eight seconds. A wrong assumption discovered nine files later costs you the session.
Plan agreed? Now it builds. Which raises the only question that really matters: how do you know it worked?