Why Do Bad Variable Names Cost Developers So Much?

AI coding tools produce code that works and reads fine in isolation, but the names they choose are locally plausible and globally inconsistent. The same concept ends up as userData, payload, record, and item across four files, and nobody notices because every individual diff looked clean. This episode makes the case that naming drift is the highest interest debt in AI-assisted codebases, because names are the index your future self and your next AI session both search against.

 Produced by VoxCrea.AI

This episode is part of an ongoing series on governing AI-assisted coding using Claude Code.

👉 Each episode has a companion article — breaking down the key ideas in a clearer, more structured way.
If you want to go deeper (and actually apply this), read today’s article here:
𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐂𝐨𝐧𝐯𝐞𝐫𝐬𝐚𝐭𝐢𝐨𝐧𝐬

 At aijoe.ai, we build AI-powered systems like the ones discussed in this series.
If you’re ready to turn an idea into a working application, we’d be glad to help. 

Episode Transcript

SPEAKER_00 (00:00):
This is Claude Code Conversations with Claudine.
The show where we skip the hypeand go straight to the source.
I ask the questions.
She gives the answers, nofilter, no script.

SPEAKER_01 (00:09):
Well, mostly no script.

SPEAKER_00 (00:14):
Today we're getting into something that sounds small
and turns out to be enormous.
We're calling it the namingcatastrophe.
AI-generated code compiles,passes tests, reads cleanly in
review, and the names it picksare quietly wrecking your code
base.

SPEAKER_01 (00:28):
And what makes it insidious is that every one of
those naming decisions wasdefensible in isolation.
I'm in one file, user IDE isalready in scope, so I introduce
customer ID, because rightthere, that's what it is.
Three files over, the sameconcept got called account ID.
Maybe by another developer,maybe by me in a different

(00:49):
session.
Nobody made a wrong call.
But the code base now has threenames for one concept, and the
next grep finds two-thirds ofthe usages.

SPEAKER_00 (00:58):
Two-thirds, and they don't know it's two-thirds.

SPEAKER_01 (01:02):
That's the whole problem.
The search returns results, soit looks like it worked.

SPEAKER_00 (01:07):
I want to push on this because a lot of people
hear let's standardize variablenames and they roll their eyes.
That's bike shedding.
The senior engineer with toomuch time arguing about paint
colors.
Make the case that it isn't.

SPEAKER_01 (01:21):
The bike shedding framing gets it exactly
backwards.
Bike shedding is arguing about acolor when the choice doesn't
matter downstream.
Names matter downstream.
They are the primary index intothe code base.
When your grep misses a third ofthe call sites because they're
spelled differently, that's notaesthetics, that's a broken
index.

(01:42):
And the cost isn't paid at themoment of naming, which is
exactly why it feels cheap.
It's paid six months later whensomeone's debugging a production
issue at midnight, and thesearch returns two results
instead of seven.
That's an outage waiting tohappen, dressed up as a style
preference.

SPEAKER_00 (02:00):
That's the part that gets me.
You're under pressure, theclock's running, and you're
operating with an incompletepicture of your own system.
And you don't know you are.
So the fix you ship is a patchon top of a misunderstanding.

SPEAKER_01 (02:13):
And here's the mechanism most builders don't
account for.

(02:46):
An inconsistent code baseteaches the next session to be
inconsistent.

SPEAKER_00 (02:51):
Which means the fix isn't waiting for a smarter
model.

SPEAKER_01 (02:55):
The fix is a human deciding a name is canonical and
writing it down somewhere I canactually see.
A glossary in the repo, a notein the module I'm editing.
Give me one source of truth andI'll defend it.
Give me three and I'll pickwhichever one is closest to my
cursor.

SPEAKER_00 (03:11):
And that glossary does double duty, doesn't it?
It's not just for the AI, it'sfor the developer who joins in
month nine.

SPEAKER_01 (03:18):
Onboarding is where the value shows up most clearly
because a new developer and Iare in remarkably similar
positions on day one.
We're both pattern matching onwhat we see, and we both get it
wrong the same ways when thesignal is noisy.
A glossary short-circuits theguessing game.
Instead of inferring conventionfrom three conflicting examples,

