AGENTS.md, CLAUDE.md, and the docs your agent keeps rewriting

Every repository has picked up a new kind of file in the last two years. AGENTS.md at the root, telling a coding agent how the project is laid out and what it must not do. CLAUDE.md beside it. A docs/ folder with specifications an agent drafted and a human half-edited. Plans, checklists, session notes, architecture decisions — all Markdown, all changing while you watch.

These files have properties ordinary documentation does not, and the tooling most of us use was designed for the ordinary kind.

What makes them different

They are read by two audiences. A human skims for the bit they need; a model reads the whole thing, every time, as context. That second reader is why the files get long and why structure matters more than prose polish. Headings are navigation for one audience and delimiters for the other.

They are written by something that never stops. An agent working on a task may rewrite its plan three times in ten minutes. The file on disk is a live object, not a document you open and close.

They are reviewed in pull requests. AGENTS.md is checked in. A change to it goes through the same review as a change to a source file, which means a noisy diff in a Markdown file costs the same as a noisy diff anywhere else — see why Markdown editors wreck diffs.

They mix prose with structure. Tables of conventions, task lists of what is done, the occasional Mermaid diagram of how the pipeline fits together. This is exactly the kind of Markdown that is miserable to read as source and pleasant to read rendered.

A setup that works

Four habits, none of them expensive.

Read them rendered, without leaving Finder

The single biggest improvement is not opening an editor to read a file. Select AGENTS.md, press Space, read it, press Space again. If your Mac does not do that yet, the Quick Look guide explains the one-time setup.

It sounds trivial. It is the difference between checking what the conventions say and guessing, because checking used to cost a window.

Keep a viewer open on the file the agent is editing

When an agent is rewriting a plan, you want to watch it happen rather than re-open the file every thirty seconds. A viewer that reloads when the file changes on disk turns the document into a live view of what the agent currently believes.

This also catches a specific failure mode early: an agent that has quietly rewritten a section you asked it to leave alone. You see it while it happens, not in the diff at the end.

Write AGENTS.md for a skimmer

The file is context, but a human still has to maintain it. A few things that survive contact with both readers:

• Short H2 sections with literal names. “Build”, “Tests”, “Conventions”, “Do not”. Not “Getting started with our developer experience”.
• Tables for rules with exceptions. A convention with three exceptions is a table, not four paragraphs.
• Task lists for state. - [ ] and - [x] are readable as text, render as checkboxes, and diff as one line.
• Fenced commands, exactly as typed. ```sh blocks are unambiguous to both readers.
• A “do not” section, stated plainly. Models follow prohibitions best when they are short, specific and unhedged.

Review Markdown changes like code

If AGENTS.md is in the repository, its diff is part of the review. Two rules keep that cheap:

1. Normalise once, deliberately — prettier --write '**/*.md' in its own commit, added to .git-blame-ignore-revs — so that every tool and every agent agrees on the house spelling of a bullet.
2. Use an editor that does not reformat what you did not touch, so that human edits stay one line long.

Without those two, every conversation about the document is conducted through a diff nobody can read.

Diagrams earn their keep here

A pipeline explained in four paragraphs is four paragraphs an agent must reconstruct into a shape. The same pipeline as a Mermaid graph is a shape already:

```mermaid
graph LR
    F[Fetcher] --> Q{{queue}}
    Q --> N[Normaliser]
    N --> D[(Warehouse)]
    N -.->|rejects| R[Dead letter]
```

Mermaid is text, so it diffs, reviews and is generated by a model as easily as prose — and it renders as an actual diagram in anything that supports it. Rendering Mermaid on macOS covers where that works and where it does not.

The part that is genuinely hard

None of the above solves the real problem, which is that these files rot. An AGENTS.md describing a directory layout from four months ago is worse than no file at all, because both readers believe it.

There is no tool for this. There is only the habit of reading the file occasionally, which is why making it easy to read matters more than it appears to. A document you can check in two seconds gets checked. One that costs a window launch gets trusted instead, which is another word for ignored.

---

Hem is a free, open source Markdown viewer and editor for macOS: Quick Look previews, live reload when a file changes on disk, Mermaid and LaTeX, and editing that writes back only the blocks you changed. It is 5.7 MB and it does not phone home.