Incremental Refactoring Loop — Claude Code Guide

Safe refactoring is a sequence of small steps

Incremental refactoring is not a broad “improve the whole class” effort. Each step has one goal, a safety net, a bounded area, targeted verification, and a separate rollback.

1. State one narrow structural goal.
2. Check CLAUDE.md, the harness, tests, and characterization.
3. Limit the request to a specific method or file.
4. Forbid changes to the public API, messages, dependencies, and unrelated files.
5. Make the minimal change.
6. Run the affected test, build, or lint.
7. Read the complete diff.
8. Create a separate commit after confirmation.

Example of a narrow request

Goal: extract validation from finalizeOrder
Allowed: one service file and its focused tests
Must preserve: public API, messages, order of business checks
Forbidden: dependency updates, formatting sweep, unrelated cleanup
Check: focused tests plus local harness
Stop: if another module or contract must change

The diff matters more than a feeling of safety

A reviewer-agent can classify the result as behavior preservation, behavior change, or insufficient data. This is an additional check, not a replacement for human review.

• check file and module boundaries;
• find unnecessary changes and renames;
• check the public API and messages;
• match every line to the step goal;
• do not accept an unclear diff merely because tests are green.

When to stop and roll back

Pause after every commit

Refactoring ends with a pause after a separate commit. The next transformation starts with a new plan and a new cycle, not as a continuation of an endless cleanup.