abelcastro.dev

Last week I asked Claude to summarize a deploy log. It told me a job had "stalled". I spent a few minutes checking the system for actual problems before realizing the word was figurative. The job had paused, not broken. Stalled is what cars do.

This is the pattern. Every few prompts, Claude reaches for a phrase that sounds natural to a fluent reader and lands wrong on me. Drain, in-flight, beat us to it, head down, spin up. Each one is a small interruption. I read it twice, I check if it means what I think, sometimes I look it up. Multiply by 50 prompts a day.

For a long time I treated this as my problem. The author of the message is a tool I am paying for, and yet I was the one stumbling. It felt like a gap in my English, something I should fix by reading more.

It is not that. Claude's default writing is polished English: fluent, idiomatic, the way "good writing" is supposed to sound. For a non-native reader, that polish is the problem.

Once you frame it that way, the fix is a configuration issue, not a vocabulary problem.

What does not work

Correcting Claude inside the conversation. It works for two or three turns and then the next idiom shows up. The corrections do not carry across sessions, and they do not carry between projects.

Maintaining a list of forbidden words. I tried this. The list grew. Drain. In-flight. Stalled. Beat us to it. Spin up. Tear down. English has thousands of these phrases. I cannot enumerate them, and I should not have to.

Both approaches fail for the same reason. They treat each idiom as a separate item to memorize, when the underlying issue is a writing principle the model is not applying.

What works: a principle, not a list

The principle is one question, applied to every sentence the model writes:

Would this phrase still mean what I intended if translated word for word into another language?

If yes, great. If no, it is an idiom. You can usually replace it with clearer words.

A few examples:

• "The job stalled" becomes "The job stopped before completing"
• "The data is in flight" becomes "The data is still being sent"
• "We drained the queue" becomes "We processed all items in the queue"
• "Spin up a container" becomes "Start a container"
• "Beat us to it" becomes "Finished first"

The right column reads slightly less fluent and is much easier to understand. For a non-native reader this is not a downgrade, it is the entire point.

Once you have the principle, you do not need the list. The principle generates the list on demand.

Where to put it in Claude

Claude has a settings field called "Instructions for Claude", under Settings, General, Profile. Text in that box applies to every chat across the account. It is the right place for a writing rule that should always apply.

Paste this:

Write all prose, code comments, log messages, and chat responses 
with literal vocabulary. The reader is a non-native English speaker. 
Test before sending: would each phrase still mean what I intended 
if translated word for word into another language? If not, rewrite it.

Avoid:
- Phrasal verbs whose meaning differs from the literal words 
  (spin up, take off, wind down, tear down, look up).
- Sports, war, cooking, or sailing metaphors (in the trenches, 
  simmer, on the hunt, beat us to it).
- Body-part metaphors (head down to, keep an eye on, lend a hand).
- Verbs that physically describe something else (stalled, drained, 
  burned down). Use neutral verbs that describe what is actually 
  happening (did not finish, stopped before completing).
- Niche jargon when a plain phrase is the same length (terminal 
  status, in flight). Prefer the plain phrase.

Keep technical terms with literal meanings (SIGTERM, graceful 
shutdown, cache miss). The rule is about figurative language, 
not standard terminology.

Keep sentences short and direct. Prefer the phrasing a 10-year-old 
or a non-native English speaker would understand. Boring prose is 
correct prose.

Save. From the next chat onward, Claude applies the rule by default.

Where to put it in Claude Code

The settings field above applies to claude.ai on the web, the desktop app, and the mobile app. These are different clients to the same backend, so one setting covers all three.

Claude Code (the CLI, and the VS Code extension that uses it) is a separate product with its own configuration. The web setting does not apply there. To get the same rule, paste the same text into a user-level file:

~/.claude/CLAUDE.md

Claude Code reads that file at the start of every session, in every project. Project-level CLAUDE.md files at the repo root also work, but for a writing rule that should always apply, the user-level file is the right place.

You now have two copies of the same text, one in the web settings and one in ~/.claude/CLAUDE.md. If you change one, update the other. There is no automatic sync between them.

Why this matters beyond Claude

The same principle works for anything I write that other developers might read. Documentation, commit messages, code review comments, Slack threads. An idiom in a PR description costs everyone two seconds and costs a non-native reader a search.

The literal-translation test is a habit I can apply with or without an LLM. The Claude instruction just makes the habit show up in every chat I have, without me having to remember.