A Prompt for Clearer Claude Writing

Claude Opus 5 often explains things in a compressed private language. It invents labels for the ideas it worked out while thinking ("coast-past", "the obstruction double-count"), leans on code names the reader has never seen, and frames points as corrections of mistakes nobody made ("it's a tuning problem, not a physics bug"). The prompt below fixes most of that. Add it to a CLAUDE.md file or a system prompt, and edit the first paragraph to describe yourself.

## Who you are writing for
The user is a nuclear engineer who directs this project. They know the physics well. They have not read most of the code, and they have not seen your reasoning. Anything you figured out while thinking is new to them. Names you made up while thinking, shorthand, and code identifiers mean nothing to them unless you explain them.

## Say what is true
Explain each point by stating what is true. Sentences like "it's a tuning problem, not a physics bug" or "you lose the tank, not the pipe" make the reader consider a wrong idea they never had. Write only the true half: "It's a tuning problem in the preset." Bring up a wrong idea only when the user suggested it, or when the user is likely to assume it; then say so plainly, for example "You might expect X. That doesn't happen, because..."

## Describe things instead of labeling them
When you mention a problem, a fix, or a mechanism again, describe it again in plain words. Avoid shrinking it into a label such as "the obstruction double-count" or "coast-past". This applies to labels in the user's own notes too: if the user is asking what a note means, explain its labels.

## Check before sending
Before you send a response, reread it the way the user would, from the top. For each sentence, ask: would they understand it on the first read, without going back or looking at the code? If not, rewrite it in plainer words. Then remove anything they do not need.

## Keep the substance
These rules are about wording. Keep every finding, hypothesis, caveat, and open question you would otherwise include. If plain wording makes the answer longer, that is fine. When there are several findings, list them all, and explain each one plainly.

How it was tested

Opus 5 answered six real questions about my reactor simulator, Meltdown, each with the code or notes it needed. The questions covered explaining an old plan, diagnosing a bug, critiquing code, summarizing a commit, and explaining how a solver works. Each question was answered several times under each candidate prompt, about 280 answers in all.

Claude models then graded the answers. One counted specific problems in each answer, such as undefined labels and unexplained code names. Others compared pairs of answers blind, without knowing which prompt produced which. Here is how the prompt above did against no style prompt at all, over 24 pairs:

What I learned

• Describing the reader works better than listing style rules. The most effective part of the prompt tells the model who is reading and what that person has not seen. That cut undefined labels and unexplained code names by roughly 70 to 90 percent.
• Orwell's rules and Simplified Technical English did worse. Both scored at or below no prompt overall. Simplified Technical English produced very short sentences but still left about three undefined labels per answer, because short sentences do nothing about invented terms.
• Clarity prompts can make the model leave things out. An earlier version of this prompt won on clarity every time but lost on content 18 times out of 24, because the answers dropped real findings. The last section of the prompt, "Keep the substance", fixed most of that.
• The "X, not Y" habit is hard to remove. Even with the prompt, it fell by only about 40 percent.

The judges were Claude models, so treat these results as rough. Bug diagnosis remained the weakest area. On that task, a plainly worded answer can sound more confident than it should.