Writing rules for AI agents and humans

AR Labs loads one short set of writing rules into every AI agent session. An AI agent is a language model run in a loop with tools, so it can act, not only reply, and ours write a great deal that people read later: specs, pull request bodies, task descriptions, design records, reports. The rules aim at one outcome: a reader who was not in the session can follow the text without asking. They suit anyone whose agents produce text that reads fluently and still cannot be acted on.

The problem it prevents

The most damaging habit in agent-written prose is assuming context the reader does not have. An agent refers to "the aggregation seam" or a task ID as though the reader had watched its tool output, asserts that something "matters" without saying what breaks, and opens at full mechanism depth. Shaikh and colleagues, in Grounding Gaps in Language Model Generations (NAACL 2024), found that language models produce fewer of the grounding acts people use to establish shared understanding, such as clarifying questions, and that training on current human-preference data reduces them further. The result reads fluently and cannot be acted on. Weeks later, a person reviewing a pull request cold has to reconstruct what the agent knew.

The rules

The core of the rule file, lightly condensed:

• Ground every reference. Introduce each name, term and decision before using it, including terms coined in the same session. No "the X" before an X exists.
• Name a task by what it is, not by its ID alone. "app-42.3 (sessions lost on restart)", not "app-42.3". The same goes for pull requests, commits and branches cited by number.
• Define terms at first use for the stated audience. The default reader for internal documents is an engineer who has not loaded the codebase or the session.
• Open decision-carrying sections in plain English: what this is and why it matters, before the mechanism. Add the on-ramp; never cut the precision.
• State stakes rather than asserting them. Say what breaks.
• Say which depends on which, and in which direction.
• In replies, lead with the outcome, then the detail, in complete sentences without the working shorthand the session coined.
• One topic per sentence, active voice with a named actor, varied sentence length.
• Prefer the plain word, and prose to bullets unless the items are discrete.
• Never perform sincerity: cut "to be honest", "frankly", "genuinely".
• When presenting options, one sentence each with only the action, the actor and the cost, then at most one sentence of recommendation. Clauses about how easy or quick an option will be are predictions, and they are the sign that the writing has started selling.
• Respect a document's existing form: tables stay tables, checklists stay checklists.
• Documents state current truth; version control holds the history. No inline edit dates and no notes on what an earlier draft said.

The rules close with a reminder that they describe recurring failures, not a checklist to satisfy, and that judgement comes before compliance.

A worked example

Before:

Fixed the aggregation seam issue in app-17.4. The gate now passes. This is important for the harness.

After:

Sessions were being saved twice when a visitor reconnected, because two handlers both wrote the session on reconnect. Now only the connection handler writes it. Task app-42.3 (sessions lost on restart) depended on this, and can now proceed.

The second version introduces the problem, names the cause and says which piece of work depended on the fix.

Rules in context are not rules obeyed

A written rule competes with a trained habit, and under pressure to produce text the habit tends to win. Having the rules in context is not a guarantee, so we add an active check. A writing-quality skill (packaged instructions, with any scripts, that an agent loads only when a task needs them; see Write Well) audits prose in five layers: word choice, structural clichés, throat-clearing openers, formatting tells, and grounding and readability, which matters most. Structural clichés and formatting tells (such as heavy em dash use, scattered bold and punchy one-line section endings) are checked only for public-facing writing.

We once kept a list of banned words and retired it. The list flagged words that were right in context and pushed prose toward stilted substitutes, which cost more than the tells it caught. Word choice is now judged per sentence: a word is flagged when it does no work there, never because it appears on a list.

Author and reviewer aim at the same target

When an agent drafts a design document, it loads the same readability rubric the reviewing agent will score the draft against, before it writes. Because the rubric is a single file that both read, the author and the reviewer stay aligned even as the rubric changes, and the review round finds less to fix.