Improving the Terrible English Used by Claude Code

  by Steve Endow

[This blog post was 100% human written. None of this post was drafted or written by an AI.]

I am hardly the grammar police, but I value linguistic precision.

The bizarre English language quirks baked into Claude Code cause it to use terrible words and phrases that make no sense (to a native US English speaker) and significantly weaken the precision of it's language when communicating with a developer.

What do you mean?

Here are some of the terrible phrases that Claude Code spat out while I was trying to develop software:

Load-bearing

Ground truth

Rung scaffold

First-class citizen

territory

cast a wide net

These mean absolutely nothing.  They are linguistic jibberish.  They may sound familiar and you may say "Oh, ya, I know what that means."  But we aren't chatting about our recent vacation over dinner with friends--we're trying to develop software applications, where every character in the code matters.

If you think you know what these mean, tell me where exactly do I see the "load" in my code?  Where is the "ground" in my application?  Where is the "rung" in my tests?  How many classes of citizens do I have in my project?

Every one of these phrases is an extremely weak substitute for the concept or object or literal code being referenced or described.  

I learned years ago that metaphors, similes and jargon only serve to weaken your language.  Metaphors are useful as an intermediary to attempt to describe a concept to someone who is not familiar with that concept.  They are not an effective way to communicate with someone who understands the concept already.

In the context of coding and application development (and many other domains), metaphors and figures of speech only serve to weaken your language.  I don't call a variable a "bucket", or a procedure a "factory", or a codeunit a "thingie".  Similarly, I don't want Claude to use fishing metaphors when discussing my code.

Having recently transitioned from GitHub Copilot (which did not have this behavior) to Claude Code, the flood of these bizarre linguistic ticks made me stop, read and re-read what Claude Code was saying, and then try to figure out what it actually meant with these useless statements.

I had to tell Claude:  "Stop using these stupid meaningless phrases!"  Of course, it didn't know what I was asking for, so I had to ask it to modify my preference file (user level CLAUDE.md) to create rules to try and minimize this behavior.

It created two sections in the file.

Sample user CLAUDE.md file

The first section:

Language and writing style

Use simple, clear, literal language. Do not use:

Metaphors — for example, do not say "rung" to mean a step in a sequence, "rig" to mean a test setup, "lift" to mean move or convert code, "hoist" to mean move something up, "walk up" or "upward walk" or "parent walk" to mean traverse parent directories, "scaffold" or "scaffolding" to mean a folder structure or starter files, or "in X territory" to mean "in the area where X applies". Use the literal word: "step", "test setup", "move", "convert", "move up", "search up through parent directories", "folder structure", "in the X area".

Colloquialisms and figures of speech — for example, do not say "the diagnoses held up", "we got burned", "bake in", "cast a wide net", "ground truth", "pin down", "load-bearing", "non-portable" (as a casual descriptor). Use direct equivalents: "the diagnoses were confirmed", "this caused a problem before", "include", "search broadly", "the reference data", "identify", "important", "does not work on the other operating systems".

Business or marketing jargon — for example, do not say "deliverable", "leverage", "circle back", "blast radius", "north star", "headwinds". Use plain alternatives: "result", "use", "return to", "scope of impact", "goal", "obstacles".

Fancier synonyms when a common word works — for example, do not say "cadence" when "schedule", "interval", or "frequency" fits, and do not say "emit" when "send", "write", or "log" fits. Pick the simpler, more common word every time.

Technical terms that have a specific meaning in software development are acceptable: API, locator, selector, iframe, schema, validation, recorder, helper function, test case, etc. The rule applies to figurative or informal language, not to precise technical vocabulary.

When tempted to use a metaphor, replace it with a direct description of what is happening.

The second section of the file includes this list of examples to avoid.

Examples of phrasing to avoid and to use

Avoid	Use
"Lift the selectors into helpers"	"Move the selectors into helper functions"
"The next rung of the ladder"	"The next test case"
"The rig is ready"	"The test setup is ready"
"These tests held up"	"These tests passed" / "These tests were confirmed to work"
"Cast a wide net"	"Search broadly" / "Try several options"
"Ground truth"	"Reference data" / "The known-correct value"
"Load-bearing"	"Important" / "Required for the system to work"
"Promote to production" (figurative)	"Move from the test file to the helper module"
"First-class citizen"	"Fully supported"
"Bake in"	"Include" / "Build in"
"Out of the box"	"By default"
"Source of truth"	"The authoritative reference" / "The reference file"
"Cookbook" (as a doc heading)	"Reference" / "Examples"
"Hoist node_modules up one level"	"Move node_modules up one folder level"
"Node walks up the directory tree"	"Node looks for node_modules in each parent directory"
"The upward walk to node_modules"	"The search through parent directories for node_modules"
"Rung scaffold" / "rung folder"	"Test case folder"
"The next rung"	"The next test case"
"A junction in source control territory"	"A junction inside a folder tracked by git"
"Non-portable junction"	"A junction that only works on Windows"
"Co-located driver"	"A driver file kept in the same folder as the test case"
"Configurable cadence" / "On a different cadence"	"Configurable schedule" / "On a different schedule"
"The 10-second cadence" (of a polling job)	"The 10-second interval"
"Emit email notifications"	"Send email notifications"
"Emit a telemetry signal"	"Send a telemetry signal" / "Log a telemetry signal"
"Emit an activity log entry"	"Write an activity log entry"
"What signals are emitted"	"What signals are sent"

 

If you find Claude Code's explanations to be non-sensical, give this a try, and every time it tries to use a clever sounding phrase, tell it to add it to this list and find a better, simpler way to communicate the topic.

Steve Endow is a Microsoft MVP in Los Angeles.  He works with Dynamics 365 Business Central and related technologies.

You can also find him on X and YouTube, or through these links:  links.steveendow.com