{"slug": "claude-code-plan-mode-how-i-use-it-on-real-multi-file-work", "title": "Claude Code Plan Mode: How I Use It on Real Multi-File Work", "summary": "Claude Code's plan mode splits multi-file work into a planning step and an execution step, requiring user approval before any code changes. The author uses it for changes spanning three or more files or touching auth, sync, or migrations, and recommends specific corrections to plans before allowing edits.", "body_md": "# Claude Code Plan Mode: How I Use It on Real Multi-File Work\n\nA practical guide to Claude Code plan mode: when to use it, how the approval loop works, and why serious changes need a plan you can keep.\n\nThe first time I let Claude Code take a serious auth change straight from prompt to patch, it changed nine files. Three of them were subtly wrong. The compiler was happy. The behavior was not.\n\nThe mistake was not using an agent. The mistake was letting implementation start before I understood the approach.\n\nClaude Code plan mode fixes that specific failure. It splits the work into two steps: decide what should happen, then change the code. For small edits, the extra step is unnecessary. For anything with real blast radius, it is the difference between reviewing an approach and untangling a bad patch.\n\nI use it constantly in Nimbalyst, the desktop workspace I build around Claude Code and Codex. Any time the work touches auth, sync, migrations, agent sessions, or more than a couple of files, I want the plan in front of me before the first edit lands.\n\n## What Claude Code plan mode does\n\nPlan mode is a permission mode in Claude Code. Claude can inspect the codebase, reason through the task, and propose an implementation plan. It waits for approval before making changes.\n\nYou can start Claude Code in plan mode:\n\n```\nclaude --permission-mode plan\n```\n\nYou can also switch modes during a session with the Claude Code shortcut. In most terminals, `Shift+Tab`\n\ncycles through the available permission modes, including plan mode. Some setups use `Alt+M`\n\ninstead.\n\nThe shortcut is just mechanics. The value is the checkpoint. Before Claude edits files, you get to see:\n\n- Which files it thinks matter\n- What order it intends to change them in\n- What assumptions it is making\n- What it plans to test\n\nPush back there. Once there is a nine-file diff, you are already paying the expensive version of the review.\n\n## When I use plan mode\n\nI turn on plan mode when a wrong assumption would be expensive. In practice, that means:\n\n- A change spans three or more files\n- The work touches auth, permissions, sync, billing, migrations, or data loss risk\n- I am asking Claude to infer an architecture it may not understand yet\n- The code path has side effects I cannot check by glancing at one file\n- The final diff will need a careful human review anyway\n\nI skip it for the obvious stuff: a typo, a small copy edit, a single-file fix, a quick rename, or a prototype I expect to throw away.\n\nPlan mode is not ceremony. It is a filter. If a bad direction would be cheap to fix, just make the edit. If it would be painful, make the agent show its direction first.\n\n## How to use plan mode in Claude Code\n\nStart in plan mode. Give Claude the task and the constraints. Let it read. Then read the plan like the opening comment on a pull request from a developer you trust but still review carefully.\n\nI look for four things:\n\n- Did it find the right files?\n- Is it using existing helpers and patterns?\n- Is the order of work safe?\n- Did it name the tests or checks that would prove the change works?\n\nIf the answer to any of those is no, I do not let it edit yet. I correct the plan.\n\nCorrections need to be specific. “Be careful with auth” is too vague. “Use the existing org-scoped JWT helper and do not read tokens from environment variables” is the kind of instruction that changes the result.\n\nOnce the plan is specific enough that I would be comfortable assigning it to a teammate, I leave plan mode and let Claude execute. Auto-accept can be useful at that point, but only after the plan is clear. Auto-accept without a good plan is just a faster way to create review work.\n\n## A good plan is concrete\n\nWeak plans sound like this:\n\nUpdate the relevant files, add tests, and ensure everything works.\n\nThat is not a plan. It is a placeholder.\n\nA useful plan names the files, the sequence, the existing conventions, and the verification path. For example:\n\nFirst inspect the current session-token helpers and the IPC path that calls them. Then update the call site to use the existing org-scoped token helper. Add a regression test for the team workspace case. Run the focused auth tests before touching unrelated cleanup.\n\nI want that level of detail before edits begin. It gives me something to approve, reject, or rewrite.\n\nMy rule: if the plan could apply to almost any codebase, it is too generic. Make it name your code.\n\n## Where plan mode falls short\n\nClaude Code’s plan mode is useful. The weak spot, at least in the terminal workflow, is where the plan lives.\n\nThe plan is usually something you read, approve, and then lose track of while the implementation scrolls by. For serious work, that is backwards. The plan is often the most valuable artifact in the session because it captures the reasoning before the code starts changing.\n\nI want that plan beside the diff. I want to check each edit against the step it was supposed to satisfy. I want to hand the plan to another developer before implementation starts. And if the change turns out to be wrong a month later, I want to see the reasoning that led us there.\n\nThat is one reason I built Nimbalyst around persistent planning. I keep the plan as a real markdown document in the workspace, next to the generated diff and the agent session. When I run several tasks in parallel, I pair each plan with its own [git worktree](/blog/git-worktrees-for-ai-coding-agents-complete-guide/) so the code, context, and reasoning stay isolated.\n\nThis does not replace Claude Code plan mode. It makes the output easier to keep, edit, compare, and review after the terminal has moved on.\n\n## The takeaway\n\nUse Claude Code plan mode when the change is large enough that you would want a human developer to explain their approach first.\n\nThat is the real standard. Three files? Plan first. Auth or migrations? Plan first. Unfamiliar code? Plan first. A diff you already know you will review line by line? Plan first.\n\nThe benefit is not that Claude “thinks harder.” The benefit is seeing the thinking while it is still cheap to correct. A bad plan is a paragraph. A bad implementation is an afternoon.\n\nAnd if the plan matters, keep it. Do not let the most considered part of the session disappear as soon as the code starts changing.\n\n## Related pages\n\n## Related posts\n\n-\n### Best Claude Code Skills in 2026 (Ranked)\n\nThe best Claude Code skills in 2026, ranked by day to day usefulness: code review, test writing, parallel batch work, debugging, release flows, and one visual bundle from Nimbalyst.\n\n-\n### Claude Code Plugins: A 2026 Guide\n\nClaude Code plugins explained: what they are, how they extend the agent, and how plugins relate to MCP servers, skills, and Nimbalyst extensions.\n\n-\n### Claude Code Skills: A Practical 2026 Guide\n\nClaude Code skills explained: what they are, how to write one, the best built-in skills, and how skills differ from MCP servers and subagents.", "url": "https://wpnews.pro/news/claude-code-plan-mode-how-i-use-it-on-real-multi-file-work", "canonical_source": "https://nimbalyst.com/blog/claude-code-plan-mode/", "published_at": "2026-06-29 00:00:00+00:00", "updated_at": "2026-06-29 16:21:20.379804+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models"], "entities": ["Claude Code", "Nimbalyst", "Codex"], "alternates": {"html": "https://wpnews.pro/news/claude-code-plan-mode-how-i-use-it-on-real-multi-file-work", "markdown": "https://wpnews.pro/news/claude-code-plan-mode-how-i-use-it-on-real-multi-file-work.md", "text": "https://wpnews.pro/news/claude-code-plan-mode-how-i-use-it-on-real-multi-file-work.txt", "jsonld": "https://wpnews.pro/news/claude-code-plan-mode-how-i-use-it-on-real-multi-file-work.jsonld"}}