Agent Atlas

Field notes

The Playbook

An agent forgets everything between sessions. Whatever it knows tomorrow, someone wrote in a file today. This page is about keeping those files well: which ones exist, who writes them, the habits that keep several agents from tripping over each other, how hard to make each one think, and how one lead agent hands work to fresh ones.

The paper trail

Factual
Nine files agents read, when each one loads, and how to keep it.

When each file is read is documented by the tool makers. How to keep it is our advice, drawn from the builders. Plate II shows the loading order step by step. The field guide has every file in detail, and The Agent Files opens ten real ones.

Instruction file

AGENTS.md, CLAUDE.md

Read
At the start of every session, before your first message. (Anthropic; OpenAI; Agentic AI Foundation)
Written by
You, and the agent when you ask it to.
Keep it
Short. Anthropic says under 200 lines, because longer files cost more context and get followed less. OpenAI says keep it small. When you correct the agent, have it add the fix here.

Nested instruction file

web/CLAUDE.md, api/AGENTS.md

Read
When the agent works in that folder. The nearest file wins. (Anthropic; Agentic AI Foundation; Cursor; OpenAI)
Written by
You.
Keep it
Only what is true in that folder and nowhere else. Put guidance in the closest folder where it applies.

Skill

skills/release/SKILL.md

Read
Its short description is visible up front. The full text loads when the agent picks it. (Anthropic; Matt Pocock)
Written by
You, or a maker you trust.
Keep it
A description that says exactly when to use it. One workflow per skill.

Notes the agent keeps

memory/, MEMORY.md, progress.txt

Read
Claude Code loads the first 200 lines of MEMORY.md at every start; the rest when needed. Codex memories are off by default. (Anthropic; OpenAI; Google)
Written by
The agent, for its future self.
Keep it
One fact per note, dated. Never the only home of a rule that must always apply.

Plan or roadmap

roadmap.md, progress.txt, features.json

Read
At the start of a session, with the git log, to get up to speed. (Anthropic)
Written by
One owner. Usually the lead agent.
Keep it
What is done, what is next, in order. Anthropic keeps its feature list as JSON, which models overwrite less than Markdown.

Handoff

handoffs/CLAUDE_TO_GROK.md

Read
By the agent it is addressed to, when it starts. (Anthropic)
Written by
The agent handing work over.
Keep it
One file per direction, newest section last. Open with status, next owner, next action.

Task queue

research.md, a Beads graph

Read
Before an agent chooses work. (Steve Yegge)
Written by
Anyone can add. One agent claims each task.
Keep it
An id, an owner and a status on every task. Claim before you start.

Journal and decisions

journal.md, decisions.md

Read
Rarely. When someone asks why things are the way they are.
Written by
Whoever made the change or the call.
Keep it
Append only. The reason, not just the result.

Session transcript

~/.claude/projects/…/<session>.jsonl

Read
By you, or a search tool, when you need to know what an agent actually did. (Anthropic)
Written by
The harness, continuously, as the agent works.
Keep it
Leave it alone. Search it instead of re-explaining. Claude Code can find the session that made a pull request.

Settings and hooks

.claude/settings.json, a PreToolUse hook

Read
By the harness, not the model. Applied on every tool call. (Anthropic)
Written by
You.
Keep it
Anything that must never happen goes here, not in a text rule.

Same idea, six harnesses

Factual
AGENTS.md, CLAUDE.md, GEMINI.md and friends, side by side.

Every tool reads a project file and keeps some memory. The names and rules differ. AGENTS.md is the common ground: Codex, Grok and Cursor read it, and Claude Code reads it through one import line.

HarnessProject fileMemory
Claude CodeCLAUDE.md. Reads AGENTS.md itself only when there is no CLAUDE.md; otherwise import it with @AGENTS.md. Nested files load when it works in that folder. (Anthropic)Auto memory. The first 200 lines of MEMORY.md load at every start. (Anthropic)
CodexAGENTS.md, from the project root down to the folder you launch in, at most one per folder. (OpenAI)Off by default. A recall layer, never the only home of a rule. (OpenAI)
GrokAGENTS.md and CLAUDE.md, loaded in full for every session, with no size cap. (xAI)Curated notes in topics/, one file per subject, read at the start of a session. (xAI)
Gemini CLIGEMINI.md files from several folders, joined and sent with every prompt. Split big ones with @file.md. (Google)Facts written straight into Markdown memory files, loaded in later sessions. (Google)
Cursor.mdc rules in .cursor/rules need frontmatter, or they are ignored. Nested AGENTS.md files apply in their folder. (Cursor)Not in our sources yet.
ClineNot in our sources yet. A Memory Bank of Markdown files, read at the start of every task. (Cline)

