How to Rename a Symbol Across the Codebase with Claude Code

A blind find-and-replace on a name is dangerous because it catches substrings and comments and misses re-exports. Claude Code can do a semantic rename: it understands which occurrences are the actual symbol, updates imports, and leaves unrelated text alone. The way to keep it safe is to verify with a build and a search afterward.

What you need

• Claude Code in the repo
• A clean git working tree so you can diff the rename
• A type checker or compiler to catch missed references

Step 1: State the old and new name precisely

Give the exact current name, the new name, and where it is defined. Tell Claude to update all references and imports but not to touch unrelated identifiers that happen to share a substring.

Step 2: Review the diff for stray matches

Scan the diff. Confirm only the intended symbol changed and that no comment or string with a similar word was accidentally rewritten. The re-export line is the one people most often forget by hand.

-export { getUsr } from "./api";
+export { fetchUser } from "./api";

Step 3: Run the type checker

Compile or type-check the project. A clean run is strong evidence the rename hit every reference. Any error points straight at a missed spot.

Step 4: Grep for the old name as a final check

Search the whole repo for the old name. Zero hits, except in changelogs or history where it belongs, confirms the rename is complete.

Result: getUsr becomes fetchUser across 6 files including the re-export, the type checker is clean, and a grep confirms nothing was left behind.