AGENTS.md: what "supported" actually means, tool by tool

TL;DR

• AGENTS.md has no required fields. Its own site says so: standard Markdown, any headings you like.
• It states one precedence rule, that the closest file wins, in a FAQ answer and again in a setup step. It never calls itself a specification. Seven tools that read the format describe seven different mechanisms.
• Codex says the quiet part on its own page: the closer file overrides earlier guidance because it appears later in the combined prompt. Between directories that is word order, not enforcement. Inside one directory there is a rule, and AGENTS.override.md wins it.
• Codex also stops loading files once the total reaches 32 KiB, a default rather than a ceiling, and because it concatenates from the root down, the files at risk are the ones nearest your code. The same page documents raising the limit.
• None of these tools is lying. With no schema, there is nothing to conform to.

AGENTS.md is a good idea and a successful one. Over 60k open-source projects carry one, its front page names 23 tools that read it, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation rather than by any single vendor. None of what follows argues against the format.

What follows is narrower and, if you maintain a monorepo, more useful: the sentence on the website and the sentences in the tools' own documentation are not the same sentence. Every quotation below was fetched from its source page on 2026-08-31 and matched against it word for word.

A note on who is writing. We build Mnemoverse, a memory layer for AI agents. Nothing of ours is involved in any of this and nothing of ours appears below except one line at the end.

What the format promises

Three passages on the AGENTS.md site carry the whole subject. Two of them are FAQ answers.

On structure:

Are there required fields?

No. AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide.

On conflict:

What if instructions conflict?

The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.

The third passage is not in the FAQ. It is step 4 of "How to use AGENTS.md?", and it is the stronger of the two precedence statements, because it describes what tools do rather than stating a rule:

Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.

Agents automatically read the nearest file in the directory tree. That is the sentence a monorepo maintainer acts on, and the sections below are a check of it against each tool's own page.

Read the three together. There is no schema, so a tool cannot be non-conformant about structure. And there is a precedence rule, phrased the way a specification phrases a requirement: wins.

The site does not call it a specification. The words specification, schema and conformance do not appear anywhere on the page, and the section that carries the rule is headed FAQ. What follows treats the sentence as what the site presents it as: the format's own account of itself.

That word is doing a lot of work, and the tools do not agree about what it means.

Copilot on GitHub: the nearest one takes precedence, and that is all the page says

From the Copilot documentation:

You can create one or more AGENTS.md files, stored anywhere within the repository. When Copilot is working, the nearest AGENTS.md file in the directory tree will take precedence.

This matches the format's own wording. If you read only that sentence, the rule holds.

It is also all the page says on the subject. There is no merge order, no statement that the other files are dropped, nothing about how the nearest one comes to take precedence. The claim is repeated, the mechanism is not given, and from this page you cannot tell what becomes of the file that loses.

Two further things about the page are worth naming, because the rest of this article treats it as the one that agrees.

It covers one surface, and says so in its first paragraph.

Repository custom instructions let you provide Copilot with repository-specific guidance and preferences on GitHub. To find out how to set up custom instructions in an IDE, see Adding repository custom instructions for GitHub Copilot in your IDE.

This page is Copilot on GitHub. The VS Code section below is the same product in an editor. That is two of the rows in the table further down, describing one product on two surfaces.

Priority on this page means ordering, not exclusion. A note lower down, about the three kinds of custom instructions rather than about two AGENTS.md files, says what a priority order does:

Multiple types of custom instructions can apply to a request sent to Copilot. Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last. However, all sets of relevant instructions are provided to Copilot.

That note is not about nested AGENTS.md files, so it does not contradict the sentence quoted above. It is on the same page, and it says that coming second in the order does not mean being left out.

VS Code: the agent decides, and the page never says if nesting is on

From the VS Code documentation:

VS Code automatically detects an AGENTS.md Markdown file in the root of your workspace and applies the instructions in this file to all chat requests within this workspace. This is useful if you work with multiple AI agents in your workspace and want a single set of instructions recognized by all of them, or if you want subfolder-level instructions that apply to specific parts of a monorepo.

The root file is found without being configured, and the second sentence is worth keeping. This page names the monorepo case as one of the two reasons it gives for using the format at all, and the list under that paragraph repeats it:

