Investigate in plan mode before multi-file edits

Learning objective

Use plan mode for read-only discovery and design before complex multi-file changes; execute small, well-understood fixes directly.

Core idea

Plan mode separates understanding a change from applying it. Claude reads source, explores dependencies, and proposes a plan so you can correct the design before implementation. For a complex migration, a hidden shared wrapper should change the plan before callers are rewritten, rather than force a second rewrite afterwards.

Use the mode as a concrete control, not merely a sentence saying “think first.” However, read-only describes the intended source workflow; the product documents an enforcement exception for interactive terminal sessions with bypass permissions available. If source edits must be blocked during investigation, that exception matters.

See 3.4.1 for deciding whether to plan, 3.4.3 for keeping verbose discovery outside the main conversation, and 3.4.4 for the implementation handoff. Here the question is what an investigation phase actually permits and produces.

How it works

Enter planning through the documented controls

Start Claude Code with claude --permission-mode plan to choose planning at launch. In a running terminal session, use Shift+Tab until the status bar shows ⏸ plan mode on. You can also prefix a prompt with /plan to enter planning and begin that task. Read the displayed mode rather than counting key presses: the cycle includes other permission modes.

For a project’s terminal sessions, .claude/settings.json can set permissions.defaultMode to "plan". Conversations started by the VS Code extension do not read project settings for their starting permission mode. The corresponding VS Code user setting is claudeCode.initialPermissionMode with value "plan". Scope the configuration to the surface where the team works instead of assuming one project setting changes every interface.

These controls do not choose the migration architecture for you. They create the phase in which Claude can answer questions and propose it. Ask for the files involved, the dependency relationships that constrain their order, and the behavior that the proposed change preserves.

Understand the source-edit boundary

The permission-mode documentation says Claude researches, runs exploratory shell commands, and writes a plan without editing source. Except in interactive terminal sessions with bypass permissions available, edits remain blocked until plan approval. This is not a claim that the session writes no artifact at all: the planning output itself is part of the workflow.

Bypass permissions are available in the terminal mode cycle after startup with --permission-mode bypassPermissions, --dangerously-skip-permissions, or --allow-dangerously-skip-permissions, or with permissions.defaultMode: "bypassPermissions" in user, --settings, or managed settings. The --allow-dangerously-skip-permissions flag adds the mode to the cycle without activating it; availability alone matters to this exception.

In the documented bypass exception, Claude remains instructed to plan without editing, but the normal plan-mode blocks are not enforced. A file edit or shell command attempted during planning can run without prompting. Do not use that session configuration as evidence of enforced read-only discovery. The docs say plan-mode blocks remain in non-interactive -p runs, Agent SDK sessions, and VS Code chat-panel conversations.

Shell exploration also needs a precise boundary. Outside the bypass exception, when auto mode is available and useAutoModeDuringPlan is on, the classifier reviews exploratory commands; the setting is on by default. Approved commands run and rejected commands are blocked. When auto mode is unavailable or the setting is off, commands outside the built-in read-only set prompt for approval. A planning session therefore does not mean every shell command runs freely, or that every command is intrinsically read-only.

Whether a planning session blocks an action depends on the bypass exception and, for an exploratory command, on auto mode.

Keep this distinction visible when reviewing a workflow: the request says what Claude should investigate, the mode governs source modification, and command permissions govern which exploratory commands run. A natural-language instruction alone does not establish those enforcement properties.

Turn reads into design evidence

Anthropic’s planning workflow first asks Claude to understand the relevant source, then asks for an implementation plan identifying affected files and behavior. For a library replacement, investigate shared adapters before enumerating leaf replacements. A search result establishes a usage location; a focused read establishes whether it is a direct call, wrapper, or re-export that changes the migration order.

The plan should explain how those findings affect the approach. “Replace all imports” is incomplete when a shared wrapper controls retries or timeouts for its callers. Have Claude identify that wrapper and propose how its contract survives replacement. Name the relevant paths in the prompt so discovery has a bounded question rather than becoming an indiscriminate tour of the repository.

You can edit the proposed plan with Ctrl+G, which opens it in your default text editor. Review the dependency order and expected verification before proceeding. If a design question remains unresolved, stay in planning rather than treating a detailed file list as an agreed approach. The approval controls themselves are covered in 3.4.4.

Keep understood fixes proportionate

A small date-validation change with a settled rule can be requested directly. Give Claude the file, required behavior, and verification criterion. Direct execution still includes the focused reading necessary to apply the fix; it does not mean editing without examining source.

Do not expand a planning workflow merely because Claude Code supports it. Anthropic explicitly recommends direct requests for small fixes with clear scope. The useful contrast is between a focused read supporting a known change and exploratory reads that determine what the change should be.

Key distinctions and trade-offs

Discovery versus modification: Reading a dependency to explain its behavior belongs to investigation. Replacing its implementation belongs to execution. A plan can describe the replacement without performing it.

Read-only intent versus enforced blocking: Plan mode requests a source-preserving workflow. The bypass-permission exception means that request is not always an enforced source-edit barrier.

File inventory versus implementation design: Knowing every import location does not settle wrapper semantics or dependency order. The plan connects those observations to the selected changes.

Planning costs time, but moves disagreements to a phase where revising the proposal is cheap. For an understood conditional, the same review can add little information. For a multi-file migration, skipping discovery can let an unsupported assumption spread through many edits.

Architecture / decision scenario

A developer-productivity team replaces a request library used by several packages. The architect starts a terminal session with claude --permission-mode plan, without enabling bypass permissions, and asks Claude to read the shared adapter and representative callers. The investigation finds that one package uses the adapter while another duplicates its behavior.

Claude proposes a migration that establishes the replacement adapter contract first, then updates the two caller groups. The architect uses Ctrl+G to clarify that the duplicate implementation must be compared before consolidation. Source stays in the investigation phase while this decision is reviewed; the proposed plan changes instead of partially migrated callers.

A separate request adds an agreed delivery-date conditional in a known validator. The team handles it directly, with a focused source read and its existing verification command. There is no competing design to resolve through a separate plan.

If another engineer opens planning in an interactive terminal with bypass permissions available, the architect does not infer the same enforced edit boundary from the status bar. They start the planning session without any of those three bypass-related startup flags and without permissions.defaultMode: "bypassPermissions" in user, --settings, or managed settings, so the session retains plan-mode blocks for source-preserving discovery.

Common exam traps

• Treating “do not edit yet” as equivalent to a permission mode that blocks source edits.
• Claiming every plan-mode session enforces the same blocks despite the bypass exception.
• Assuming .claude/settings.json selects the VS Code extension’s starting mode.
• Treating exploratory shell commands as unrestricted or uniformly read-only.
• Calling an import inventory a design when wrapper behavior remains undecided.
• Using the full planning workflow for a known, single-function conditional.

Where the exam guide differs

What to remember

Use explicit planning controls to investigate and propose complex changes before source modification. Verify the session’s enforcement boundary, including exploratory command handling. Review dependency evidence and the design it supports; execute an already understood small fix directly.

Knowledge check

References

• Anthropic, Choose a permission mode
• Anthropic, Best practices for Claude Code
• Anthropic, Common workflows
• Anthropic, Claude Certified Architect – Foundations Exam Guide