Rohit Ghumare · August 11, 2026 · 11 min read

The AGENTS.md Practices Nobody Uses

A year ago AGENTS.md was a convention one lab used to brief its coding agent. Now it is a Linux Foundation standard, read by twenty-odd agents, living in over seven hundred thousand files. It got a governing board before it got a spec. And in that speed, the practices that actually make the file work stayed niche: the token budget it spends on every request, the nearest-file rule almost nobody nests for, the resolution order that silently shadows your rules, the eval where it beats the alternative outright, and its quiet second life as an attack surface. Here is what the standard does not tell you.

The standard arrived before the spec

On December 9, 2025, the Linux Foundation announced the Agentic AI Foundation, and OpenAI donated AGENTS.md into it alongside Anthropic's Model Context Protocol and Block's goose. That is unusual company for a Markdown convention. The foundation lists AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, and OpenAI as platinum members, and gave AGENTS.md a governing board seat and a health dashboard: 303 contributors, 122 contributing organizations, 24,000 stars.

What it did not give AGENTS.md is a specification. The repository holds a README and an FAQ and nothing that reads like a standard; an open issue asks for a formal spec, another proposes an "AGENTS.md v1.1" to finally codify discovery and precedence, and a pull request from August proposes adding the governance files the project does not yet have. The rules that matter, then, are not written in one place. They are scattered across each tool's own documentation, and they disagree in ways that will quietly cost you. Start with the one that surprises people most.

Every tool reads it differently, and one of them shadows you

"Twenty tools read AGENTS.md" is true and misleading. They read it through different resolution orders, and if you assume the file you wrote is the file the agent loaded, you are sometimes wrong. Pick a tool and follow what it actually does when it looks for instructions.

Three of these are worth stating plainly. Zed puts AGENTS.md seventh in a first-match list, behind .rules, .cursorrules, .windsurfrules, and more, so a stray .cursorrules a teammate committed two years ago silently wins and your AGENTS.md is never read. Codex reads it, and caps it: a 32 KiB default limit on the combined instruction bytes, so an oversized file gets truncated, not honored. And Claude Code does not read AGENTS.md at all. As of August 2026 its docs say it reads CLAUDE.md, full stop; the widely repeated belief that it falls back to AGENTS.md is, in the words of one practitioner, "false. no import, no symlink = it's ignored entirely." The fix is one line, and it is the single most useful thing in this essay if you run Claude Code.

The bridge, and the flat-file gap it papers over

The consensus pattern that emerged over 2026 is not "pick AGENTS.md or CLAUDE.md." It is: make AGENTS.md the source of truth every tool reads, and make CLAUDE.md a one-line shim that imports it.

# CLAUDE.md
@AGENTS.md

# Claude-only instructions below this line

Claude Code expands the @ import at session start and loads the shared file as if it were written inline; run /context and you will see both files listed under Memory. A symlink (ln -s AGENTS.md CLAUDE.md) does the same on systems that support it. Either way you keep one file, not two copies that drift.

It is worth being honest about why Anthropic held out, because it is not stubbornness. CLAUDE.md does things the AGENTS.md spec does not describe: @-imports that pull in other files, path-scoped memory where a backend directory's rules only load when you are in the backend, and separate project-versus-user memory layers. AGENTS.md, per its own FAQ, is one flat Markdown file with no required structure. The bridge gives you the cross-tool reach of the standard and keeps the richer machinery where a tool offers it. That is the actual state of the art, and it is a paragraph most "AGENTS.md vs CLAUDE.md" posts never reach.

The number nobody budgets: it costs tokens on every request

Here is the practice that separates files that help from files that quietly hurt. The root AGENTS.md is loaded into context on every single request, whether or not its contents are relevant to the task. It is not retrieved when needed; it is always resident. So every line you add is a line the model reads before it starts thinking about your actual problem, and a line of the context window it cannot use for the code.

That reframes the whole exercise. The goal is not a complete file; it is a file that contains only what applies to every task, with breadcrumbs to the rest. The empirical anchors are specific: frontier thinking models follow roughly 150 to 200 instructions with consistency, and smaller or non-thinking models fewer; Codex caps the bytes at 32 KiB; GitHub's guidance is "no longer than two pages"; Ona recommends under 300 lines, ideally under 60. A study of 2,303 real context files found their median readability score was written for machines, not humans, which is correct, but also that security and performance guidance each appeared in only 14.5 percent of them. Most files are too long about the wrong things.

