Plan Big Refactors Safely with Claude Code

How to use Claude Code plan mode and the `opusplan` stack to run large, cross-cutting repository changes through a spec-first, branch-safe workflow tied to PRs and CI.

Claude Code plan mode for large repository changes: the short version If your change touches multiple files, spans services, or risks breaking auth, billing or compliance flows, Claude Code’s plan mode should be your default entry point. Plan mode is a read-only state that makes Claude propose a concrete edit plan before touching your working tree, as described in Anthropic’s Claude Academy guide on plan mode . The opusplan model alias routes planning to an Opus‑class model and execution to a Sonnet‑class model, according to Anthropic’s model configuration docs , so you pay higher‑tier rates only for the planning step. Treat that plan as a design artefact, wire it into branches, PRs and CI, and reserve 1M-context planning for genuinely cross-cutting work. Under Anthropic’s current list prices for Claude models in the Claude Model Pricing PDF , a well-scoped, plan-first large change can plausibly land in single-digit US dollars of API spend, depending on how many tokens your plan and edits consume; that estimate is based on multiplying the published per-million-token rates by rough token counts for a large refactor, not on observed billing data. If you mainly do trivial, local edits, the overhead of plan mode is not worth it. For recurring, mechanical changes in a repo with strong CI, auto-accept or Sonnet-only loops are cheaper and fast enough. For the rest, plug plan mode into your broader AI development workflow so it complements the prompt-to-production loop you already use and the wider AI development stack you pick for 2026 . Where Claude Code plan mode fits in your stack Anthropic’s Help Center describes Claude Code as tooling that lets you delegate coding tasks to Claude from your development environment (including the terminal), using natural-language instructions. According to the Claude pricing page , Claude Code is available to users on Claude Pro, Claude Max, Team and Enterprise plans, and is not available on the Free plan. Plan mode is one of its core permission modes and is positioned by Anthropic’s own education content as the default starting point for complex or multi-file work. The Claude pricing page confirms that Claude Code is bundled with Pro, Max and higher tiers, so plan mode usage is constrained by plan-level limits rather than separate API pricing. For a broader view of Claude Code’s agent model and how it compares to other terminal agents, see the separate breakdown on Claude Code as a terminal-first agent . Here the focus is specifically on how to use plan mode for large repository changes and how it plugs into the wider AI development stack you pick for 2026 . Decision rule: when to use plan mode vs normal vs auto-accept Use this mental decision tree as a starting policy: Trivial, single-file, low-risk change (e.g. copy tweaks, a one-line bug fix with an obvious failing test): Use Claude Code in normal mode or an IDE agent like Cursor or Copilot. Plan mode overhead adds little safety. Medium, multi-file, scoped change (e.g. refactor within a service, swap a library, add a feature touching a few modules): Use plan mode with Sonnet or opusplan at ≤200k context. Plan once, execute in one or two passes. Large, cross-service or business-critical change (e.g. payments flow updates, auth migration, cross-cut logging rollout): Use plan mode with opusplan . Treat the plan as a spec, tie it to a feature branch and PR, and gate each plan checkpoint with tests and code review. Highly repetitive, well-tested bulk change (e.g. dependency bumps, regenerating a known-safe codegen layer): Once patterns are proven, consider auto-accept with a cheaper model plus strong CI. Very large monorepo, broad migration (e.g. framework upgrade across dozens of services): Use opusplan with 1M context sparingly for the global plan, then execute via narrower ≤200k-context passes where possible. How Claude Code plan mode actually works Permission modes in Claude Code Claude Code exposes multiple “permission modes” that govern how it acts on your repository. Anthropic’s plan-mode overview explains that plan mode is a read-only workflow state: Claude can read your repo, design a plan, and show proposed edits, but it does not write files until you explicitly approve. The broader permission model and safe production patterns are covered in more detail in the dedicated piece on Claude Code permissions and production architecture. Claude Code in plan mode presents a read-only multi-step plan in the terminal before it is allowed to touch your working tree. At a high level for large changes: Normal mode : Claude can read files and apply edits with your confirmation on a per-action basis. Plan mode : Claude must first produce a structured plan of changes. Only after you review and approve can it execute that plan. Auto-accept : Claude can apply changes without asking each time—better suited to repetitive, low-risk operations under strong CI. Anthropic’s Academy content presents plan mode as the default entry point for complex or multi-file work because it forces a separation between exploration/design and execution. Model aliases and the opusplan stack Claude Code lets you choose models via aliases. According to Anthropic’s model configuration documentation , Claude Code exposes convenient aliases such as sonnet and opus that route to Sonnet-class and Opus-class models, and a special opusplan alias that uses an Opus-class model for planning and a Sonnet-class model for execution. Claude Code also supports up to a 1M-token context window on supported models; you can opt into these larger contexts via the documented model and settings options in the Claude Code docs. This split is the key to treating plan mode as a distinct SDLC pattern. Opus-class models are Anthropic’s higher-priced, deeper-reasoning tier, while Sonnet-class models are cheaper and still strong for code editing. The current Claude Model Pricing PDF lists, per 1M tokens, standard input and output prices for each model tier; for example, Sonnet-class models on the standard API are priced at US$3.00 per million input tokens and US$15.00 per million output tokens, and Opus-class models at higher rates as shown in the official PDF, with the same prices applying across the full supported context window, up to 1M tokens on the Claude Platform. Using opusplan means you pay Opus-class rates only for the planning phase, then Sonnet-class rates for execution. That is the main economic lever that can make plan-first workflows cheaper per successful large change than either “Opus everywhere” or repeated trial-and-error with an IDE agent, especially once you add the cost discipline from the Claude pricing breakdown for 2026 . What happens when you enter plan mode Based on Anthropic’s Academy explanation and external tutorials such as DataCamp’s walkthrough of plan mode, the sequence for a large change is: You start a plan-mode session (e.g. via a CLI flag or command). Claude reads the relevant parts of your repository into its context. With supported large-context models, it can hold up to ~1M tokens in view, which Anthropic’s model-config docs describe as suitable for large repositories. You describe the desired change and constraints in natural language. Claude produces a multi-step plan, often listing impacted files, functions and migration steps. No files are modified yet; the plan is a read-only artefact. You can iterate on the plan (add constraints, remove risky steps, split phases). Once you approve, Claude executes the plan in normal mode semantics—reading and editing files with a Sonnet-class model under the hood when using opusplan . The terminal UX backs this design-then-apply model: you should see plan mode active, a list of steps, and no diffs applied until you explicitly approve execution. Setting up Claude Code for plan-first workflows Install and connect Claude Code Anthropic’s Claude Code FAQ documents installation via package managers such as npm and WinGet. In parallel, Anthropic’s help article on your first day in Claude Code notes that Claude Code is available on Claude Pro and Max plans and in Team/Enterprise deployments, but not for Free. For a plan-first workflow on a production repo: Confirm you are on a paid Claude plan that includes Claude Code access—currently Claude Pro (US$25/month billed monthly or US$20/month equivalent on an annual plan) or a Claude Max tier (US$100/month for approximately 5× Pro capacity or US$200/month for approximately 20× Pro capacity), per the latest “Choose a Claude plan” help article and the Claude pricing and tiers breakdown for 2026 . Install Claude Code (CLI and/or desktop) and authenticate with your Claude account or SSO for Team/Enterprise. Verify Claude Code can see your local repositories and run your usual build/test commands. Configure models and opusplan From Anthropic’s model-config docs: Set your default model to a Sonnet-class alias such as sonnet for day-to-day work. Use opusplan explicitly for large, riskier changes where Opus-level planning is warranted. Only switch to large-context variants when the change truly needs a near-1M-token context. A practical pattern: Default: sonnet , standard context, normal mode. “Big change session”: opusplan , standard context, plan mode enabled. “Monorepo migration session”: opusplan with a large-context Opus-class model for the initial planning pass, then drop back to standard-context Sonnet-class for focused execution. Prepare the repository for an AI agent The same hygiene that helps other code-focused AI agents also helps Claude Code. The piece on setting up a production repo for Codex covers these in more depth; the principles carry across: Add a CLAUDE.md at the root describing the system, key modules, test commands, and constraints. Prune or de-emphasise generated artefacts, build outputs, and giant logs that waste context. Standardise npm test / pnpm test / pytest / etc. so Claude can run tests as part of its flow. Document environment variables and secrets handling; Claude should not be encouraged to hard-code keys. Good repository structure also reduces the need for 1M context by letting you scope Claude’s view to the relevant subtrees. For Claude-specific repo guidance, see the patterns in structuring CLAUDE.md so Claude Code follows it. Branch strategy: never plan on main For large or risky changes, Claude Code should operate on a feature branch, not directly on main : Create a feature branch for the change (e.g. feat/payments-v2 ). Run plan mode and execution only on this branch. Open a PR from this branch into main , attaching the exported plan. Let CI and reviewers treat the plan as a spec. This aligns with the Codex/GitHub workflow covered in the article on a safe branch-to-PR workflow and adapts it to Claude Code’s plan artefacts. Investigation: using plan mode to understand a large codebase First contact with a big repo In a new or complex repository, jumping straight to “edit this file” is risky. Instead, use plan mode for investigation-only sessions where you explicitly forbid edits: Ask Claude: “Walk through the architecture of this repo. Summarise key services and their responsibilities, focusing on auth and billing.” Request dependency maps: “List the main call paths into BillingService and identify where external payment providers are integrated.” Use reading mode to open key entrypoints and configuration files, letting Claude narrate. With large-context models, Claude can hold more of the repository in memory, but Anthropic’s pricing PDF shows that costs scale linearly with tokens. For investigation, it is usually preferable to stay within standard context sizes and only step up to near-1M-token context if there is a clear need to view whole subsystems in one go. Structure your investigation prompts A repeatable pattern: Problem statement : What must change and why (“The team needs to migrate payment provider from A to B”). Constraints : Uptime, backwards compatibility, regions, compliance requirements. Risk areas : Data flows, stateful services, external APIs. Non-goals : What must not change (e.g. pricing logic). Use plan mode to ask Claude for: A list of impacted modules and services. Existing feature flags or rollout mechanisms. Current tests and monitoring that cover the area. External tutorials such as DataCamp’s guide on plan mode recommend this kind of upfront scoping and note that plan mode is overkill for trivial edits; their emphasis aligns with making investigation a deliberate step for large changes. Capture investigation outputs as artefacts Before any code changes: Ask Claude to summarise the findings into a markdown spec. Save this as docs/payments-migration-notes.md or in your ticketing system. Link it in the eventual PR so reviewers see the reasoning, not just the diff. That spec becomes input to the planning phase and a reference if the change needs to be revisited later. Designing the change: from investigation to plan Turn notes into a structured plan With investigation done, stay in plan mode and ask Claude to convert the notes into a stepwise change plan : Split into phases: e.g. scaffolding, dual-write, migration, clean-up. For each phase, enumerate files, functions, and config changes. Attach acceptance criteria and test commands per phase. Concrete prompt shape: Using the investigation notes in docs/payments-migration-notes.md, propose a 4-phase implementation plan. For each phase, specify: - Files to touch - Public APIs affected - Tests to run - Rollback strategy if tests fail Do not apply any edits yet. Claude’s plan output in the terminal should now be something that can be pasted directly into a design doc or PR description. Negotiate the plan Plan mode exists to be argued with. Useful adjustments include: Removing risky steps (e.g. no direct schema changes without dual-write). Adding feature flags or config toggles to guard rollouts. Injecting monitoring or logging steps into the plan. Splitting an oversized step into smaller checkpoints. Keep revising until the plan is something that would be acceptable from a junior engineer. Only then move to execution. Version the plan as a first-class artefact Once the plan is agreed: Ask Claude to output the final plan in markdown. Save it as CLAUDE_PLAN.md in the branch or paste it into the PR description. Optionally, include a “mapping” section: plan step → commits/tests. A screenshot here should show a CLAUDE_PLAN.md file or PR description containing the exported plan. That is the bridge between the AI’s internal reasoning and your human review and CI history. Executing the plan: safe application of changes Switch from planning to execution without losing the spec With CLAUDE_PLAN.md committed or otherwise persisted: Tell Claude explicitly: “The plan in CLAUDE_PLAN.md has been agreed. Implement step 1 only.” Stay on the feature branch. Keep opusplan if execution still needs deep reasoning, or switch to sonnet if the edits are now mechanical. Execution under opusplan uses a Sonnet-class model for edits. Based on Anthropic’s current list prices, that means paying the standard Sonnet per-million-token rates (US$3.00 per million input tokens and US$15.00 per million output tokens on the standard API), with the same pricing applying across the full supported context window. Review diffs and run tests per checkpoint For each plan step: Have Claude apply changes and summarise the diff. Inspect diffs locally; do not rely solely on the model’s summary. Run the specific tests listed for that step. Commit with a message that references the plan step. Where possible, let Claude run tests directly (it can invoke your test commands) and then interpret failures, but always keep human oversight on go/no-go decisions. Handling conflicts, partial adoption and plan drift Real repositories move during implementation. To handle this: If conflicts arise , resolve them by hand or ask Claude to propose resolutions, then re-run relevant tests. If reality invalidates a plan step (e.g. an API no longer exists), pause execution and go back to plan mode to revise the spec. Document deviations, either by editing CLAUDE_PLAN.md or appending a “Change notes” section in the PR. Plan drift is a specific failure mode for AI-driven changes; treating the plan as versioned documentation helps keep reality and the AI’s mental model aligned. Working with very large repositories When to use 1M context Anthropic’s current documentation states that supported Claude models, including Sonnet-class and Opus-class, offer up to a 1M-token context window on paid plans, with the official pricing PDF indicating that the same per-million-token prices apply across the full context window on the Claude Platform. Using the brief’s example scenarios and published per-1M-token prices, some illustrative estimates are: Opus-planned, Sonnet-executed at standard context (single cross-service refactor): Assume 150k input + 50k output tokens for Opus-class planning and 200k input + 100k output for Sonnet-class execution. Planning cost ≈ (0.15 × Opus input rate) + (0.05 × Opus output rate). Execution cost ≈ (0.2 × Sonnet input rate) + (0.1 × Sonnet output rate). Total will typically fall in the single-digit US-dollar range at current list prices. Opus-planned with larger context, Sonnet execution (very large monorepo migration): Assume 400k input + 150k output tokens for Opus-class planning and 300k input + 150k output for Sonnet-class execution. Costs scale linearly with tokens using the same per-million rates; higher token counts push per-run cost into the tens of dollars. Sonnet-only plan-first loop at standard context (medium change): Assume 120k input + 40k output tokens for planning and 150k input + 60k output for execution. Multiplying these token counts by the Sonnet per-million rates yields a low single-digit US-dollar total per change. These are derived estimates based on Anthropic’s published token prices and the token volumes in the brief’s scenarios, not observed billing data. They illustrate that very large, high-context Opus planning pushes per-change cost into the tens of dollars, which is acceptable for critical migrations but expensive for routine work. Scope the repo to avoid 1M context when possible Instead of defaulting to near-1M-token context for big repos: Use CLAUDE.md to tell Claude which directories matter for a given change. Ask it to limit its view (e.g. “Only consider services/payments and libs/billing for this plan”). Split changes by subsystem and run separate plan+execute loops. This keeps you in standard-context territory for most work, keeping per-change cost lower while retaining the safety benefits of plan mode. Watch for context truncation and plan blind spots With large repos, context limits can silently drop files from view. To reduce this risk: Periodically ask Claude to list which files it considered when building the plan. Cross-check critical modules (auth, billing, compliance) are actually referenced. If not, either rescope the repo or temporarily step up to larger-context models for the planning pass. GitHub, PRs and CI: turning plans into governance Map plan steps to branches and PRs For production work, the plan should be embedded in your normal GitHub workflow: Branch : Create a feature branch dedicated to the plan. Plan file : Commit CLAUDE_PLAN.md with the initial plan. Commits : Use commit messages like step 1: add dual-write for payments (per CLAUDE_PLAN) . PR : Open a PR referencing the plan and linking key investigation docs. The article on a Codex + Vercel preview-to-production workflow shows how branch-only deploys and preview environments can gate changes; the same structure works for Claude Code plans. Use CI as a gate between plan checkpoints For each plan checkpoint, configure CI to: Run the specified tests. Optionally build preview environments (e.g. via Vercel or a similar platform) for manual QA. Block merges if tests fail or monitored metrics regress. Plan mode is a design discipline, not a testing substitute. Teams without reliable automated tests or CI will not get the full safety benefit; the impact is highest when every plan step is backed by automated checks. Cost discipline on Pro/Max vs API Pro/Max: opportunity cost instead of per-token billing On Claude Pro and Max, pricing is flat monthly with usage limits rather than explicit per-token charges, per the pricing page. The real marginal cost of heavy opusplan use is opportunity cost : burning through your allocation and hitting soft limits sooner. A handful of large, high-context opusplan runs per month can consume a significant fraction of the high-usage allowance on Max, simply because Opus-class planning with large contexts is the most expensive configuration in per-token terms. That makes it rational to: Reserve large-context opusplan for the highest-risk, cross-cutting changes. Use Sonnet-only planning for medium-sized work. Prefer standard context sizes unless very large contexts are clearly necessary. For a deeper breakdown of when to stay on Pro/Max versus moving heavy workloads to the API, see the piece on Claude pricing and choosing the right tier . API/Enterprise: use opusplan as a costed SDLC step On the API or Enterprise side, costs can be estimated for a large change from the token assumptions earlier. The key levers are: Choosing opusplan vs Sonnet-only planning. Staying at standard context vs very large contexts. Controlling the number of re-planning cycles. With a disciplined investigation → plan → execution workflow, one cross-service change can land around a single-digit US-dollar amount of API spend under a standard-context opusplan scenario. Multiple trial-and-error cycles with ad-hoc editing can easily exceed that while still offering less predictability. Plan mode vs IDE agents and auto-accept Claude Code vs Cursor and other IDE-centric agents IDE agents like Cursor excel at rapid, local edits and inline feedback. Claude Code, especially in plan mode, is closer to a terminal-native teammate that runs commands, edits files and talks through changes. For deciding where plan mode sits alongside tools like Cursor and GitHub Copilot, see the separate comparison on Cursor vs Claude Code vs IDE or terminal agents and the broader GitHub Copilot vs Cursor comparison for 2026 . The key takeaway for large repo changes: Use Claude Code plan mode for cross-cutting, multi-file work where a global plan and explicit approvals are needed. Use Cursor or similar inside the IDE for smaller refactors and line-level improvements. Let GitHub and CI own the final governance via branches, PRs and tests. When auto-accept is justified Auto-accept removes friction but also removes one of the safety levers. Shift into auto-accept only when: The change pattern is highly repetitive (e.g. regenerating a codegen layer). CI is fast and trustworthy . The pattern has already been proven through several plan-mode runs. At that point, human-in-the-loop review of each small plan can add less marginal safety than simply letting CI enforce correctness. When to change your decision on plan mode Plan mode is not always the right answer. Based on the decision brief and the dynamics above: Flip to normal mode or an IDE agent when the change is trivial and contained. The overhead of generating and reviewing an Opus-backed plan is slower and more expensive than just applying a quick edit and reviewing a single diff. Flip to auto-accept or Sonnet-only when running the same mechanical changes repeatedly under strong CI; plan review adds less value. Enforce opusplan with explicit design review when changes cross compliance-critical or business-critical flows; the extra reasoning and repository visibility justify higher token costs. Stay in standard context rather than very large contexts when a large repo change can be scoped cleanly to a subsystem, using CLAUDE.md and directory constraints to avoid unnecessary large-context usage. Use plan mode as an occasiona