# A refactor across a few files

Course: Claude Code from Zero — https://zero2vibecode.com/learn/claude-code
Canonical URL: https://zero2vibecode.com/learn/claude-code/2-2-refactor-across-files

Multi-file changes are where an agent earns its keep and where it misses one spot. Trust nothing until you have searched for the old name yourself.

This is the work agents are genuinely, obviously good at. It is also where "it looked fine" bites hardest, because the mistake is usually somewhere you did not look.

## Ask for it precisely

> Rename `getUser` to `fetchUser` everywhere in `src/`. Update the imports. Do not change any behaviour, and do not touch the tests yet.

Four elements: the old name, the new name, where, and what stays untouched. A refactor request without a boundary tends to grow.

**Refactor and behaviour never share a turn.** 
Do the rename. Commit. Then change what the function does, in a separate turn and a separate commit. Two small readable diffs instead of one where a behaviour change hides inside a hundred renamed lines.

## Then check it yourself

The agent will tell you it renamed everything. It believes that. Believing it is not the same as it being true — a file that never came up in the conversation is a file that may never have been opened.

Here is the check, and it takes ten seconds: **search the project for the old name.** If anything comes back, the refactor is not done.

In the terminal below, the rename has already been "finished". Grep for `getUser` in each file and find the one that was missed.

## Feeding the miss back

Now you have something specific to say:

> `src/admin.js` still imports and calls `getUser`. Rename it there too.

One sentence, one file, no ambiguity. Then grep again. Zero results, and only then is the refactor real.

## Read the diff for what you did not ask for

Multi-file changes are where extras sneak in: a reordered import block, a reformatted function, a "while I was there" tweak. Each one is individually harmless and collectively makes the diff unreadable.

Ask for them to be reverted. You are not being difficult — you are keeping the change reviewable, which is the only reason review works at all.

**Tests are not proof of a complete rename.** 
A green test suite means the tested paths still work. If `src/admin.js` has no test, the old name can survive there happily until someone opens the admin page. Search, do not assume.

## The pattern to keep

1. Ask precisely, with a boundary.
2. Let it work.
3. Search for the old thing yourself.
4. Feed back exactly what is left.
5. Commit the refactor on its own.

That loop scales from a three-file rename to a much larger change. What does not scale is trusting the summary.

<Faq>
  
  
</Faq>