Plan Mode: Think Before You Code

The workflow that prevents Claude Code's most expensive mistake: building the wrong thing well.

There is a category of Claude Code mistake that costs more than ordinary bugs.

The code works. The tests may even pass. But the approach is wrong: the API contract does not match the consumer, the change fights the existing architecture, or a hidden edge case was never discussed.

You discover the problem after implementation, which means you now have to unwind code that was never supposed to exist.

Plan mode exists to prevent that.

What Plan Mode Is

Plan mode is a dedicated phase where Claude Code explores and reasons before editing files.

You enter it with:

/plan

Or with a task:

/plan add cancellation support to pending invoices

In plan mode, Claude can inspect the codebase, ask clarifying questions, surface risks, and propose an implementation plan. The point is to separate "what should we do?" from "write the code."

Those are different modes of work.

The Four-Step Workflow

The current Claude Code best-practice loop is:

1. Explore. 2. Plan. 3. Implement. 4. Commit.

Step 1: Explore

Ask Claude to read the relevant code without making changes.

/plan

Read the auth routes, session middleware, OAuth provider code, and existing auth tests.
Do not edit files.
Explain the current login flow and where Google OAuth should fit.

This prevents Claude from inventing architecture before it understands yours.

Step 2: Plan

Ask for a concrete plan.

Create an implementation plan for Google OAuth.
Include files to change, tests to add, open questions, and risks.

Do not accept the first plan automatically. Review it like a design doc.

Ask:

  • Does it match existing patterns?
  • Are the file paths real?
  • Are the tests specific?
  • Are the risky cases named?
  • Is any new dependency justified?

Step 3: Implement

Switch back to normal mode and implement against the plan.

Implement the approved Google OAuth plan.
Start with the tests for the callback handler.
Run the auth test suite after each task.

The plan is now the anchor. If Claude drifts, redirect it back to the plan.

Step 4: Commit

Once tests pass and the diff is reviewed, ask Claude to commit or prepare the PR.

Show me the final diff summary, then create a descriptive commit.

Use your normal review standards. Plan mode improves the work; it does not remove your responsibility.

When to Use Plan Mode

Use plan mode when:

  • The task touches multiple files.
  • The task changes an API contract.
  • The code area is unfamiliar.
  • The work introduces a dependency.
  • The change affects security, payments, data migration, or permissions.
  • You cannot describe the expected diff in one confident sentence.

Skip plan mode when:

  • The change is a typo.
  • The fix is a small, obvious one-liner.
  • You are renaming a local variable.
  • You are making a mechanical edit inside a clear existing pattern.

Planning has overhead. Use it where the cost of being wrong is higher than the cost of thinking first.

What a Good Plan Contains

A good plan is specific enough to execute and review.

It should include:

  • Goal: the desired behavior.
  • Non-goals: what this change should not do.
  • Current system summary: what Claude found in exploration.
  • Files to change: real paths, not vague module names.
  • Task list: small, checkable steps.
  • Tests: exact cases and commands.
  • Risks: edge cases and unknowns.
  • Rollback: how to undo or pause safely.

Example:

# Plan: Pending Invoice Cancellation

## Goal

Allow users to cancel invoices before payment capture.

## Non-goals

- Do not support cancellation after payment succeeds.
- Do not change invoice creation.

## Tasks

- [ ] Add service tests for pending, paid, and missing invoices.
- [ ] Add `cancel_invoice` service method.
- [ ] Add route and authorization check.
- [ ] Add audit log entry.
- [ ] Run `pytest tests/invoices`.

## Risks

- Webhook idempotency must remain unchanged.
- Paid invoices must stay immutable.

If the plan contains "TBD" or "handle errors appropriately," push back. That is not a plan. That is a place where a plan is missing.

Use Your Editor for Plans

Claude Code supports editing plans directly in your editor in current workflows. Use that.

You will see things in a plan file that you miss in chat:

  • Over-broad scope
  • Missing tests
  • Wrong file paths
  • Hidden assumptions
  • Steps that should be split

Treat the plan like a lightweight design review.

Common Mistakes

The first mistake is planning and coding in the same breath.

If the prompt says "think through the approach and implement it," Claude has pressure to move from uncertainty to code too quickly. Ask for the approach first. Then implement.

The second mistake is skipping plan mode because you feel confident.

Confidence is exactly when blind spots are quiet. Use plan mode when the blast radius is real, not only when you feel lost.

The third mistake is accepting a vague plan.

"Update the service and add tests" is not a plan. "Add a failing test for paid invoice cancellation returning 409" is a plan.

The fourth mistake is letting the plan get stale.

If implementation reveals a new constraint, update the plan before continuing. A stale plan creates false confidence.

Plan Mode and Models

Planning benefits from stronger reasoning. If your setup supports model choice, consider using Opus or higher effort for ambiguous architecture and review. Sonnet is often plenty for implementation once the plan is clear.

The rule is simple:

  • Spend reasoning where mistakes are expensive.
  • Spend speed where the path is already known.

The Payoff

Plan mode adds a small pause before coding. In return, you get:

  • Fewer wrong implementations.
  • More reviewable diffs.
  • Clearer tests.
  • Better session handoffs.
  • A written artifact for teammates.

For non-trivial work, the pause pays for itself quickly.

Think first. Code second. Review always.

Sources

Part 6 of a seven-part series on using Claude Code efficiently.