ClaudeRefactoringLevel 2: Context

Should You Rename Code Before Refactoring It?

Yes, if the names are vague. Do one pass that changes only names, as its own commit, then decide on structure. Clear names often show you where the code should split. Watch one trap in Claude Code: its Edit tool replaces exact text, so a short name can match things you didn't mean.

Prompt to copy 
Read [file or function]. Propose better names for variables, parameters and helpers, based on what each one actually does. Give me a table: old name, new name, why. Flag any name that's exported, stored in a database, sent over an API or read from config, and leave those out for now.

Don't edit anything yet. After I approve the table, rename only those, with no structural changes and no reformatting. Find every reference first, and don't do a blanket text replace on short names.

Finish by running [type-check command] and [test command], and show me the output and `git diff --stat`.
Safe in a names-only passNeeds its own plan
  • Local variable
  • Private function
  • Exported name
  • Stored JSON key
Rule of thumb, not an Anthropic chart. Positions show rough order only. Exported and stored names are contracts, so keep them out of a names-only pass.

Try it now

  1. 1Run /effort low in Claude Code, and send the prompt.
  2. 2Trim the table. Reject anything clever, and check the flagged names yourself.
  3. 3After the rename, read it with git diff --word-diff, which shows changes word by word. It should show only identifiers changing.
  4. 4Commit it on its own. It worked if the tests pass with no test logic changed, and you can now see where the code wants to split.

Use it when

Before restructuring code full of names like data, tmp, handle or flag2, especially code you didn't write. Anthropic's docs suggest /effort low for a rename across a few files, because you're reviewing each result anyway. The Claude app works too if you paste a single function and ask for the table of names.

Skip it when

Code that's already clearly named, where you can go straight to the structural change. Avoid sweeping renames on a shared branch mid-feature, too, since they create conflicts for your teammates. For hundreds of sites of a public symbol, your IDE's rename or a codemod is more dependable. That's a rule of thumb, not a vendor figure.

Why it works

A names-only commit is easy to review because nothing else changed, and it's often where you first see what a function really does. That part is a rule of thumb, not a vendor claim. The trap comes from how the tool works. Anthropic's tools reference says Edit does exact string replacement, with no regex or fuzzy matching. The text must appear exactly once, unless Claude sets replace_all: true, which replaces every occurrence. So renaming id that way could also hit valid. A language server helps Claude find real references, but the docs describe that tool as read-only, so it locates the sites rather than renaming them. Your type checker and tests then confirm the result.

Example

A function uses d, res and doStuff. The table proposes invoice, lineItems and applyDiscounts, and flags res as also being a key in the JSON response, so it stays for now. Reading the renamed version, you might see that applyDiscounts also sends an email. That's your next refactor, and you could only see it once the name said what the function was meant to do.

Going further

Ask what the type checker can't see. Names also live in JSON keys, templates, SQL strings, reflection and log dashboards, and no language server follows those. Add Then search for the old names in strings, config and templates, and list what you find to the prompt. That list is a rule of thumb, not from a vendor. Once it's committed, /code-review abc1234^..abc1234 reviews that single commit. Also keep formatting hooks in mind: if a PostToolUse hook runs Prettier on every edited file and those files weren't formatted before, formatting noise lands in your rename diff. Format in a separate commit first.

Common mistakes

  • Renaming an exported or stored name in a pass meant to be safe. That's a change to a contract, and it needs its own plan.
  • Letting replace_all run on a short name such as id or data. It's plain string replacement, so it can hit other identifiers and comments.
  • Bundling renames with moved code. The diff gets too big for anyone to check that behavior held.
  • Trusting /rewind to undo a mass rename done with sed. Files only a Bash command changed aren't restored, so commit first.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Workflow How Do You Refactor With Claude Safely? Technique How Do You Break Up a Huge Function With Claude? Technique How Do You Change a Function Used Everywhere? Concept How Much Can You Fit in a Claude Chat?

Beyond the course

Glossary Vibe coding Pricing guide Claude pricing, plans and models