• You work with multiple AI coding agents and want a single set of instructions recognized by all of them
• You want subfolder-level instructions that apply to specific parts of a monorepo

Root support has a switch, and the page introduces it after the automatic detection rather than before:

To enable or disable support for AGENTS.md files, configure the chat.useAgentsMdFile setting.

Subfolders get their own section, and the page puts a badge reading Experimental above it, followed by this line:

Nested AGENTS.md files is experimental and might change or be removed.

The section then says what nesting is for:

Using multiple AGENTS.md files in subfolders is useful if you want to apply different instructions to different parts of your project. For example, you can have one AGENTS.md file for the frontend code and another for the backend code.

And what it does:

Use the chat.useNestedAgentsMdFiles setting to enable or disable support for nested AGENTS.md files in your workspace.

When enabled, VS Code searches recursively in all subfolders of your workspace for AGENTS.md files and adds their relative path to the chat context. The agent can then decide which instructions to use based on the files being edited.

The closest file does not win by rule, and the choice is not a free one either. The paths go into the context, and the decision is made based on the files being edited, which is nearer to the FAQ's sentence than a bare list of paths would be. It is still a decision taken by a model while it answers, rather than a rule applied before it is asked.

The page states no default for either setting. It states defaults elsewhere in the same document when it means to, chat.instructionsFilesLocations (default: .github/instructions) among them, so whether nesting is on in your install is something to read out of your settings and not off this page.

Codex: three rules in one list, and the last one is word order

This is the page worth reading in full if you read only one. From Custom instructions with AGENTS.md:

Merge order: Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.

That sentence is the third of three numbered items, introduced together:

Discovery follows this precedence order:

The first two are selection, and they do resolve conflicts. In the Codex home directory, and again in every directory on the way down, a file named AGENTS.override.md is read in preference to AGENTS.md, and only one file per directory is taken at all:

In each directory along the path, it checks for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames. Codex includes at most one file per directory.

Between directories there is no such rule. The selected files are joined in order, nothing is compared, and the nearer one "overrides" the way the last speaker in an argument wins: by being last. That is not a criticism of Codex. It is the most honest description of the mechanism anyone in this article gives, and it is on their own page, unprompted.

Two consequences follow from the same page, and both matter in a large repository.

Instructions can be dropped, and the same page says what to do about it.

Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default).

That is the first sentence of the paragraph. After a link to the configuration reference, the same paragraph ends with the remedy:

Raise the limit or split instructions across nested directories when you hit the cap.

The troubleshooting section carries it again under a heading of its own, "Instructions truncated", and a worked configuration example on the page sets project_doc_max_bytes = 65536 and describes the larger limit as allowing more combined guidance before truncation. So the cap is a default and the page documents changing it. What the page does not document anywhere is a warning at the moment guidance is cut, so a reader who goes looking for one will not find it.

Concatenation runs from the root down, so the files at risk of falling outside the budget are the ones deepest in the tree. Those are the ones nearest your code, which are exactly the ones the site says should take precedence.

There is a filename you have probably never seen.

AGENTS.override.md is documented by Codex and appears nowhere on agents.md. It is where the page resolves a conflict rather than ordering one: the sample repository tree annotates the AGENTS.md sitting beside an override as "Ignored because an override exists", and the troubleshooting section treats a forgotten one as the reason the wrong rules are in force.

Wrong guidance appears: Look for an AGENTS.override.md higher in the directory tree or under your Codex home. Rename or remove the override to fall back to the regular file.

It works at the global level too:

Use ~/.codex/AGENTS.override.md when you need a temporary global override without deleting the base file. Remove the override to restore the shared guidance.

That is a clean way to suspend your own global defaults without deleting them.

Cursor: combined, and no mechanism stated for the nested files

From Cursor's rules documentation:

AGENTS.md is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to .cursor/rules for straightforward use cases.

And on nesting:

Cursor supports AGENTS.md in the project root and subdirectories.

Further down, under a heading of its own, the page says when a nested file applies:

Nested AGENTS.md support in subdirectories is now available. You can place AGENTS.md files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children.

Then, after a directory tree with four of them across three levels:

Instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence.

