How to rename a variable across your whole project — without breaking things that just look similar

AI named a variable data. Then data2. Then userData, even though it holds orders. You decide to clean up: hit Find and Replace, type user → customer, "Replace All."

A minute later you've got customername instead of username, a button on your site now says "Log in as customer," and a request to the server sends a field the server has never heard of. The replace did exactly what you asked: it replaced letters. All of them.

The good news: your editor has a tool that changes not letters but meaning. Here's how to rename anything across a whole project without hitting anything else.

Why Find and Replace is a bad idea

Text search doesn't understand code. To it, user, username, users, and the word "user" in a button label are the same string of letters.

Code tells them apart. A variable user in one function and user in the next one are two completely different things (thanks to scope). Renaming one doesn't mean touching the other.

You need a tool that sees code the way the programming language does. In VS Code and Cursor it's called Rename Symbol.

Six steps

1. Save a way back. Before any bulk edit, make a commit. If something goes wrong, you roll back with one command instead of fixing forty files by hand.

2. Put your cursor on the name and press F2. Right on the declaration: const userData = ... — cursor on userData. A small input box pops up. On a Mac it's also F2 — sometimes with the Fn key.

3. Type the new name and check the preview. Instead of Enter, press Shift+Enter — the editor shows every place that will change, grouped by file. Skim it: only genuine references to this exact variable should be there. Similar names won't make the list — that's the whole point.

4. Confirm. The editor changes the name everywhere it's referenced: in this file, in other files, in imports. For JavaScript and TypeScript, this works across files out of the box.

5. Find what F2 can't see. Rename Symbol understands code, not text. Here's what it will miss:

   • strings in quotes — "userData" as a key or a message;
   • fields that come from the server or live in the database;
   • CSS class names and settings in JSON files;
   • mentions in comments and docs.

   For those, open project-wide search — Ctrl+Shift+F (Cmd+Shift+F on a Mac) — and turn on two toggles to the right of the input: Aa (match case) and the boxed ab (match whole word). Now user won't match username.

6. Run it and check. Open the app and walk through the screens where the variable lived. Look at the diff: every changed line should make sense. If you have tests, run them.

How to ask an agent to do it

If you work in an agent like Claude Code or Cursor, you can hand off the rename. But phrase the task so it doesn't take the same "replace letters" route:

The key part of the strong version is the last line. A list of places before the edit is the same preview as Shift+Enter in the editor. You see the scope before it happens.

What you get

Names in your code start telling the truth: orders means orders, customer means a customer. Next time you look for code in your project, searching for a clear name takes you to the right place on the first try. And an agent reading your code gets confused less, too: good names are context it gets for free.

How can I tell a name is bad?

A simple test: read the name out loud without the code around it. data, temp, result2, handleClick3 say nothing — those are rename candidates. A good name answers "what's in here": unpaidOrders, isLoading, saveProfile.

What if I need to rename a file?

Drag it or rename it right in the editor's file tree. VS Code will offer to update every import that points to it — say yes, then check the diff.

Why does F2 do nothing?

Usually the editor hasn't recognized the file's language or hasn't finished indexing the project. Wait a few seconds after opening it, or check that the language shown in the bottom-right corner is correct.