How to write an AGENTS.md file, and what to leave out of it

An AGENTS.md file has no schema, no required sections and no validator, which is why every guide to writing one gives you the same invented template and no way to judge it. The useful rule is narrower than a template: put in it only what has to be true for every session started in that directory, and nothing else. Everything else your team knows still needs a home, and the second half of this post is about where, because that half is the problem Baalda is built for.

What actually goes in an AGENTS.md file?

The format is the easy part. The agents.md site, which is the closest thing the convention has to a spec, answers the format question with one line: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." No frontmatter, no schema, no required keys. As of 9 October 2026 the site says the convention is "used by over 60k open-source projects" and lists 23 tools that read the file, among them Codex, Cursor, Gemini CLI, Zed, Devin, Jules, Aider, goose, Windsurf and GitHub Copilot's coding agent.

So the real question is not format, it is inclusion. Here is a test that decides it, because it is the one the loaders actually enforce: does this sentence stop being true if someone checks out a different directory? If it does, it belongs in the file. If it does not, you are about to maintain N copies of it.

That test keeps a short list in:

• The build, test and lint commands, written out, including the flags your CI uses.
• Project layout, the parts that are not obvious from the tree.
• Conventions the agent gets wrong on its own: the test framework you actually use, the import style, the thing that looks dead but is not.
• Hard prohibitions for this codebase. Do not edit the generated client, do not add a migration without X.

And it keeps a much longer list out: why the architecture is the way it is, the decision you reversed in March, who has to be asked before a schema changes, how deploys actually go, what the client wants, which service is being retired next quarter. All of it is real, all of it is the sort of thing you would tell a new engineer in their first week, and none of it is a property of the directory the agent is standing in.

Anthropic's Claude Code memory documentation draws the same line for its own instruction file, and it is worth reading because it is unusually specific: "Keep it to facts Claude should hold in every session: build commands, conventions, project layout, 'always do X' rules. If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead."

Why is a file nobody enforces still a budget?

Because it is loaded unconditionally, for everyone, on every run, and two of the loaders put a ceiling on it in bytes.

Start with what "loaded" means. Claude Code's documentation states that instruction files and auto memory are "both loaded at the start of every conversation", and that auto memory specifically is capped at the "first 200 lines or 25KB". OpenAI's Codex documentation is more explicit about the arithmetic, because Codex does not read one file, it reads all of them: "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." Then the ceiling: "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)."

Read that last sentence carefully, because the failure mode is quiet. Codex does not truncate the file you cared about and warn you. It stops adding files. In a monorepo where the root AGENTS.md has grown to 30 KiB, the package-level file that holds the rules for the code you are actually editing can simply never load, and nothing in the session says so.

That is the budget, and the thing that makes it a team problem rather than a personal one is who pays it. A paragraph you add to the root file is read by every teammate's agent, in every session, in every package, whether or not the session has anything to do with the paragraph. It is the only file in your repository with that property. A long AGENTS.md is not a thorough AGENTS.md, it is a tax, and Anthropic's docs put the quality cost plainly too: "The more specific and concise your instructions, the more consistently Claude follows them."

So you have a file with a hard budget, and a body of team knowledge with no natural size limit. The file is not where the second thing goes.

Where does the knowledge that fails the test go?

Somewhere the agent fetches from, rather than somewhere it loads from. That is the whole distinction, and it is the one the instruction-file conversation keeps skipping.

Baalda is a team second brain: plain markdown files on your own disk, several people editing the same notes at once in real time, and an AI reading and writing those same files over MCP. The piece that matters here is the read path, because it is a pull rather than a push. The agent registers one endpoint:

claude mcp add --transport http baalda https://api.baalda.com/api/mcp \
  --header "Authorization: Bearer mcp_your_token_here"

For a local vault that address is http://localhost:3010/api/mcp, and self-hosted it is your own server URL plus /api/mcp. What the agent gets is a set of tools, not a block of text prepended to its context. search_notes takes a vault and a query and returns ranked hits, k defaulting to 10 and capped at 50, across notes and the extracted text of the files sitting beside them, docx, xlsx, pdf, csv and code, each hit tagged note or file. read_note then pulls one note by its docId and returns the markdown plus a revision.