Combined, as in Codex. Precedence claimed, as on the AGENTS.md site. No mechanism is stated for the nested files, so a reader cannot tell whether Cursor resolves the conflict or whether the specific instruction is simply later in the prompt.

The page does state a mechanism, for a different set of rules. Under Team Rules:

Precedence: Rules are applied in this order: Team Rules → Project Rules → User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts.

Merge everything, and where guidance conflicts the earlier source takes precedence. That is the reverse of Codex, where the later text in the prompt overrides what came before. The page opens by naming four types of rules, of which AGENTS.md is one, and that ordering names three of them. Where an AGENTS.md file sits against a project rule, and what happens between two nested AGENTS.md files, the page does not say.

The same page describes the underlying model plainly, and it is worth quoting because it applies to every tool here:

Large language models don't retain memory between completions. Rules provide persistent, reusable context at the prompt level.

When applied, rule contents are included at the start of the model context. This gives the AI consistent guidance for generating code, interpreting edits, or helping with workflows.

opencode: the first match wins, and it traverses upward

The film's mirror image of Codex, and the reason the two of them are the pair worth staying for. From opencode's rules documentation, under the heading Precedence:

When opencode starts, it looks for rule files in this order:

1. Local files by traversing up from the current directory (AGENTS.md, CLAUDE.md)
2. Global file at ~/.config/opencode/AGENTS.md
3. Claude Code file at ~/.claude/CLAUDE.md (unless disabled)

The first matching file wins in each category. For example, if you have both AGENTS.md and CLAUDE.md, only AGENTS.md is used.

Read the direction. The traversal runs up from the directory you are working in, and the first match wins, so the file that wins is the nearest one and the root file is reached only when there is nothing nearer. The page's own example of a category is AGENTS.md against CLAUDE.md in the same place, and its word for what happens to the loser is that only the winner "is used".

Set that beside Codex. Codex takes one file per directory and concatenates all of them from the root down, so the root file is present and the nearer one overrides it by being later in the prompt. opencode takes one file, full stop. Both are consistent with the sentence on the AGENTS.md site, because that sentence says which file wins and never says whether the losers are read.

Two tools, one format, two ways to lose an instruction, and neither of them contradicts the specification.

Aider: nothing is discovered

Aider's own page on the subject, Specifying coding conventions, does not mention AGENTS.md. The string does not occur on the page at all. It documents a different filename and two ways to load it. The first is per session:

It's best to load the conventions file with /read CONVENTIONS.md or aider --read CONVENTIONS.md. This way it is marked as read-only, and cached if prompt caching is enabled.

The second route has a heading of its own on the same page, Always load conventions:

You can also configure aider to always load your conventions file in the .aider.conf.yml config file:

Under it the page gives read: CONVENTIONS.md, and a bracketed list for several files. With that line in place, the file loads on every run and you pass nothing in.

What the page never documents is discovery. In both routes the filename is a value you supply, in the chat, on the command line or in the config file, and no route on the page has Aider find it by name on its own. The AGENTS.md FAQ contributes exactly one thing here, and it is the filename: read: AGENTS.md in place of the read: CONVENTIONS.md that Aider documents in the same config file.

Gemini CLI: the filename is a setting, and their example puts AGENTS.md first

The page that documents this is Provide context with GEMINI.md files. Files are found, and they are found hierarchically:

The CLI uses a hierarchical system to source context. It loads various context files from several locations, concatenates the contents of all found files, and sends them to the model with every prompt.

What is not discovered is the name. The name is a setting:

While GEMINI.md is the default filename, you can configure this in your settings.json file. To specify a different name or a list of names, use the context.fileName property.

The example printed directly under that sentence, on the same page, is this:

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

AGENTS.md is the first entry. So Gemini CLI does document the format under this name, and the configuration line is not something the AGENTS.md site had to supply on the tool's behalf. It is also the only occurrence of the string AGENTS.md in the 95 Markdown files under docs/ on the default branch, and it occurs there as one value in an example rather than under a heading of its own.

Two similar names are worth keeping apart. The setting above is context.fileName in settings.json, and it governs project instructions. The extension manifest has a separate contextFileName field, documented in the extension reference, which loads context from the extension's own directory.

