D5 · Plan mode and explore→plan→code · Claude Code Learning Hub

As D3 said: plan mode is, strictly speaking, just one of the permission modes. But it earns its own lesson, because the workflow the Claude Code docs recommend most — explore→plan→code — is built around it. By the end of this lesson you'll be able to judge whether a task deserves planning first, and walk through a complete "explore → plan → approve → implement" cycle.

Why this lesson comes today

This lesson picks up directly from D3 · Permission modes and sandboxing: there you learned what default, acceptEdits, auto and the rest can each do without asking, and plan mode was one row in that table. Today we switch perspective — treating plan mode not as a permission setting but as a way of working: split "understand the problem" and "change the code" into two phases, with a gate you control in between.

It also sets up what's ahead: D6 · checkpoint / rewind is about backing out after a mistake, while plan mode is about needing that escape hatch less often; the hands-on tip "Have Claude interview you and turn requirements into a spec" is the advanced version of this lesson's idea — planning done heavier and more formally. Our takeSkip this lesson and you'll fall into the habit of letting Claude start coding the moment it gets a requirement — with a noticeably higher rework rate on big tasks.

Core concepts, explained

OfficialPlan mode in one sentence: Claude only researches and proposes changes, but doesn't actually make them. Claude can read files, run commands to explore, and write up a plan, but it will not edit your source; until the plan is approved, edits stay blocked (the single exception is covered in the misconceptions section below). The CLI status bar shows ⏸ plan mode on while it's active. The official framing: explore a codebase before changing it.

The permissions view: what's blocked, what's allowed

OfficialIn plan mode, read operations never need approval. Shell commands split into two cases: if your account qualifies for auto mode and the useAutoModeDuringPlan setting is on (it is by default), shell commands during the planning phase are reviewed by a classifier model — the ones that pass simply run, the ones that don't are blocked, with no prompt either way; otherwise, commands outside the built-in read-only command set still trigger an approval prompt.

Our takeA handy way to remember it: plan mode = "read freely, write never, run commands case by case". What it blocks is modifications to your source code — not any of the exploration you need to understand the problem.

Entering, exiting, approving: one gate

OfficialThere are three ways into plan mode:

In a session, press Shift+Tab to cycle permission modes, in the order default → acceptEdits → plan; press Shift+Tab once more to leave plan mode without approving a plan.
Prefix a single message with /plan to enable plan mode for that one prompt only.
Start with claude --permission-mode plan; to make a project default to plan, set "permissions": {"defaultMode": "plan"} in .claude/settings.json.

The explore→plan→code workflow: exploring and planning both happen inside plan mode, and plan approval is the only gate; approving exits plan mode and starts implementation, while rejecting keeps you in the planning phase to polish further.

OfficialOnce the plan is written, Claude lays it out and asks how to proceed, usually with three options:

Yes, and use auto mode — approve and start executing in auto mode; when auto mode isn't available this option reads Yes, auto-accept edits, and in a session started with bypass permissions it reads Yes, and bypass permissions.
Yes, manually approve edits — approve the plan, but confirm every edit one by one.
No, keep planning — stay in plan mode and tell Claude what to change in the plan.

OfficialNote: approving a plan exits plan mode and switches the session to the permission mode matching the option you chose. To plan another round, cycle back with Shift+Tab or use the /plan prefix. Before approving, you can also press Ctrl+G to open the plan text in your default editor and edit it directly; accepting a plan also auto-names the session from the plan's content (unless you've already named it with --name or /rename).

Why explore before planning: the official reasoning

OfficialBest practices lists this as a core recommendation, and the reasoning is blunt: let Claude start coding straight from the requirement, and you'll likely get code that "solves the wrong problem". Plan mode exists precisely to separate exploration from execution. The full recommended workflow has four steps: Explore (read code and answer questions in plan mode) → Plan (have Claude write a detailed implementation plan) → Implement (approve the plan or exit with Shift+Tab, then start coding and verify against the plan) → Commit (commit and open a PR).

