How to write docs that AI coding agents can actually read

Your wiki has 400 pages. Your agent reads three of them and ignores the rest. The pages it does read, it half-understands.

That's not because the docs are bad. They were written for a human skimming on a Tuesday afternoon, looking for one specific answer. Agents don't skim. They sample, they guess, and they confidently fill in the gaps with whatever sounds plausible.

If you want Cursor, Claude Code, or Codex to actually use your docs, you have to write them differently. Not harder — differently.

What agents struggle with

Before fixing the docs, name what's broken. Most team documentation fails agents in three ways:

1. Implicit context. "We use the standard pattern" means nothing without naming the pattern.
2. Buried decisions. The why lives in a Slack thread or a closed PR comment, not in the doc.
3. Stale truth. The doc says one thing; the code says another. Agents trust the doc and ship broken code.

Seven rules for AI-readable docs

1. Lead with the conclusion

Agents read top-down and weight early tokens more. Put the rule first, the rationale second, the history last.

Bad: "Historically, we used JWTs, but after the 2024 incident…"
Good: "Use session cookies, not JWTs. Reason: the 2024 incident showed JWT revocation took 24 hours."

2. Name the pattern explicitly

Don't write "the usual way." Write the literal name: "the withTenantContext wrapper." If a function exists, reference it. If a file exists, link to it.

3. Write decisions, not summaries

A summary tells the agent what the code does — which it can already see. A decision tells it what not to do, which it can't infer.

Useful: "We chose Postgres triggers over application-level cascades because of the 2025 data integrity audit. Don't bypass the trigger by writing directly to the table."

4. Keep one source of truth per topic

Agents weight whichever doc loads first. If two docs disagree, you'll get coin-flip behavior. Pick one canonical doc per topic and link the others to it.

5. Use stable identifiers, not screenshots

Agents can't read images. They can read filenames, function names, env var names, and table names. Reference the thing, not a picture of it.

6. Prefer markdown over rich docs

Notion, Confluence, and Google Docs all serve agents through scraped HTML. Markdown is what they ingest cleanly.

7. Keep docs next to the code

If your briefs live in the repo, your agent reads them on every session. If they live in a wiki, your agent reads them when you remember to paste them in.

A template that works

Every brief in our system follows the same shape:

1. Title: what this is in plain language.
2. Decision: the rule the agent should follow, in one sentence.
3. Why: the reason, with a link to the original conversation or PR.
4. Don't: the most likely wrong path, written explicitly.
5. Reference: files, functions, or tables involved.

A 200-word brief in this shape beats a 4,000-word wiki page. The agent finds the rule in the first 50 tokens and stops guessing.

The shortcut

Writing briefs by hand works. It's also slow — and the kind of discipline most teams burn out on.

Brifly automates the capture: record a 5-minute walkthrough, get a brief in this exact shape, query it from the CLI. Cursor, Claude Code, and Codex all read from the same set.

Tool or no tool, the discipline is the same. Write briefs the agent can actually read, and you stop being the context shovel.