Plan Before You Code

Complete Tell the Model What to Look At first; this lesson builds on @ references so the plan the model produces is grounded in the actual files you pointed at.

Plan mode is the habit of asking the model to outline its approach before it writes a single line of code. Most agent IDEs have this as a first-class feature: in Cursor you can ask for a plan explicitly, in Claude Code you can say "think through this before you start." The model describes what it intends to do and you review it. Then you say go.

Here is the before and after: A developer asked Claude Code to "refactor the data layer to use the new API client." Claude produced a 3-bullet plan: update the fetch utility, update every call site, and update the tests. The developer read bullet 2 and realized the model had identified 12 call sites but missed the 3 in the admin panel (a separate subdirectory). That gap would have left the admin panel calling the old client silently. One plan review, 30 seconds, prevented a silent regression across three screens.

The cost asymmetry is dramatic. Reading a plan takes 30 seconds. Reviewing a plan that reveals a misunderstanding takes 2 minutes. Undoing 12 incorrect file edits because you skipped the plan takes 45 minutes and usually requires git reset. Plans are cheap. Unplanning is expensive.

Paste this into Claude:

I want to practice plan mode on a real task. Here is the task: [describe a change that touches more than two files, e.g. "add an email field to the User type, update the registration form, update the API endpoint that saves the user, and update the tests"]. Before you make any changes, write a plan: (1) List every file you will touch and what specifically changes in each one. (2) List the order you will make the changes, so nothing breaks mid-refactor. (3) Tell me what you are uncertain about or what you need clarified before you start. Do not write any code yet. I want to review the plan first.

What good looks like:

• You received a plan listing specific files and specific changes before any code was written
• You reviewed the plan and found at least one file or edge case the model identified that you had not thought of
• You found at least one gap in the plan and corrected it before the model started coding
• After approving the plan, the implementation required fewer back-and-forth correction turns than a typical unplanned task
• You can explain in one sentence why reviewing a plan is cheaper than reviewing completed code

What a good response looks like:

Here is my plan for adding the email field across your project. I will not write any code until you approve this.

1. src/models/User.ts: Add `email: string` to the User interface after `username`. Mark it required.
2. src/api/users.ts: Update the `validateUserInput` helper to include email as a required field. Update the database insert on line 51 to include email. Add email to the `sanitizeUser` allowlist on line 67 (currently missing, which would silently drop it from API responses).
3. src/components/UserForm.tsx: Add a controlled email input following the existing useState pattern for username and password.
4. tests/api/users.test.ts: Update the user shape assertion on line 22. One existing test will fail without this.

Order: models first, then API, then UI, then tests. This order means no file references a type or field that doesn't exist yet.

Uncertainties before I start: Does the email field need to be unique in the database, or is that enforced elsewhere? And should the email be editable after registration, or is it set once at creation?