What is AGENTS.md, and does your agent actually read it?

What goes in an AGENTS.md

The format’s site, agents.md, calls it “a README for agents: a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.” The sections it suggests are what a new teammate would need: a project overview, build and test commands, code style, testing instructions and security considerations, plus commit or pull request rules and deployment steps. On required fields its answer is “No. AGENTS.md is just standard Markdown. Use any headings you like.”

# AGENTS.md

## Setup
- Install dependencies: pnpm install
- Run the tests: pnpm test (must pass before any commit)

## Conventions
- TypeScript strict mode
- Never edit files under generated/

OpenAI released the format in August 2025. On December 9, 2025, the Linux Foundation announced the Agentic AI Foundation with three founding contributions: Anthropic’s Model Context Protocol, Block’s goose and OpenAI’s AGENTS.md. The site’s source is the agentsmd/agents.md repository on GitHub, and the site counts over 60,000 open-source projects using the format.

For a large repository the spec’s answer is more files, not a longer one: an AGENTS.md inside each package, where “the closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.” Each agent implements that rule its own way, and that is where they differ.

Which agents read it, and when

As each tool’s documentation stood on October 1, 2026:

Codex

Codex reads AGENTS.md “before doing any work.” Its AGENTS.md documentation says it builds an instruction chain “when it starts (once per run; in the TUI this usually means once per launched session).” First comes the global file in your Codex home, ~/.codex unless CODEX_HOME is set: AGENTS.override.md if it exists, otherwise AGENTS.md. Then every directory from the project root, usually the Git root, down to the one you started in, taking at most one file from each: AGENTS.override.md, then AGENTS.md, then any fallback names you have configured. The files are joined root first, and “files closer to your current directory override earlier guidance because they appear later in the combined prompt.”

Two limits follow from that. Codex stops at the directory you started in, so an AGENTS.md further down the tree applies only when you start Codex there, for example with codex --cd services/payments. And it “stops adding files once the combined size reaches” project_doc_max_bytes, 32 KiB by default. Since files are added root first, the nearest file, the one meant to override the rest, is the first to drop out of a chain that is too long. To see what loaded:

codex --ask-for-approval never "Summarize the current instructions."

Claude Code

Claude Code’s own file is CLAUDE.md. Since version 2.1.277 it also reads AGENTS.md directly, with a condition its memory documentation spells out: “By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it,” and a .claude/CLAUDE.md or CLAUDE.local.md counts too. A repository with both files gets its CLAUDE.md files only. To have Claude read both, set Project instructions to claude-md-and-agents-md in /config, or put an @AGENTS.md line in your CLAUDE.md, which expands the file into context at launch.

At session start it loads the files in your working directory and every directory above it, root first. They are “concatenated into context rather than overriding each other,” so instructions nearer where you launched are read last, and where two contradict, the docs warn that “Claude may pick one arbitrarily.” A subdirectory’s AGENTS.md loads when Claude reads a file in that subdirectory. AGENTS.override.md and AGENTS.local.md are not read. Run /memory and look for your AGENTS.md’s path in the list to check it loaded.

OpenClaw

In OpenClaw, AGENTS.md belongs to the agent rather than to a repository. It sits in the agent’s workspace, ~/.openclaw/workspace by default, beside SOUL.md, IDENTITY.md, USER.md and MEMORY.md, and the workspace docs describe it as “operating instructions for the agent and how it should use memory.” OpenClaw’s system prompt is “rebuilt each run,” per its context reference, and those files go into it under Project Context, so AGENTS.md is in front of the model on every run, not only at the start of a conversation.

The system prompt docs add the details that matter for a long file. Each injected file is cut at 20,000 characters and all of them together at 60,000 by default; when that happens, OpenClaw adds a notice telling the model the files were truncated and “to read the affected files directly.” A sub-agent is given AGENTS.md alone of these files. A session running from another folder gets that folder’s AGENTS.md appended after the workspace files. On OpenClaw’s native Codex harness, Codex loads AGENTS.md through its own discovery and OpenClaw does not inject it a second time. In a chat with the agent, /context list shows each injected file’s size and whether it was cut. What the other workspace files are for is in the guide to OpenClaw’s workspace files.

The others

• GitHub Copilot. Its repository instructions docs allow “one or more AGENTS.md files, stored anywhere within the repository,” and “the nearest AGENTS.md file in the directory tree will take precedence.” A single CLAUDE.md or GEMINI.md at the root works instead.
• Cursor. Its rules docs treat a root AGENTS.md as an alternative to .cursor/rules, and say nested files “are combined with parent directories, with more specific instructions taking precedence.”
• Hermes Agent. Per its context files docs, “only one project context type is loaded per session (first match wins),” in the order .hermes.md, AGENTS.override.md, AGENTS.md, CLAUDE.md, .cursorrules.
• Gemini CLI. It reads GEMINI.md by default. Its context file docs show how to add AGENTS.md in its settings.json:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