How this site is run

Factual
Three agents from three companies: Claude leads, Grok researches, Codex checks.

Three agents from three companies build Agent Atlas. Claude leads and merges, Grok researches, Codex checks every quote. They never talk directly. They talk through these files.

AGENTS.md              rules every agent reads first
agentic-scaffolding/
  roadmap.md           done and next, owned by Claude
  collaboration.md     who owns what, how to hand off
  research.md          the task queue: R-001 to R-021
  handoffs/
    CLAUDE_TO_GROK.md  one file per direction,
    GROK_TO_CLAUDE.md  newest section last
    CODEX_TO_CLAUDE.md
  research/            each agent's raw findings
  journal.md           what happened, appended
  decisions.md         why, appended
content/sources.yaml   only checked quotes reach the site
A research request moves from OPEN to CLAIMED to READY to CLOSED. Each agent works on its own branch and opens a pull request. Only the lead merges, and only after the site's tests pass.

Rules for the paper

Our advice. Each one fixes a mistake we or the builders made.
  1. One fact, one home. Copied rules drift apart. Link or import instead.
  2. Every handoff opens with status, next owner, next action. The next agent knows in three lines whether the work is theirs.
  3. Date everything that can go stale. A model name or a price is true on a day. Write the day, and when to re-check.
  4. One owner per file. Others write to the owner through a handoff. Two agents editing one plan is how plans rot.
  5. Maps get rewritten, logs get appended. Rewrite the roadmap so it stays short. Never rewrite the journal.
  6. Rules in the instruction file, history elsewhere. The instruction file is paid for on every turn. Stories belong in the journal.
  7. If it must never happen, make it code. A hook blocks a bad command whether the model agrees or not.
  8. Write the next prompt before you clear. The last thing a session does is leave a ready prompt for the fresh one.
  9. Keep the paper in git, and push. Work that lives on one machine is work nobody else can pick up.

The effort dial

Factual
How long the model thinks before answering, and when to turn it up.

Newer models take an effort setting: how long to think before answering. After the choice of model, it is the biggest lever on your allowance. Turn the dial.

Effort

What the makers say

  • Low and medium work well for routine tasks and stretch your usage further. (Anthropic)
  • Lower effort also means fewer, terser tool calls. (Anthropic)

What builders do

  • Thariq Shihipar implements on low while he stays in the loop. (Thariq Shihipar)
  • Boris Cherny picks low for speed, knowing it is less intelligent. (Boris Cherny on X)

What the makers say

  • Claude Opus 5.5 and Haiku 5.5 start here by default. (Anthropic)

What builders do

What the makers say

  • Most Claude models default to high. (Anthropic)
  • Grok defaults to high when you set nothing, and its reasoning cannot be turned off. (xAI)

What builders do

  • Thariq Shihipar verifies on high, where edge cases matter. (Thariq Shihipar)
  • Paweł Huryn uses high for small daily tasks. (Paweł Huryn)

What the makers say

  • For the hardest long-running coding and agent work, where a gain has been measured. (Anthropic)
  • Deeper than high, without the full token cost of max. (Anthropic)
  • OpenAI: only when evals show a clear benefit worth the extra time and cost. (OpenAI)

What builders do

  • Boris Cherny raises Opus to xhigh or max for complex visual work. (Boris Cherny on X)

What the makers say

  • OpenAI and Codex list max on some models. Which levels exist depends on the model. (OpenAI; OpenAI)

What builders do

  • Thariq Shihipar uses max when he wants the model to work a hard problem through on its own. (Thariq Shihipar)
  • Paweł Huryn points max at his hardest tasks. (Paweł Huryn)
