How to Use Claude Code's Plan Mode to Break Down Complex Refactoring Tasks
How to Use Claude Code’s Plan Mode to Break Down Complex Refactoring Tasks
Large-scale refactoring — migrating a codebase from one framework to another, restructuring a monolith into modules, or overhauling a legacy API — can be overwhelming. Claude Code’s Plan Mode gives you a structured way to decompose these tasks into discrete, trackable steps before any code is changed. This guide walks you through the complete workflow from planning to execution.
Prerequisites
- Node.js 18 or later installed- An Anthropic API key (or a Claude Pro/Max subscription)- A terminal environment (macOS, Linux, or Windows with WSL/Git Bash)
Step 1: Install and Configure Claude Code
Install Claude Code globally from npm and run the authentication flow:
npm install -g @anthropic-ai/claude-code
claude
On first launch, follow the prompts to authenticate
If using an API key directly:
export ANTHROPIC_API_KEY=YOUR_API_KEY
Navigate to your project directory so Claude Code has full context of the codebase:
cd /path/to/your-project
claude
Step 2: Enter Plan Mode
By default, Claude Code operates in **Act Mode**, where it reads and edits files directly. To switch to Plan Mode — where it analyzes and plans without making changes — press Shift+Tab in the interactive prompt. You will see the mode indicator change:
# The prompt indicator changes to show you're in Plan Mode:
(plan) >
You can also type /plan as a shorthand to toggle into Plan Mode. While in Plan Mode, Claude Code will reason about your codebase, outline steps, and produce a structured plan — but it will **not** execute any file edits or shell commands.
Step 3: Describe Your Refactoring Goal
Give Claude Code a clear, specific description of your refactoring objective. The more context you provide, the better the plan:
(plan) > Refactor the Express.js REST API in /src/api to use a layered
architecture: separate route handlers into controllers/, business logic
into services/, and database queries into repositories/. Keep all
existing tests passing. The codebase uses TypeScript and Prisma ORM.
Claude Code will analyze the directory structure, read relevant files, and produce a multi-step plan like this:
Plan: Refactor Express API to Layered Architecture
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
☐ Step 1: Create directory structure (controllers/, services/, repositories/)
☐ Step 2: Extract database queries from route handlers into repository files
☐ Step 3: Create service layer that calls repositories and contains business logic
☐ Step 4: Refactor route handlers into thin controllers that delegate to services
☐ Step 5: Update dependency injection and imports across all modules
☐ Step 6: Run existing test suite and fix any broken imports or references
☐ Step 7: Add barrel exports (index.ts) for each new directory
Step 4: Review and Refine the Plan
Plan Mode is interactive. You can refine the plan before any code is touched:
(plan) > Add a step to create integration tests for the new service layer.
Also, move Step 7 (barrel exports) to right after Step 1 so imports are
available early.
Claude Code will regenerate the plan with your adjustments. Continue iterating until the plan matches your expectations. Common refinements include:
- Reordering steps to manage dependencies correctly- Adding constraints like "do not modify any test fixtures"- Splitting a large step into smaller sub-steps- Scoping down to a single module first as a pilot
## Step 5: Execute the Plan Step by Step
Once the plan looks right, switch back to Act Mode by pressing Shift+Tab again and instruct Claude Code to begin:
(act) > Execute the plan starting from Step 1
Claude Code will work through each step sequentially. After each step, it reports what was done and marks the step complete:
✔ Step 1: Created controllers/, services/, repositories/ directories
Created: src/api/controllers/
Created: src/api/services/
Created: src/api/repositories/
Created: src/api/controllers/index.ts (barrel export)
▶ Step 2: Extracting database queries into repositories…
You can pause execution at any point by interrupting with Esc and reviewing the changes before continuing.
Step 6: Track Progress and Handle Errors
If a step fails — for example, a test breaks after moving code — Claude Code will stop and report the issue:
✘ Step 6: Test suite failed
FAIL src/api/tests/users.test.ts
- Cannot find module ’../handlers/userHandler’
Suggested fix: Update import path to ’../controllers/userController’
You can then instruct Claude Code to fix the issue and continue:
(act) > Fix the broken import and continue with the remaining steps
For long-running refactors, you can also check progress at any time:
(plan) > Show current plan status
Pro Tips for Power Users
| Tip | Details |
|---|---|
| **Scope the pilot** | Start with one module (e.g., users) before applying the pattern to the full codebase. Use: *"Apply only to the users module first."* |
| **Use CLAUDE.md** | Add project conventions to a CLAUDE.md file in your repo root. Claude Code reads this automatically and respects patterns like naming conventions, import styles, and test frameworks. |
| **Combine with git** | Commit after each major step so you can git diff and git revert individual steps independently. |
| **Headless mode for CI** | Run plans non-interactively with claude -p "Execute the refactoring plan in PLAN.md" for integration into CI pipelines. |
| **Multi-file awareness** | Claude Code automatically tracks cross-file dependencies. If renaming a function, it updates all callers — but always verify with grep or your test suite. |
Plan Mode does not activate
Ensure you are running Claude Code version 1.0 or later. Update with npm update -g @anthropic-ai/claude-code. The Shift+Tab toggle requires the interactive terminal — it will not work in piped or headless mode.
Plan is too vague or generic
Provide more specific context in your prompt. Reference exact file paths, framework versions, and constraints. For example, instead of “refactor the API,” say “refactor src/api/routes/*.ts to separate controller logic from Prisma queries.”
Execution skips steps or loses context
For very large codebases, Claude Code may hit context limits. Break the plan into phases (e.g., “Phase 1: repositories only”) and execute each phase in a fresh session. Use CLAUDE.md to persist conventions across sessions.
Permission denied errors during execution
Claude Code asks for confirmation before risky operations. If a tool call is blocked, check your permission settings with /permissions and add trusted paths as needed.
Frequently Asked Questions
Can I save a plan and resume it in a later session?
Yes. You can ask Claude Code to write the plan to a markdown file (e.g., PLAN.md) in your project directory. In a new session, reference that file: “Load and continue the plan in PLAN.md.” Claude Code will read the file, understand the step statuses, and pick up where you left off. Combining this with git commits per step makes resumption seamless.
How does Plan Mode differ from just asking Claude Code to refactor directly?
Without Plan Mode, Claude Code may attempt to execute the entire refactoring in one pass, which increases the risk of errors and makes it harder to review changes. Plan Mode forces a two-phase approach: first you agree on what will be done, then execution happens step by step with tracking. This gives you a checkpoint after every step and the ability to course-correct before more code is changed.
Is there a limit to how many steps a plan can have?
There is no hard limit on the number of steps. However, plans with more than 15–20 steps can become difficult to manage in a single session due to context window constraints. For very large refactors, it is best to organize the work into multiple phases of 5–10 steps each, executing and committing one phase at a time.