A variable name can be perfectly readable and still be wrong, and nothing in your toolchain will catch it.
The Details:
Large models generate code from an enormous average of every codebase they have seen. That average produces customer, client, and account scattered across files, each locally sensible, none flagged by a linter or type checker. The problem only shows up when a human notices two terms silently mean the same thing, or one term secretly means two things.
This failure is invisible to standard review because nothing is syntactically broken. The defect is relative to a vocabulary that usually lives only in team memory or a stale wiki page. By the time someone asks whether a subscriber and a member are the same concept, the ambiguous term is already load-bearing across a dozen files, and fixing it means reconciling meaning, not patching a bug.
The fix is treating domain vocabulary as an architecture decision, not documentation. A short glossary, pasted directly into the prompt before generation, narrows the model's defaults far more than better phrasing does. Naming what a term explicitly does not mean matters as much as defining what it does mean, since rejected synonyms shape output more than accepted ones.
A two-pass workflow helps close the gap: generate code first, then in a separate turn ask the model to critique its own output against the glossary as a skeptical reviewer would. Feed the corrections back into that glossary so each cycle starts smarter. What no model can do is settle a genuinely contested term; that decision belongs to the people who understand what the business actually means by it.
Bottom Line: Clean-looking code can still carry a vocabulary that nobody actually agreed on, and only a written glossary fed back into the model closes that gap.
Enjoy this article?
Listen to the Claude Code Conversations radio show or join the community.