Effort is a token budget.

It sets how many tokens the model spends answering, thinking included. (Anthropic; OpenAI)

You pay for thinking you never see.

Reasoning tokens are hidden, take up context, and are billed as output. (OpenAI; xAI)

The same word is a different amount on each model.

Claude Code calibrates the scale per model, so “high” on one is not “high” on another. (Anthropic)

Measure before you climb.

Both Anthropic and OpenAI say to use the top levels where a gain has been measured. (Anthropic; OpenAI)

Same model, two settings. Paweł Huryn pointed one model at 105 bugs (Paweł Huryn).
High13 fixed
Max33 fixed

A common split: plan and review high, build low. Thariq Shihipar implements on low, reviews, then verifies on high, and changes the level mid-conversation with /effort (Thariq Shihipar).

One lead, fresh hands

Simplified
One agent keeps the plan; fresh workers each take one task.

One agent keeps the bird's-eye view and never does the detailed work. It hands each task to a fresh agent with a short, complete prompt, takes back a short result, and lets that agent go. Each worker starts with almost nothing in its context, so nothing old can mislead it.

The leadholds the plan and the queuewrites task promptsreviews, merges, clears
Workerfresh contextone task, own branch
Workerfresh contextone task, own branch
Checkera different modelreviews the result
Anthropic built its own Research feature this way: a lead agent plans and hands pieces to subagents that work in parallel (Anthropic). Each subagent explores in its own context and hands back a short summary (Anthropic; Anthropic). The checker is a different model because different models miss different things (Paweł Huryn).

Every harness ships this now

Claude Code subagents

Each starts with a fresh, isolated context and works only from the message Claude writes it. (Anthropic)

Claude Code agent teams

One session leads. Teammates have their own contexts and talk to each other. Shut them down when done. (Anthropic; Anthropic)

Codex

Subagents with a prompt that says how to split the work and what to return. Cloud tasks each get their own workspace and keep going while your computer sleeps. (OpenAI; OpenAI)

Grok

Subagents are child sessions with their own context that hand a summary back. On by default. (xAI)

What goes in a task prompt

Anthropic's list: an objective, an output format, guidance on tools and sources, and clear task boundaries (Anthropic). OpenAI adds how to split the work and whether to wait for the others (OpenAI). In practice:

  • Who it is and which files to read first.
  • The one task, and "nothing else".
  • Where to put the result, and in what shape.
  • What it must not touch.
  • How to say it is done: a status, a next owner, a pull request.

Point to files instead of pasting summaries. Matt Pocock's implementers get the spec, the ticket, shared notes and earlier commits, not a retelling (Matt Pocock).

The prompt this site's lead gave Grok on November 13, 2026:

You are Grok, research director on Agent Atlas. Read AGENTS.md,
agentic-scaffolding/collaboration.md, the newest section of
handoffs/CLAUDE_TO_GROK.md, and request R-018 in research.md.
Do R-018 only, nothing else. Claim it and commit. ...
Write the deliverable files the request names. Set R-018 to READY
with next owner Codex. Append a dated section to GROK_TO_CLAUDE.md.
Commit and push after every commit. Open a PR to main.
Do not edit content/ or src/. No social posts.

When to clear a worker

  • When its task has landed. Anthropic's docs say to shut teammates down when their work is done (Anthropic).
  • Before anything new. Will Ness clears when one task ends and the next begins (Will Ness).
  • Size tasks to one context. Matt Pocock's rhythm: clear, implement one ticket, commit, clear again (Matt Pocock).
  • Hand over the plan, not the history. Hugues Clouâtre's build agent receives only the finished plan (Hugues Clouâtre). Jesse Vincent clears his implementer instead of compacting it (Jesse Vincent).
  • Every reply re-reads the whole conversation, so a long life costs more and recalls less. See Plate IV.

Taken to the limit

Geoffrey Huntley's Ralph feeds the same prompt to a fresh agent over and over, with all memory in files (Geoffrey Huntley). Steve Yegge's Gas Town ran dozens of parallel agents with oversight (Steve Yegge). He has since retired it, and the task graph, Beads, outlived it (Steve Yegge). More tools like these are on the Tool Shelf.