The instrument that makes the budget spendable is nesting, and it is the most underused feature of the format. The rule every native tool implements is nearest-file-wins: the agent reads the AGENTS.md closest to the file it is editing, and that one takes precedence. So the root holds cross-cutting rules, and each package holds its own specifics, loaded only when work happens there. The reference implementation is not a blog claim: the main OpenAI repo carries 88 AGENTS.md files. Almost every repo I see carries one giant root file instead.

The evals that should end the debate

Most AGENTS.md advocacy is vibes. Two independent measurements are not, and they come from opposite ends: a framework vendor testing pass rate, and the foundation itself testing cost. Toggle between them.

They measured different things and agreed. Vercel tested pass rate on Next.js 16 tasks outside the training cutoff and found the delivery matters more than the content: passive and always-in-context beat trigger-gated retrieval, because a Skill only helps when its trigger fires and on unfamiliar tasks it often does not, while an AGENTS.md index is simply always there. The Agentic AI Foundation, on Copilot CLI with a mere 12-line file, measured the other axis, cost, and found double-digit drops in wall-clock time, credits, and diff size on an ambiguous task, with the caveat that gives its post its title: a single run "can point the wrong direction," so they took medians over five. Two labs, two tools, two metrics, one direction. That is a stronger claim than either alone, and it is why the uncommon practice worth copying is Vercel's: they generate the index with a codemod (npx @next/codemod agents-md) and regenerate it on version bumps, so the file is a build artifact kept in sync by CI, not a document that rots. Measure over runs, and let CI keep the file honest.

Practices from the people who actually measured

Beyond the budget, a handful of concrete patterns show up repeatedly in the writeups from teams that instrumented this, and rarely in the files themselves.

• The retrospective loop, blessed by the vendors. OpenAI's own guidance: when Codex repeats an error, ask it for a retrospective and have it update AGENTS.md. Amp documents the same, phrased as "update AGENTS.md based on what I told you in this thread." The file is a place scars accrete, not a spec you write once.
• Commands with flags and purpose, not prose. GitHub's analysis of over 2,500 repositories found the files that worked put exact commands early, with full flags and a parenthetical purpose, and that "one real code snippet beats three paragraphs." Prose is the least effective thing you can put in an AGENTS.md.
• File-scoped commands over full builds. The builder.io pattern: tell the agent to lint and type-check the single file it touched (eslint --fix <file>), and to run full builds only when asked. It keeps the agent fast and stops it burning a minute compiling the world after a one-line change.
• A permissions boundary written into the file. A short section naming what the agent may do freely, what it must ask before doing, and what it must never do. "Never commit secrets" is the most common line in the corpus. This is guidance, not enforcement, and the distinction is the next section.
• Codex reads leaf files last. A wire-level detail from the Codex prompting guide: it injects each AGENTS.md as a separate message, root first, leaf last, so the file closest to your code literally gets the final word before your prompt. Nesting is not just scoping; it is ordering.

The chapter the standard skips: it is an attack surface

An AGENTS.md is a file the agent reads and treats as standing instructions, with no human in the loop at read time. That is a feature until the file arrives from somewhere you did not write. It gets almost no coverage in practitioner posts, and it is the most important thing on this page.

Two things make this real rather than theoretical. NVIDIA built a working proof of concept: a malicious dependency that detects it is running under Codex and writes an AGENTS.md "claiming supremacy over user prompts." Pillar Security demonstrated the invisible-Unicode variant, hiding directives in rules files where a human reviewer sees nothing. And the tooling has not caught up: Snyk's agent scanner has no issue code for a malicious repository instruction file yet. The defenses are unglamorous and worth putting in your own workflow: write-protect AGENTS.md so a process cannot rewrite it mid-session, pin your dependencies, lint instruction files for non-ASCII characters, and alert on any modification to the file. Treat AGENTS.md with the same suspicion you give a shell script that a package wants to run.

Where it is going, and what to do Monday

The open issues tell you what is unsettled: frontmatter for glob-scoped and conditional rules, standardized imports, a canonical global location (today it is ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.config/AGENTS.md, and more, all different), and a real spec. The direction of travel is toward the machinery CLAUDE.md already has, arriving in the standard one issue at a time. Meanwhile the file keeps winning by adoption, not decree: Emacs added an official one, and Codex Code Review now reads repository rules from it, which turns the file into review policy and changes what belongs in it.

If you do five things after reading this: put the root file on a token budget and nest the rest per package; if you run Claude Code, add the @AGENTS.md import today; check what your tool's resolution order actually loads before trusting it; generate the file from CI where you can, so it stays true; and write-protect it, because it is now something an attacker would like to write. The standard is real. The practices are still yours to adopt.