Plan Before You Code

Planning is useful when the cost of the wrong edit is higher than the cost of a short review.

For Claude Code, the current docs support plan mode through commands such as /plan, claude --permission-mode plan, and interactive toggles in supported versions. Command surfaces change, so check /help in your installed version before standardizing a team workflow.

When To Use A Plan

Use a plan when the task touches:

multiple files or packages
auth, billing, permissions, migrations, or data deletion
unfamiliar code paths
user-facing UI behavior
tests that do not already exist
a refactor where the blast radius is unclear

Skip a plan for:

typo fixes
small documentation edits
straightforward dependency bumps
changes where you can describe the exact diff in one sentence

The Workflow

Explore: let the agent read and search, but not edit.
Plan: ask for files, steps, risks, and checks.
Review: correct scope, remove unrelated work, add missing verification.
Implement: exit plan mode and apply the approved plan.
Verify: run the checks from the plan.

/plan Investigate how token refresh works and propose the smallest fix
for users being logged out after refresh. Do not edit files yet.

Your plan must include:
- files you inspected
- files you expect to change
- tests or commands you will run
- assumptions that still need confirmation
- things you will not touch

What A Good Plan Includes

Plan field	Why it matters
Files inspected	Shows the plan is grounded in the repo
Proposed files to change	Makes blast radius reviewable
Behavior change	Separates intent from implementation
Verification steps	Prevents “looks done” stopping
Assumptions	Exposes guesses before edits happen
Non-goals	Blocks unrelated refactors
Rollback note	Useful for migrations and risky config changes

Red Flags

Reject or revise the plan if:

it proposes files the agent did not inspect
it mixes unrelated cleanup into the task
it lacks a verification step
it treats assumptions as facts
it suggests broad rewrites before explaining the current behavior
it depends on stale commands or version-specific features without checking them

Implementation Prompt

After approving the plan:

Implement the approved plan only.
Keep the change scoped to the listed files unless you find a blocker.
Run the verification steps from the plan and show the results.
If the plan is wrong, stop and explain before changing direction.

Why This Still Matters

Coding models are getting better, but they still optimize strongly toward completing the visible task. Plan review gives you a cheap checkpoint before code is changed, especially when the agent has not yet loaded enough repository context.