Writing for Humans in Agentic Development

Agent writes more prose than code — chat replies, commits, PRs, tickets.
Nothing compiles prose.
Bottleneck moved. Reading what the agent did is the slow part now.
Style is throughput, not taste.

Fix 1 — Telegraphic

Be ultra-concise. Use telegraphic style. Sacrifice grammar, articles, and filler words for maximum simplicity.

Drop function words. Keep content words.
Never drop negations, conditions, or degree of certainty.
Not fixed yet compressed to fixed is a lie, not a shorter sentence.
Before: Fixed the race condition in the session store by adding a mutex.
After: Race condition in session store — added mutex.

Fix 2 — Bullets

Paragraph = linear read. List = random access.
Skipping is the feature.
1 claim per bullet. Needs the next bullet to parse? It is a paragraph.

Fix 3 — A Fixed Shape

What: files/functions changed
How: concrete change
Why: reason, if known
Verified: how it was checked
Door: one-way (revert is hard) or two-way (revert is easy)
Not done: what was left unfinished, if anything

The last 3 answer the questions a reviewer asks next:

Verified forces the claim apart from the check. tests pass and not verified are both fine. Silence is not.
Door sets review depth. Two-way → skim. One-way → read it.
Not done surfaces the gap before you find it yourself.
Why, Not done: omit when empty. Door, Verified: code only.

Both of these are complete answers:

text

**What**: src/auth/session.ts — refreshToken()
**How**: expiry check moved before DB read; early return on expired token
**Why**: expired sessions hit the database on every poll
**Verified**: session tests pass; no manual run
**Door**: two-way
**Not done**: refresh path on the websocket handler

**What**: CLAUDE.md
**How**: added field-length rule
**Why**: you asked
**Verified**: not verified — prose only
**Door**: two-way

The Block

Paste into CLAUDE.md, AGENTS.md, or whatever the tool loads every run:

text

## Communication style

Be ultra-concise. Use telegraphic style. Sacrifice grammar, articles,
and filler words for maximum simplicity.

Always use bullet points. Prose only where the argument hinges on
connectives (A, therefore B, unless C).

- 1 claim per bullet.
- Bullet that needs the next one to parse is a paragraph in disguise.
- Parallel shape across bullets.
- 1 nesting level, max.
- Numerals, not words: 14, not fourteen. 1st, not first.
- Never drop negations, conditions, or degree of certainty.

When you change code, respond with:

- **What**: files/functions changed
- **How**: concrete change
- **Why**: reason (if known)
- **Verified**: how it was checked
- **Door**: one-way (revert is hard) or two-way (revert is easy)
- **Not done**: what was left unfinished (if anything)

- Each field: 1 fragment, few words.
- Field that grows into a paragraph defeats the shape.
- "**Why**: you asked" is a complete answer.
- **Why**, **Not done**: omit when empty. Never invent one.
- **Verified**: name the check. Not checked -> say "not verified".
- **Door**, **Verified**: code changes only. Skip both for text-only answers.