Refactoring with Claude Code: plan, small steps and green tests

What Claude Code does for refactoring

• Works through a refactoring backlog in small steps, each its own pull request.
• Runs the tests before and after every step, and stops when they fail.
• Does the mechanical part of migrations: renames across the codebase, API upgrades, a move to a new library.
• Removes dead code and duplicated logic, and explains each removal.

Claude Code features for refactoring

How to set up Claude Code for refactoring

1. Connect the tools

   There's nothing to connect. What makes a refactor safe is a test command Claude can run and a limit on the size of each step, so put both in CLAUDE.md and start in a worktree.

   # Start the refactor in its own worktree
   claude --worktree billing-async
   
   # Agree on the plan before any edit
   /plan Move the billing module from callbacks to async/await

2. Write the rules in CLAUDE.md

   Claude Code reads CLAUDE.md at the start of every session, claude -p runs included. Put the job's rules there, or in a skill under .claude/skills/ if they're long. See the CLAUDE.md guide.

   ## Refactoring rules
   - No behaviour changes. If a test has to change, stop and ask.
   - Run `npm test` before you start and after every step.
   - One step per pull request, under 400 changed lines.
   - Keep REFACTOR.md current: check off what's done, add what
     you found.
   - Don't touch migrations/, generated files or public APIs
     without asking.

3. Run it without the interactive interface

   claude -p runs one task and exits, so cron, CI or another tool can start it. Choose what it may do without asking with --allowedTools or --permission-mode; --output-format json returns the result with its cost.

   # One step a day from the backlog in REFACTOR.md
   claude -p "Do the next unchecked item in REFACTOR.md and keep the tests green" \
     --allowedTools "Bash(npm test),Read,Edit"

4. Put it on a schedule

   Make it a cloud scheduled task with /schedule (Pro, Max, Ultra, Team and Enterprise), a desktop scheduled task, or /loop while a session stays open. See how to make Claude Code proactive.

Source: Claude Code documentation

Limits and safety

• Without tests it can't tell a refactor from a behaviour change. Add tests for the area first.
• A large rewrite in one pass is hard to review. Small steps that each merge are safer, and faster in the end.
• It doesn't know which odd code is deliberate. Mark those places with a comment or in the rules.
• Since Claude Code v2.1.302, claude -p starts in Manual mode: an action that needs approval is denied unless a rule allows it. Allow only the tools the job needs.

Claude Code or Codex for refactoring?

The rules carry over. Write them once in AGENTS.md and put @AGENTS.md in CLAUDE.md, and both agents read the same file.

Step by step for the other agent: refactoring with Codex.

Make refactoring someone's job

Commands run when someone remembers to run them. Crewmark turns your own Claude Code into an AI employee with a role, a goal in numbers, working hours and a heartbeat, so the work happens on schedule and shows up on a board.

1. Start from the role

   The AI software engineer, with these rules in its brief.

2. Put the work on its board

   Add the job as a recurring issue. The employee wakes on its heartbeat, does it and reports in a comment.

3. Related

   Code review checks each step before it merges.

FAQ