The cost model is the opposite of the instruction file's. A note about last March's reversed decision costs nothing in the sessions that never ask about it, and is available in full in the one session that does. There is no 32 KiB ceiling to ration, because nothing is being concatenated into every prompt. You are no longer choosing between "every agent on the team carries this sentence forever" and "nobody writes it down".

Two further differences follow from the vault being a vault and not a checkout. It is addressed by vault and folder rather than by distance from the current directory, so the same note is reachable from any repository on the machine, which is the answer to the duplication the inclusion test warns you about. And access is set per folder and per file, with an MCP token scoped to one person within one vault, so the deploy runbook can be readable by everyone and writable by the platform team. A file in git has exactly one audience: everyone with access to the repository, all of it. Mods made Claude Code's instruction loader replaceable works through that audience question in detail, and a second brain over MCP covers the endpoint itself.

Can you nest AGENTS.md files, and which one wins?

Yes, and the three loaders disagree about the answer, which is the part every guide gets wrong by quoting only one of them.

agents.md describes nesting as a nearest-file rule: "Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence." The same page notes that "the main OpenAI repo has 88 AGENTS.md files", so this is not a hypothetical pattern.

Codex, which is OpenAI's own agent, does not do nearest-wins. It concatenates, as quoted above, every file from the project root down to your working directory, after reading a global file in ~/.codex first. Nothing is replaced; later files override earlier ones only in the loose sense that they come later in the prompt. Codex also checks for an AGENTS.override.md in each directory before the plain AGENTS.md.

Claude Code is different again, and this is the one that surprises people. It reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it, and its documentation gives the three cases directly:

So adding a personal, gitignored CLAUDE.local.md silently stops Claude Code reading the team's AGENTS.md for you, and only for you. Anthropic's docs flag this one explicitly. Reading AGENTS.md directly needs Claude Code v2.1.277 or later, and the setting that changes the behaviour is Project instructions under /config, where claude-md-and-agents-md loads both. If you want one file every tool shares without depending on any of that, the documented move is an @AGENTS.md import at the top of a CLAUDE.md, or a symlink.

The practical consequence for writing the files: put rules in the deepest directory they are true of, keep the root file small enough that a 32 KiB ceiling is never near, and do not assume a package-level file has been read just because it exists.

What should stay in AGENTS.md no matter what?

Three things, and the first is the honest limit of everything above.

A tool call is not a guarantee. This is the real cost of moving knowledge into a vault. An instruction file is in the model's context before it does anything; a vault note is read only if the model decides to search for it. Claude Code's documentation makes the same point about its own instruction files, that they are "context, not enforced configuration", but the gap is wider for a tool call, because the model has to choose to make it. Anything that must hold on every run with no chance of being missed, the build command, the two conventions it keeps breaking, the hard prohibition, stays in the file. That is not a limitation to work around. It is what the file is for.

A vault needs a server the agent can reach. For a local vault that is your own machine, which is fine in a terminal and no use to a cloud session running while your laptop is shut. Repository files have no such problem; they are already wherever the checkout is. A managed or self-hosted instance closes the gap, but it is a thing you have to run, and for a solo developer with one repository it is plainly more machinery than the problem deserves. One AGENTS.md is the right answer there, and Claude Code's second brain is a folder, not an integration covers the case where the notes are already on your disk and no server is needed at all.

Nothing prunes itself. A folder of conventions that nobody maintains becomes the stale wiki your company already abandoned once, except now an agent reads it faithfully and acts on last year's rule. Moving knowledge out of a 32 KiB budget removes the pressure to delete things, and that pressure was doing real work. Whatever you move out, somebody still owns.

The short version of all of it: AGENTS.md is a small, expensive, always-on file, so write it as though every line is charged to every teammate, because it is. What it cannot hold is not a gap in the convention. It is a different problem, and it needs somewhere the agent can go and look.