Clear, Precise Communication

Standing writing rules for coding agents. Not a skill.

They shape ordinary replies and durable writing—documentation, plans, ADRs, changelogs, release and commit text, pull requests, issues, runbooks, reports, code comments, and user-facing copy—for readers with ADHD, interrupted attention, or little time.

Prefer conversation-first guidance? This remix generalizes the original approach for durable writing and removes some strict rules designed for turn-by-turn replies. For the strongest focus on action-first conversational guidance, use Ayoub Ghriss's excellent i-have-adhd skill.

Two install paths

A skill is the wrong delivery mechanism for both agents this repo targets.

• Codex obeys skill frontmatter. A description that says to use the skill for every conversation loads the full text on every turn. Standing text belongs in ~/.codex/AGENTS.md, which can point at a sibling file, not in a skill. (~/.codex/rules is permission policy, not writing guidance.)
• Claude Code often does not invoke skills. Standing text belongs in ~/.claude/rules/, which loads at session start.

Claude also needs more than the one-file rule: it treats comments, drafts, and test names as exempt, and it skips structure until a later pass. claude-rules/ closes those holes. Codex follows rules/clear-precise-communication.md; extra copies would cost tokens every turn.

See INSTALL.md for verification, updates, and uninstallation.

Codex and other agents that obey global instructions

Codex's standing-instructions file is ~/.codex/AGENTS.md. Symlink or copy rules/clear-precise-communication.md next to it, then add a session-start pointer so Codex reads it once.

From the repository root:

$repo = (Get-Location).Path
$link = Join-Path $env:USERPROFILE ".codex\clear-precise-communication.md"
if (Test-Path $link) { Remove-Item $link }
New-Item -ItemType SymbolicLink -Path $link -Target (Join-Path $repo "rules\clear-precise-communication.md")

ln -sfn "$(pwd)/rules/clear-precise-communication.md" ~/.codex/clear-precise-communication.md

If the host cannot create a file symlink, copy the file instead. Add this stanza to ~/.codex/AGENTS.md if it is not already there:

## Mandatory ambient communication and writing guidance

At the beginning of each session, read `~/.codex/clear-precise-communication.md` completely and apply it throughout the session.

Do not reread it during the same session, unless immediately after a compaction.

Do not install this repo as a Codex plugin or skill.

Claude Code

Copy or junction claude-rules/ into ~/.claude/rules/ so the files load at session start with no invocation. They have no paths: frontmatter: a PR body drafted in chat still matches.

From the repository root:

$repo = (Get-Location).Path
$rules = Join-Path $env:USERPROFILE ".claude\rules"
New-Item -ItemType Directory -Force -Path $rules | Out-Null
$link = Join-Path $rules "clear-precise-writing"
if (Test-Path $link) { Remove-Item $link }
New-Item -ItemType Junction -Path $link -Target (Join-Path $repo "claude-rules")

mkdir -p ~/.claude/rules
ln -sfn /path/to/clear-precise-communication/claude-rules ~/.claude/rules/clear-precise-writing

Start a new Claude Code session. In /context, the files should appear under Memory files.

If you already have a short ~/.claude/rules/documentation-tone.md, remove it. claude-rules/documentation-tone.md replaces it.

claude-rules/ is 19.9k Opus 5 tokens. claude-rules-economy/ is the same constraints with less repetition (8.9k). Junction that directory instead when the context budget is tight. The full set is harder for Claude to ignore.

What changes

The rules put the primary value first, expose state and next actions when they matter, and remove details that slow the reader without helping them act.

Before

We made several updates to the authentication flow, including changes to magic-link handling and its related tests. Most of the work is complete, although there are still a few items that need attention before release. The staging checks passed, but production rollout is waiting on an environment variable from the platform team.

After

Magic-link authentication now passes in staging. Production rollout is blocked on one environment variable from the platform team.

• Complete: implementation and automated tests
• Verified: staging login flow
• Next owner: platform team

Core rules

1. Lead with the primary value.
2. Design for scanning.
3. Make starting easy and steps bounded.
4. Externalize current state, dependencies, and next actions.
5. Suppress tangents.
6. Give concrete time estimates when time matters.
7. Make progress and outcomes visible.
8. Describe errors matter-of-factly.
9. Keep lists focused and prioritized.
10. Remove preambles, repeated recaps, and generic closers.

Read the complete one-file rule in rules/clear-precise-communication.md.

claude-rules/ adds constraints that file did not enforce:

• Noun-phrase labels, not question headings or What/Where/Why comment openers
• Write from the reader's next action, not as a narration of the diff
• Scannable PR structure: tables for grids, one-fact bullets
• Title and opening name the user-visible effect
• Literal verbs, not idioms (deleted, not go with it; reports, not says)
• One term per concept; no synonyms for variety
• No rhetorical appositives (X — a …, a …, a … —); the things are the subject
• Changelog: change class, verb + symptom, ratios a reader can reuse
• Describe work to a reviewer; do not advocate for it
• Comments only for what code cannot say; structure or a test first

The full set restates that comments, drafts, and test names are in scope in each file. final-scan.md is the post-write search. The economy set says that once, in always-on-scope.md.

Customize

Edit rules/clear-precise-communication.md. Copy the body into claude-rules/clear-precise-communication.md, keeping the always-on preamble on the Claude copy. Re-copy into ~/.codex/ if that file is not a symlink. Start a new session so the revised text enters fresh context.

Attribution

This repository is a remix of Ayoub Ghriss's excellent i-have-adhd skill, which established the original ADHD-friendly approach to action-oriented AI responses. The original copyright notice remains in LICENSE.

The upstream project drew from The Adult ADHD Tool Kit by J. Russell Ramsay and Anthony L. Rostain, adapting its ideas for AI-generated communication.

License

MIT