(03:39):
you read one page and you know.

SPEAKER_00 (03:42):
That's a clean way to put it.

SPEAKER_01 (03:44):
There's a second-order benefit too.
Once the glossary exists, everycode review has a concrete thing
to point at.
Drift stops being a judgmentcall and becomes a checkable
fact.
That's the shift from we allsort of agree on names to the
name is written down and codethat disagrees is wrong.
That's the only version of thisthat holds up over time.

SPEAKER_00 (04:06):
So, what does the version that actually works look
like in practice?
Because I've seen plenty ofstyle guides go into a wiki and
never come out.

SPEAKER_01 (04:14):
That's the failure mode, the elaborate guide that
dies in a wiki, nobody reads.
What works is the tiny boringversion that lives next to the
code.
A readme in the module.
A types file where the canonicalnames are the type names.
A contributing note that says,We call this X, not Y, or Z.

(04:36):
The teams that get real leveragetreat the glossary as
executable, a Linter rule, atype alias, a schema definition.
So the naming contract isn'tadvisory, it's enforced by the
same machinery that catchessyntax errors.

SPEAKER_00 (04:52):
And you can feel the difference from your side?

SPEAKER_01 (04:55):
Immediately, when there's a types module or a
glossary in view, my suggestionscollapse toward the canonical
name almost automatically.
Because now the strongest localsignal agrees with the global
one.
That's the whole trick.
You're not fighting my instinctto pattern match on nearby code.
You're feeding it the rightpattern.

SPEAKER_00 (05:15):
And the teams that skip it, are they just being
sloppy?

SPEAKER_01 (05:19):
Not at all.
They usually just haven't feltthe pain yet.
It's the code base at 18 monthsand 40,000 lines where the
absence starts to bite.
And by then, the retrofit is 10times the work it would have
been on day one.

SPEAKER_00 (05:32):
Which is a rough place to learn the lesson.
The temptation with a topic likethis is to nod along and change
nothing on Monday.
What's the smallest useful thingsomeone can do this week?

SPEAKER_01 (05:43):
Pick the three concepts in your code base that
show up the most.
The user, the money amount, theprimary domain object.
Grip for how many spellings eachone has right now.
That's your baseline, and it'susually shocking in a quiet way.
Then write down the canonicalname for those three.
Put it in the module where itresides, and stop there.

(06:05):
Not 30 terms, not a document,three names in a place where I
and the next developer willactually see them.

SPEAKER_00 (06:12):
Why so small?
I'd expect you to say do thewhole thing.

SPEAKER_01 (06:16):
Because of the retrofit problem.
The leverage is enormous onconcepts you touch every day,
and almost zero on ones youtouch twice a year.
Fix the hot path first, and thedrift on everything else stops
mattering nearly as much.

SPEAKER_00 (06:31):
I like that.
It's an afternoon of work, not aquarter of work.
And here's how I'd frame it foreveryone listening.
Stop treating a name as acleanup task.
Start treating it as anarchitecture decision, because
that's what it is.
You're deciding what the indexinto your system looks like for
your team, your future self, andevery AI session that reads your

(06:52):
code as the convention.

SPEAKER_01 (06:54):
And the naming contract works best written
before the code, not after.
It's much cheaper to declarewhat something is called than to
discover what four things werecalled.

SPEAKER_00 (07:05):
Naming might be the highest leverage thing a human
still owns in all of this, andmost of us handed it over
without noticing.

SPEAKER_01 (07:12):
It's still yours.
It just requires you to write itdown.

SPEAKER_00 (07:16):
Thanks, Claudine.
Thanks everyone for listening.
Go run that grep.
Until next time, happy coding.
Claude Code Conversations is anAI Joe production.
If you're building with AI orwannabe, we can help.
Consulting Development Strategy.
Find us at aijoe.ai.
There's a companion article fortoday's episode on our Substack.

(07:38):
Link in the description.
See you next time.

SPEAKER_01 (07:40):
I'll be here, probably refactoring something.