Our takePut another way — it's renovation logic: measure the rooms and find the load-bearing walls (explore), then draw up plans and a quote (plan), you sign off (approve), and only then does construction start (implement), ending with inspection and handover (commit). Skip the first two steps and start knocking down walls, and the cost of hitting the wrong one dwarfs the time drawings would have taken. With an LLM there's an extra payoff: the code read into context during exploration is exactly the most relevant background for the implementation phase, and the written plan pins "what we're doing" down in text — giving the implementation an anchor to check against, so it's much harder to drift as it writes.

Which tasks deserve a plan first — and which don't

The official testOfficialPlan mode is useful, but it has overhead. Tasks with a clear scope and a tiny change — fixing a typo, adding a log line, renaming a variable — just let Claude do them. Planning pays off most when: you're unsure about the approach, the change spans multiple files, or you don't know the code you're about to touch. The official one-line test: if you can describe the diff in a single sentence, skip the plan.

Our takeOne more practical signal: if you plan to leave the screen and let Claude run on its own afterwards (say, switching to auto mode after approval), planning first is worth even more — the gate is your last human check before going unattended.

Common misconceptions

Misconception 1: "In plan mode Claude can't run any commands at all."OfficialWrong. Reads are always allowed; when auto mode is available, shell commands during planning are auto-approved or blocked by the classifier. What plan mode blocks at its core is "editing your source" — not "touching anything at all".

Misconception 2: "Once I'm in plan mode I'm completely safe."OfficialThere is one explicit exception: in a session with bypass permissions enabled, plan mode's blocking is not enforced — Claude is still instructed to only plan and not edit, but if it does actually attempt an edit or a command, it executes without a prompt. Don't treat plan mode combined with bypass as a "read-only vault".

Misconception 3: "After approving the plan I'm still in plan mode."OfficialYou're not. Approval exits, and the session switches to the mode you picked (auto / edit-by-edit approval, etc.). Plenty of people get halfway through implementation, want to "plan a bit more", and assume they're still in plan mode when they left it long ago — press Shift+Tab again or use /plan.

Hands-on: doable today

Pick a real project you know well (a few source files is enough) and walk the full gate flow once, about 20–30 minutes:

Start in plan mode: claude --permission-mode plan. Expected: the status bar shows ⏸ plan mode on.
Send an exploration prompt (copy the first block below, swapping in your directory name). Expected: Claude reads files and gives its analysis without changing any file.
Follow with the second prompt to ask for a plan. Expected: Claude produces a step-by-step plan and the approval menu appears (the three option families — Yes, and use auto mode / Yes, manually approve edits / No, keep planning — with wording varying slightly by account configuration).
Choose No, keep planning first and give one revision note (for example, "in step 2, write the tests before changing the implementation"). Expected: still in plan mode, and the plan gets updated.
When the approval menu appears, press Ctrl+G. Expected: the plan text opens in your default editor for direct edits; saving returns you to the menu.
Choose Yes, manually approve edits. Expected: the plan mode marker disappears from the status bar and Claude starts editing per the plan, with each edit prompting you individually for confirmation.
To wrap up, press Shift+Tab a few times and watch the default → acceptEdits → plan cycle, confirming you can switch back into plan mode anytime.

Read through the code under src/ related to login and sessions, and work out
the current authentication flow. Don't change any files yet. Answer two questions:
1. Where are tokens generated, and where are they validated?
2. Which file holds the current session-expiry logic?

I want to add a "remember me for 30 days" option to login.
Based on what you just explored, give me a step-by-step implementation plan:
for each step, list which files change, why, and how to verify the change.
Call out explicitly in the plan what is out of scope for this round.

How to know you've learned it

Without the docs, you can name the three ways into plan mode (the Shift+Tab cycle, the /plan prefix, --permission-mode plan) and how to exit without approving a plan.
You can explain what plan mode blocks and allows at the permission level, plus the exception in bypass-permissions sessions.
You can recite the three families of approval options, and state clearly that "approving = exiting plan mode + switching to the matching mode".
All 7 hands-on steps completed, including editing a plan once via Ctrl+G.
Self-check 1: "fix a typo" vs. "wire up OAuth across five files" — which deserves a plan first? Justify it with the official one-line test.
Self-check 2: you approved the plan with "Yes, and use auto mode" — what permission mode is the session in now? Are you still in plan mode?