Loaded is not the same as opened

Every mechanism above loads a file the tool knows by name. An AGENTS.md often goes further and points at other files: read the deploy notes before deploying, check the migration guide before touching the database schema. Nothing loads those. On each turn the model has to judge that this turn is one the pointer covers, then spend a tool call opening the file, and the instruction to do so is itself only text it weighs. Claude Code’s docs draw the line for their own two files: if a CLAUDE.md tells Claude in words to read AGENTS.md, “Claude sees AGENTS.md only if it decides to open the file.”

Some of an agent’s own machinery rests on the same decision by design. OpenClaw’s context reference says the system prompt carries each skill’s name and description, and the model is expected to read the skill’s instructions “only when needed”; its daily memory notes are reached on demand rather than injected. A skill’s description is written to say when to use it. A pointer in AGENTS.md makes the same bet with a sentence you wrote.

What we measured

On September 21, 2026, we tested one OpenClaw agent, on OpenClaw 2026.9.4 with the model DeepSeek V4.1 Flash, whose AGENTS.md told it to read a reference file in its workspace, and follow it, before answering anything about a short list of named topics. We asked it questions the file answered. One conversation was an ordinary chat with its owner; the rest were fresh conversations holding a single question each.

• It opened the file in six of the eleven turns where the file held the answer. Each of those six times it answered as the file said, once only in part.
• In the other five it answered without opening the file, and every one of those five answers missed what the file said.
• Told its answer had not helped, it looked. In the chat with its owner, its first answer came from what it already knew. When the owner replied that the answer had not helped, it opened the file and gave the file’s answer.
• An extra trigger helped once in three. Partway through, we added a trigger to the list aimed at the kind of question it had been skipping. Of the three questions asked after that, two of them earlier misses, it opened the file for one. These three are among the eleven.

Then we replaced the list of topics with a moment. In substance, the instruction became:

Before your first reply in any conversation with your owner, read [the file] in your workspace, and keep to it for the rest of the conversation.

The three questions the topic list had let it miss were asked again, each in a fresh conversation. Each time it read the file before replying, and all three answers matched it. A fourth question asked for the number and total on a photo of a receipt, a job the file has nothing to say about, and it went straight to the photo without opening the file. Where it read the file, the read added about 4,500 tokens to the conversation.

That is one agent, one model, one OpenClaw release and one day, with no question asked twice under the same wording. It shows that the gap between a loaded file and a pointed-to file is real and can be wide. It does not give you the rate for your own model and wording.

What the result suggests

Our reading of the five misses, an interpretation rather than a measured cause: a “before answering about X” instruction depends on the model deciding, turn by turn, that the question is about X, and it makes that call with what it already believes. On none of the misses did it treat the question as one the file covered; it worked from its own assumptions or from what it found elsewhere. When it had a reason to doubt, as after the owner’s reply, it looked.

Tying the read to the start of the conversation removes most of that judgment, since the read happens before the agent has formed a view of the question. It does not turn the read into a mechanism. The agent still skipped the file on a job the file did not cover, so the instruction remains something the model weighs, which is how Claude Code’s docs describe instruction files in general: “Claude treats them as context, not enforced configuration.”

The price is the file’s size in every conversation that reads it, about 4,500 tokens for the one we tested. A file the agent has read is a tool result, so it stays in the conversation’s history, which every later model call sends, and when a long conversation is compacted, it is summarized along with the rest of the history. AGENTS.md is rebuilt into the system prompt on every run, so compaction does not reach it.

Where to put what the agent must know

• What it must act on every time goes in AGENTS.md itself, where the tool loads it without a decision, kept inside the loader’s budget: 32 KiB across the whole chain in Codex, 20,000 characters per file and 60,000 in total in OpenClaw, and under 200 lines per file is what Claude Code’s docs advise. In OpenClaw it is also the one workspace file a sub-agent receives. In Claude Code, an @path line does the same for another file: it is expanded into context at launch, up to four hops deep.
• A reference too long to carry on every run stays in its own file. If the agent needs it often, point at it by moment rather than by topic: at the start of every conversation, before the first reply. Expect to pay its size in tokens each time.
• If you keep a topic list, test it with real wording. Ask the questions the file answers, each in a fresh conversation and phrased the way people actually ask, and look in the agent’s tool calls for the read before its reply. A test that uses the list’s own words can pass while real questions miss.
• Check the loaded part separately: /context list in OpenClaw, /memory in Claude Code, the summarize command above in Codex. A file shadowed by a CLAUDE.md or past a size limit is not there for the model, however well it is written.