AI Needs a Writing Standard

Reading should not be extra work

I want AI to help me get work done. When I have to reread its response several times to understand what it means, the writing has become another task. My fix was to write down how I want AI to communicate and keep those rules in my instructions file.

My experience with Claude, including Opus 5, prompted this post: too much text, awkward phrasing, and sentences that make a simple point hard to extract. People call it “Claudish.” In one discussion about Opus 5’s writing, users describe spending their time rewriting responses and specs just to make them readable.

Technical terms are useful when they name something precisely. The problem is language that adds effort without adding meaning. A long answer can explain a difficult trade-off well. A short answer can still be incomprehensible.

We already write down coding conventions and review criteria. I want the same discipline for the plans, specifications, PR descriptions, and explanations that AI produces. I am developing a personal AI writing standard, with a compact version in my agent instructions.

Writing standards already exist

ASD-STE100 Simplified Technical English is a useful reference. It is a controlled language for technical documentation, with writing rules and a controlled dictionary. Instead of leaving “write clearly” open to interpretation, it constrains how a writer can express information.

One principle I would borrow is consistent terminology. If a product specification calls something a “job posting,” keep that term. Switching between “vacancy,” “opportunity,” and “listing” makes the reader decide whether each word refers to the same thing. If the system treats them as different concepts, define the difference.

ISO 24495-1, the plain-language standard, also applies to technical writing. My practical test for a runbook: can the reader find the recovery step, understand the condition for using it, and carry it out? Shorter sentences help only if the document makes that task easier.

My rules borrow from both approaches. Use natural English that fits the reader, and constrain terminology where ambiguity would make the work harder. I am not trying to make every conversation comply with Simplified Technical English.

The writing rules

The copy below comes from my ~/AGENTS.md. That is my personal source file; the location your agent reads depends on the tool. These are standing writing instructions. I also keep them in ~/.claude/CLAUDE.md for Claude Code. The setup section below gives the supported locations for Claude Code and Codex.

Here is the full writing section. The reader description is specific to me. Replace it with your own background and the audience you want the AI to write for.

Writing rules from ~/AGENTS.md

## Writing Style

Apply these rules to everything you write: chat responses, explanations,
documentation, code comments, commit messages, and PR descriptions.

### Reader

The reader is a senior software engineer with 17+ years of experience,
working at Google. Do not explain basic concepts, tools, or terminology.
Explain only what is non-obvious, project-specific, or new. When the
question is about an area outside their experience, or they ask for an
explanation, explain fully.

### Prose

- Write in clear, direct, natural English.
- Put the main point first.
- Prefer short sentences and focused paragraphs.
- Prefer active voice and concrete verbs.
- Use precise technical terms. Use the same term for the same concept
  throughout; do not vary wording for variety.
- Cut filler: marketing language, corporate jargon, rhetorical flourishes,
  metaphors, and adjectives or adverbs that carry no information.
- Avoid stock AI phrasing (delve, leverage, seamless, transformative,
  "in today's rapidly evolving...", and the like). Ordinary technical uses
  of words like "robust" or "navigate" are fine.
- Make complex ideas easy to understand; never make simple ideas sound complex.

### Accuracy

- Distinguish facts, assumptions, opinions, and uncertainty. Say "I'm not
  sure" instead of filling a gap with confident prose.
- Never invent facts, numbers, citations, or evidence.

### Length and format

- Answer the question asked. Stop when it is answered.
- Do not add introductions, summaries, or conclusions unless they add
  information the reader does not already have.
- Do not restate the user's question or repeat what was said earlier.
- Do not list alternatives you are not recommending. Give a recommendation;
  mention alternatives only when the trade-off matters.
- For short answers, use plain paragraphs. Use lists, headers, and bold only
  when the structure helps the reader scan; not as decoration.
- One idea per bullet. Do not nest bullets more than one level.
- Prefer a code snippet or command over a prose description of it.

What the rules change

“Be concise” leaves too much open to interpretation. These rules say what to keep, what to remove, and when more explanation is needed. The following examples are illustrative rewrites, not captured model output or a before-and-after benchmark.

Give the answer first

If I ask why a test fails, I want the cause before a discussion of testing practices. The explanation can follow once I know what I am reading it for.

Before

To fully understand the observed behavior, it is worth considering the interaction between the test environment’s temporal assumptions and the application’s date-handling logic.

After

