Every builder writes a letter their agents read before every task. These ten are real, pinned to the commit we read. Some are 24 lines. One is 1,168. Open them, and see what to steal and what to watch for.
Ten files, weighed
EstimateReal agent files from builders, by size. The heaviest is over a hundred times the lightest.
Tokens are bytes divided by four, a rough rule for English. The point is the spread: the heaviest is over a hundred times the lightest. Anthropic suggests under 200 lines (Anthropic), and every line takes some attention on every task (Anthropic).
24 lines · about 110 tokens, read at the start of every session
Steal
Only the commands an agent cannot guess: set up, test, build the docs.
Watch
Nothing else. That is the point for a small, well-tested library.
# AGENTS.md
This project uses a Python environment for development and tests.
## Setting up a development environment
1. Install the project with its test dependencies:
```bash
pip install -e . --group dev
```
2. Run the tests:
```bash
pytest
```
Emanuel runs ten or more agents on one project (Agent Flywheel), and has them reread AGENTS.md after compaction (Jeffrey Emanuel). Ten agents reading his heaviest file is about 140,400 tokens before anyone types. The cache makes that cheap in money, not in attention. He ships a great deal anyway: a long file is a cost, not a verdict.
What the good ones share
FactualShort, specific, and about what the agent cannot read for itself.
Commands first. How to test, type-check and build, exactly. Simon Willison’s whole file is that. Anthropic puts it at the top of its list of what belongs. (Simon Willison; Anthropic)
A router, not a manual. Omarchy’s file opens with an index of task guides. Steinberger keeps “hard rules only” and leaves workflows to skills, which load when picked. (Basecamp; Peter Steinberger; Anthropic)
One file, one home. Every keeps one AGENTS.md and links CLAUDE.md to it. Emanuel puts the rules all his repos share in one suite-wide file. (Every; Jeffrey Emanuel)
The rules that bite are enforced somewhere else. Anthropic’s file names the CI check that fails when a rule breaks, and tells the agent not to weaken it. (Anthropic)
Room to disagree. Pi’s file makes the agent say whether it agrees before it changes anything. Steinberger asks for a collaborator with a point of view. (Mario Zechner; Peter Steinberger)
Written from scars. Boris Cherny turns every mistake into a line. Every has the agent write the lesson down after each verified fix. (Boris Cherny on X; Every)
A messy file, cleaned
SimplifiedA bad agent file and the fix for each mistake. Tap a red number.
Made up for this page from mistakes that show up in real files, ours included. Tap a red number to see what is wrong with the line.
# AGENTS.md (updated March)
## IMPORTANT!!! READ ALL OF THIS CAREFULLY!!!
ALWAYS think very hard and be extremely thorough.
Keep going until everything is done. Never be lazy.
Never ask me questions, just do it.
Always ask before changing more than one file.
## Architecture
The app is a Next.js frontend in /web that talks to a
FastAPI backend in /api. Users live in Postgres. Auth is
in /api/auth and uses JWTs, refreshed every 15 minutes...
## Rules
- Use claude-3-opus for everything, it is the best model.
- Write clean code.
- NEVER run rm -rf or git push --force.
- Run `npm test` before committing.
- We use pnpm, not npm.
- Copy the patterns in /src/legacy.
- Staging key: sk-live-4f9a2c...
## History
In June we tried Redux and it was a disaster. Sam spent
two weeks ripping it out, so never suggest Redux again.
- Write clean code.
Shouting. Current models follow a plain line, and capitals make them over-apply it.
"Think hard" is ordinary text, not the effort setting. "Keep going" causes over-work more often than it fixes a stall.
These two contradict each other. The agent has to guess which one wins, every time.
The agent can read the code. Describe only what the code cannot tell it.
An undated model name. It went stale and nobody noticed.
Nothing to check. Name the command or the rule instead.
A rule that must never break belongs in a hook, which blocks the command whether the model agrees or not.
npm or pnpm? The wrong test command, next to the rule that contradicts it.
That code still runs, but it is the style the team is moving away from. This line tells the agent to spread it.
A live secret in a file every agent reads and every commit carries.
A story. Keep the reason in decisions.md, and the rule here in one line.
The same line twice. Copies drift apart.
Where the fixes come from: capitals, “think hard”, “keep going” and architecture tours (Anthropic). Hooks block a command before it runs (Anthropic). Dates and one home per fact are our rules for the paper.
Five ways to run many agents
FactualHow agents that never share a mind avoid stepping on each other.
Every setup answers the same question: how do agents that never share a mind avoid stepping on each other?
One lead, files as the wire
This site: Claude leads, Grok researches, Codex checks.
Each agent works on its own branch and writes to the others through handoff files. Only the lead merges.
Breaks: Slow. The lead is the bottleneck, and every handoff is only as good as the agent that wrote it.
Ten or more agents commit straight to main with no worktrees. They reserve files through Agent Mail before editing, and pick tasks from a Beads graph. (Agent Flywheel; Jeffrey Emanuel)
Breaks: Needs his tooling. Every agent sees the others’ half-finished edits, all the time.
A worktree per agent
Jesse Vincent, Kieran Klaassen.
Each task gets its own checkout of the repo, so agents never touch each other’s files. (Jesse Vincent; Kieran Klaassen; Git)
Breaks: Conflicts do not disappear. They wait until merge, and arrive together.
A lead with fresh workers
Ethan Mollick, Anthropic’s research system.
One agent splits the job and hands each piece to a fresh worker with its own context. (Ethan Mollick; Anthropic)
Breaks: Cost. Anthropic measured about 15 times the tokens of a chat.
Breaks: Tops out at your attention. DHH puts his limit at about sixteen threads.
What memory is for
FactualThree layers: what happened, what was learned, and the rules that follow.
Jeffrey Emanuel’s cass-memory sorts agent memory into three layers (Jeffrey Emanuel). The split is useful even if you never install it.
Raw sessions
Every harness saves transcripts as it works (Anthropic). Complete and true, far too big to reread. Search them instead (Jeffrey Emanuel).
Summaries
Handoffs, journals, diaries. Small enough to read, but written by an agent at the end of a long life. Check them against the git log before you trust them.
Rules
AGENTS.md, MEMORY.md, a playbook. Read at every start, so every line must earn its place. Codex calls its memories a recall layer, never the only home of a rule that must always apply (OpenAI).
What cass adds: forgetting on purpose
Rules lose confidence unless confirmed again: it halves every 90 days. One harmful mark counts four times a helpful one, and a rule marked harmful again and again turns into a warning (Jeffrey Emanuel).
The price: agents ask it for rules before each task (Jeffrey Emanuel), and the README’s feedback marks live in code comments (Jeffrey Emanuel). That clashes with a repo that bans comments.
The idea worth taking even without the tool: memory that only grows gets worse. Something has to remove lines.
Five questions for any line of memory
Would a fresh agent act differently because of this line? If not, delete it. It costs attention on every task.
Is it dated? A model name, a price, a “pending” decision: true on a day. Write the day.
Does it have one home? If it is also in the code, the roadmap, or another agent’s file, link instead.
Would you notice if it were wrong? A memory nobody checks drifts. Have the agent verify a note before acting on it.
Does anything ever remove lines? If memory only grows, it rots. Decide what gets pruned, and when.
Our own files, critiqued
FactualThis site’s own agent files, held to the same standard.
Micah, who runs this site, asked for the same scrutiny on his own setup. His global file is 29 lines, about 800 tokens, read by Claude and Codex through one symlink. Server details are left out.
What the 29 lines hold
Kind
Lines
How to write the file itself
1
Working style: no open-items lists, keep going, plain prose, subtract
7
Hard rules: no stray files, no comments or unit tests, no subagents
3
Session ritual: read the voice file, preview links, clear point, memorial, card, keepsake
6
Pointer to a long outside skill, and which rules win
1
Tools: a friend's servers and search
5
Headings and blank lines
6
Keep
Short, and one file for both agents, the same move as Every’s symlink (Every).
Deploys are blocked by a hook, not a sentence (Anthropic).
Each project keeps his own words, verbatim, for the next agent to read first. Intent survives the clear, not just status.
Fix
“Keep going until there are no loose ends!” Anthropic says lines like that cause over-work more often than they fix a stall (Anthropic). Name the finish line instead: done means pushed, verified, handoff current.
Over a third of the file is ritual and tool notes that every agent reads, even for a two-minute question. Steinberger’s rule fits: hard rules only, workflows in skills that load when needed (Peter Steinberger; Anthropic).
Two rulebooks that disagree. The pointer pulls in a long outside skill that spawns subagents, then this file has to say its own rules win. Fold in the few rules you want from it, and drop the pointer.
The voice file only grows. One project’s is 15 KB, read at every start, and four of its newest entries say a transcript could not be parsed. Every future agent rereads that noise. Keep recent sessions whole, shrink old ones to a line, drop failed summaries.
Undated memory. A note like “voices pending Micah’s pick” may have been settled weeks ago. Date every note, and have the agent check it before acting.
Two rules want to be hooks: no new files in the projects folder, and push only your own commits. Text works most of the time. A hook works every time (Anthropic).
“No subagents unless asked” holds up. Anthropic now says they cost tokens and do not make answers smarter (Anthropic). Carve out the one case that earns it: a fresh reviewer that has not seen the reasoning.