The shape, in one table

	what its own documentation says happens
the AGENTS.md site	the closest file wins, in a FAQ answer and in step 4
Copilot on GitHub	the nearest file takes precedence, mechanism not stated
VS Code, root	detected automatically; chat.useAgentsMdFile enables or disables it
VS Code, nested	paths are added and the agent decides based on the files being edited; experimental, no default stated
Codex	one file per directory, concatenated root-down; nearer means later; AGENTS.override.md suppresses the file beside it; dropped past 32 KiB by default
Cursor	combined with parents, more specific takes precedence; no mechanism stated for the nested files
opencode	one file, the first match while traversing up; the root file is reached only if nothing is nearer
Aider	nothing is discovered; you name the file, with /read or in .aider.conf.yml
Gemini CLI	found hierarchically under the names you configure; default GEMINI.md, and the page's example lists AGENTS.md first

Seven tools and one sentence on the website. Eight rows, because VS Code documents what it does with a root file and what it does with nested files separately and they are not the same mechanism. Fewer than seven vendors, because two of those rows are one product on two surfaces, Copilot on GitHub and Copilot in an editor.

Why this is not a flaw in AGENTS.md

It is a trade, and the openness half of it is stated by the people who made the choice:

Rather than introducing another proprietary file, we chose a name and format that could work for anyone.

That sentence sits under "Why AGENTS.md?", in a passage about keeping AGENTS.md separate from README.md, and what it says was chosen is a name and a format that are not proprietary to one vendor. The site does not say it gave anything up in order to gain adoption, and it does not describe a trade at all. The trade is our reading of the result: an open format with no schema buys adoption by not constraining implementers. That is why 23 tools and 60k projects exist a year after the repository was created. A format with a strict schema and a conformance test would have fewer of both.

The cost of the trade lands on one person: whoever writes the file and reasonably believes that the sentence about precedence describes what their tool does. One page repeats it word for word, Copilot on GitHub, without saying how the nearest file comes to take precedence. Of the rest, two pages describe something approximate and four describe something else.

What to do about it, concretely

1. Find out which mechanism your tool uses, from its own documentation rather than from the format's site. The seven above are a starting list, not a complete one.
2. If your tool concatenates, put the important thing last. In Codex, merge order is position, so a rule that must survive belongs in the deeper file, not the root. Position is not the only lever the page gives you: an AGENTS.override.md suppresses the AGENTS.md beside it whatever the depth, and the page says to "place overrides as close to specialized work as possible".
3. Watch the budget in a monorepo. 32 KiB across a root file plus every parent directory is less generous than it sounds, and what falls off the end is the specific guidance, not the general. It is a default rather than a ceiling: Codex documents raising project_doc_max_bytes and ships a worked example at 65536.
4. Check the setting before you rely on a nested file in VS Code. Nesting is marked experimental, the page states no default for it, and with it on the nearest file does not win by rule: the agent decides which instructions to use based on the files being edited.
5. Remember what none of this is. All of it is text arriving in a context window. If you need something to not happen, no instruction file will do it, in any of these tools. That is a different mechanism and it is covered in CLAUDE.md, AGENTS.md and Cursor rules: why none of them enforce anything.

Sources

Every page below was fetched on 2026-08-31 and every quotation matched against it.

• AGENTS.md, the format's own site and FAQ.
• agentsmd/agents.md, the repository, created 2025-08-19.
• Custom instructions with AGENTS.md, Codex.
• Adding repository custom instructions for GitHub Copilot, Copilot on GitHub.
• Use custom instructions in VS Code, VS Code.
• Rules, Cursor.
• Rules, opencode.
• Specifying coding conventions, Aider.
• Provide context with GEMINI.md files, Gemini CLI.
• Extension reference, Gemini CLI, for the separate contextFileName field in an extension manifest.

Related

• CLAUDE.md, AGENTS.md and Cursor rules: why none of them enforce anything asks the prior question: whether an instruction file binds anything at all.
• What Is an MCP Memory Server? follows the same shape one layer down, where a protocol standardises the call and not the behaviour.

Mnemoverse is a shared memory layer for AI agents, connected over MCP. Setup is in getting started.

— Olga Timoshina · Last updated 2026-08-31