Claude Code Best Practices: Managing Large Refactoring Projects with Plan Mode and Git Workflows
Claude Code Best Practices for Large Refactoring Projects
Managing large-scale refactoring projects with Claude Code requires a deliberate strategy. Without proper planning, you risk losing context mid-task, introducing regressions, or spending hours re-explaining requirements. This guide covers proven workflows combining plan mode, structured task breakdowns, git checkpoints, and context window optimization to keep complex refactors on track from start to finish.
1. Start Every Refactor with Plan Mode
Plan mode is your most important tool for large refactors. Before writing a single line of code, align with Claude on the full scope and approach.
Activating Plan Mode
Use the /plan command or shift+tab to toggle into plan mode. Claude will analyze the codebase and produce a structured plan without making changes.
# In Claude Code, type:
/plan Refactor the authentication module from Express middleware to a standalone service with dependency injection
Claude will respond with a multi-step plan including files to modify, dependencies to update, and a suggested execution order. Review this carefully before approving.
Refining the Plan
Push back on the plan before execution. This is far cheaper than undoing work later.
# Example conversation in plan mode:
User: Let’s not touch the session store yet - that’s a separate initiative.
User: Also, keep backward compatibility with the existing middleware signature for now.
Once the plan is finalized, Claude persists it in the conversation context and references it throughout execution.
2. Break Tasks into Atomic Units
Large refactors fail when treated as a single monolithic task. Break them into discrete, testable steps.
Task Breakdown Strategy
- Extract interfaces first — Define the target API contracts before moving code- One module per task — Refactor a single module completely before moving to the next- Tests before changes — Ensure test coverage exists for the code you are about to change- Wire up last — Integration and wiring should be a separate final step
# Use todowrite to track progress across steps: User: Break this refactor into tasks and track them.
Claude creates a task list like:
Task 1: Extract AuthService interface from existing middleware
Task 2: Implement AuthService class with DI support
Task 3: Add unit tests for AuthService
Task 4: Update middleware to delegate to AuthService
Task 5: Update route handlers to use new injection pattern
Task 6: Run full test suite and fix regressions
Each task should be completable in a single conversation turn without exhausting the context window.
3. Git Checkpoint Workflow
Commit after every successful task. This gives you rollback points and keeps the diff reviewable.
The Checkpoint Pattern
# After each completed task, instruct Claude:
User: Commit this with a descriptive message.
Claude runs:
git add -A
git commit -m “refactor(auth): extract AuthService interface from middleware”
Before starting a risky step:
git stash # or create a branch
git checkout -b refactor/auth-service-step-4
Branch Strategy for Large Refactors
| Approach | When to Use | Risk Level |
|---|---|---|
| Single feature branch | Refactor completes in one session | Low |
| Step branches merged to feature branch | Multi-session refactor, need review gates | Medium |
| Stacked PRs | Team review required at each stage | Lowest |
# Stacked branch workflow: git checkout -b refactor/auth-step-1 # ... complete step 1 ... git commit -am "refactor(auth): step 1 - extract interface"git checkout -b refactor/auth-step-2
… complete step 2 …
git commit -am “refactor(auth): step 2 - implement service”
4. Context Window Optimization
Claude Code automatically compresses earlier messages as the context fills, but you can proactively manage this for better results.
Key Strategies
- Use
/compactbetween tasks — This summarizes the conversation, freeing context for new work while preserving key decisions- Reference files by path, don’t paste — Let Claude read files with its tools rather than pasting large blocks into chat- Keep task scope small — If a single task requires reading more than 8-10 files, break it further- Leverage CLAUDE.md — Put project conventions, architecture decisions, and coding standards in yourCLAUDE.mdfile so they persist across sessions without consuming conversation context# Compact between major tasks: /compact Completed auth service extraction. Moving to test coverage.
Use CLAUDE.md for persistent context:
In your project root, create CLAUDE.md:
echo ”## Architecture
- Auth uses dependency injection via constructor
- All services implement interfaces in /src/interfaces/
Tests use real database, not mocks” > CLAUDE.md
The Session Handoff Pattern
For multi-day refactors, start each new session with a brief context reload:
# At the start of a new session:
User: I'm continuing a refactor of the auth module. Check the git log for recent
commits prefixed with refactor(auth) and review the current state of src/services/auth.
Then pick up from where we left off.
Claude will read the recent commits, examine the current code state, and resume work without you re-explaining the entire project.
Pro Tips for Power Users
- Use
/planfor impact analysis — Before starting, ask Claude to identify every file that imports or depends on the module you are refactoring. This prevents surprise breakages.- Run tests after every commit — Tell Claude to runnpm testor your equivalent after each checkpoint. Fix regressions immediately while the change is fresh.- Tag your checkpoints — Usegit tag refactor-checkpoint-1for easy rollback targets instead of hunting through commit hashes.- Use subagents for exploration — For broad codebase searches during refactoring, let Claude use its Explore subagent rather than manually reading dozens of files.- Set memory for cross-session state — If a refactor spans multiple days, ask Claude to save key architectural decisions to memory so they persist across conversations.
Troubleshooting Common Issues
| Problem | Cause | Solution |
|---|---|---|
| Claude forgets earlier decisions | Context window compressed away key info | Add decisions to CLAUDE.md or use /compact with explicit summary |
| Refactor introduces regressions | No test checkpoint between steps | Run tests after every commit, not just at the end |
| Claude suggests re-reading files it already read | Prior file reads were compressed | Use /compact proactively to keep a clean summary |
| Plan drifts from original scope | Incremental requests shifted direction | Re-enter plan mode and reconcile current state with original goals |
| Too many files changed in one step | Task granularity too coarse | Break into smaller tasks — one module or one concern per step |
How large of a refactor can Claude Code handle in a single session?
Claude Code works best when individual tasks touch 5-10 files at a time. For refactors spanning 50+ files, break the work into multiple sessions using the git checkpoint workflow and session handoff pattern described above. The key constraint is not total project size but how many files need to be in active context simultaneously.
Should I use plan mode for every task or only at the beginning?
Use plan mode at the start of the overall refactor and again whenever scope changes or you encounter unexpected complexity. For routine steps within an established plan, you can stay in normal mode. Re-entering plan mode mid-refactor is also valuable for reassessing the remaining work after completing several steps.
What happens if I need to abandon a refactor midway through?
This is exactly why the git checkpoint workflow matters. Each completed step has its own commit, so you can revert to any checkpoint using git revert or git reset. If you used step branches, simply delete the unmerged branches. The key is never making large changes without intermediate commits.