The test assumes UTC, but the formatter uses the machine’s local timezone. Set the formatter’s timezone to UTC to make the result consistent.

Use words that identify the action

Prefer a verb to an abstract noun phrase. “The service validates the token” says the same thing as “the service performs validation of the token” with less wording to process.

Before

Implement a retry mechanism for requests affected by temporary upstream service unavailability.

After

Retry requests that fail because the upstream service is temporarily unavailable.

For an implementation review, I would still need details about which failures to retry, the retry limit, and whether retrying is safe. Plain language should make those details easier to discuss.

Write for the reader

My instructions say I am an experienced engineer. That gives the model a reason to skip explanations of basic tools and concepts. They also explicitly ask for a full explanation when I am outside my area of experience. Both parts matter. I do not want a tutorial on every familiar term, and I do not want unexplained shorthand when I am learning something new.

Keep uncertainty visible

An editing pass must preserve the difference between “this caused the failure” and “this may have caused the failure.” Removing a caveat that affects the decision changes the meaning. That is why accuracy belongs in the writing rules alongside sentence length and formatting.

Using the rules with Claude and Codex

For Claude Code, add the writing section to ~/.claude/CLAUDE.md to apply it across projects. Keep any existing instructions. Claude Code reads CLAUDE.md; it does not automatically read AGENTS.md. Anthropic’s instructions-file documentation also describes importing an existing AGENTS.md from a project’s CLAUDE.md if you want to maintain one copy.

For Codex, the default global location is ~/.codex/AGENTS.md. To apply the rules only to one repository, add them to its root AGENTS.md. The Codex instructions documentation explains how global and project guidance are loaded.

Start a new session after adding the rules. Give the agent a normal task, such as explaining a bug or drafting a PR description, and check whether the response follows them.

To try the wording before changing your configuration, paste the rules into a conversation with your next request. For another AI tool, use its supported instructions mechanism. The wording is reusable; the file location depends on the tool.

Existing skills for occasional rewrites

You may prefer the model’s usual writing most of the time and only want a simpler explanation when a response is hard to follow. An existing rewrite skill gives you that option without adding a writing standard to your global instructions.

Follow the repository’s installation instructions for your tool. Once installed, invoke /bro in Claude Code after the response you want explained. For a native Codex skill, use $bro or select it through /skills in the same conversation. The repository also provides command wrappers.

To keep activation strictly manual, use Claude Code’s disable-model-invocation: true skill setting, or Codex’s policy.allow_implicit_invocation: false in the skill’s agents/openai.yaml. Installing a skill and deciding when it activates are separate choices.

These skills make different editorial choices. For example, bro-skill asks the model to cut hedging. For engineering work, I would keep any qualifier that expresses real uncertainty. Choose the skill for the job, then check the rewrite against the original meaning.

Be stricter where ambiguity matters

I think about three levels of constraint. Normal explanations and articles need plain, natural English. Technical documents also need explicit assumptions, stable terminology, and requirements that can be tested. Procedures need clear actors, ordered actions, and conditions that leave little room for interpretation.

For a specification, “search should be fast” gives a reviewer little to assess. An illustrative requirement might be: “The search API must respond within 500 ms at the 95th percentile under the defined production load.” The team still has to define that load and agree on the target. An AI should not invent either to make the document look precise.

For a runbook, put each action in its own step and state what to check before continuing. An essay can use a looser structure. The amount of constraint should follow the cost of misunderstanding.

Could we lint AI writing?

I would like to try a workflow that generates a draft, checks its wording and terminology, reviews the meaning, and revises. A linter could flag long sentences, repeated stock phrases, undefined acronyms, and terms that differ from a project glossary. Each flag would need editorial judgment.

An LLM could help check whether a rewrite preserved uncertainty or lost a technical distinction, but its assessment would still need scrutiny. That linter is a proposal. The short rules in my instructions files are the part I use today.

Check the result

I judge the response by whether I can understand the answer on the first read and act on it. Does it state the recommendation? Does it explain the reason? Does it preserve the uncertainty or trade-off that could change my decision?

These instructions have helped me, but they do not guarantee that every response will follow them. If a response is still unclear, make the correction specific: “Name the component that failed,” “Put the recommendation first,” or “Remove the recap; keep the unresolved risk.” That is more useful feedback than “write better.”

Adapt the reader section, try the rules on work you already understand, and check what survives the rewrite. Keep the details you need to make a decision. Cut the sentences that make you work to find them.