Claude CodeBeginner

How to Rename a Symbol Across the Codebase with Claude Code

Rename a function, type, or variable everywhere it is used without missing call sites or breaking imports.

6 minBeginner

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.

Claude Code

You

Rename the exported function getUsr in src/lib/api.ts to fetchUser everywhere, including imports and re-exports. Do not change unrelated names like getUsrPrefs.

Agent

Found 11 references across 6 files plus one re-export in index.ts. I'll rename only the getUsr symbol and its imports, leaving getUsrPrefs untouched.

Precise names prevent collateral edits.

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.

src/lib/index.ts

-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.

zsh - my-app

$npx tsc --noEmit

(no output)

no dangling references to the old name

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.

zsh - my-app

$git grep -n 'getUsr\b'

(no matches)

Diff plus compile beats raw replace

The combination of a reviewed diff and a clean type check catches what a plain text replace would miss, like re-exports and dynamic imports.

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

Watch related tutorials