AGENTS.md: One File Now Rules Every AI Coding Agent Your Team Runs

Synergised Consulting Ltd

22 September 20266 min read

Title card: One File Now Rules Every AI Coding Agent Your Team Runs, with the AGENTS.md shared rulebook subtitle on the Synergised ground background

Last Updated: 22 September 2026

One plain Markdown file called AGENTS.md can now carry the same instructions for every major AI coding agent, because Claude Code started reading it on 18 September 2026. Write your build commands, code conventions and safety rules once, commit the file to the repository, and Codex, Cursor, Gemini CLI, GitHub Copilot and Claude Code all read the same rulebook. What changed, what it does not do, and where the catch sits, are all below.

What AGENTS.md is

An AGENTS.md file is a plain Markdown file in a code repository that tells an AI coding agent how to work on that project: how to build and test it, which conventions to follow, and what to leave alone. Its own documentation describes it as "a README for agents", and that is a fair summary. The format carries no required fields and no special syntax, which is precisely why it spread. The specification emerged from collaboration between OpenAI Codex, Amp, Google's Jules, Cursor and Factory, and OpenAI later contributed it to the Agentic AI Foundation under the Linux Foundation, giving it vendor-neutral governance. According to The Register, more than 60,000 open source projects had already implemented the format as of December 2025, and the specification's own site lists upwards of twenty tools that read it, including Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Jules, Windsurf, Aider and Zed. Agents also read the nearest file in the directory tree rather than only the root copy, so different parts of a large project can carry their own tailored instructions. OpenAI's own main repository, for example, ships 88 of them.

Why one file beat one file per tool

Before this month, a team running Claude Code alongside anything else had to keep two rulebooks. Claude Code looked for CLAUDE.md; Codex, Cursor and the rest looked for AGENTS.md. The files were similar but not identical, and teams kept them in sync with symlinks, import lines or sheer discipline. The Register's report of the change notes that specification separatism bought Anthropic nothing once Claude Code's popularity was established; the two-file maintenance burden simply fell on the teams using both tools. A single rulebook that every tool reads is less work and, more importantly, cannot drift out of sync with itself.

What actually changed on 18 September

Anthropic added AGENTS.md support to Claude Code in version 2.1.277. "Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md," according to Thariq Shihipar, a member of Anthropic's technical staff, in the post The Register reported. The behaviour can be changed in the tool's /config menu under Project instructions, so a team that prefers Claude Code to ignore the shared file can switch the fallback off.

Three limits worth knowing before you delete CLAUDE.md

First, this is a fallback, not a merge. If a CLAUDE.md exists, Claude Code reads it and ignores the AGENTS.md beside it. Independent coverage of the release confirms Claude Code does not combine the two files, so a repository that keeps both still needs the documented @AGENTS.md import line, which lets Claude-specific rules sit below the shared ones. Second, the feature is not yet available when Claude Code runs through Amazon Bedrock, Google Vertex AI or Microsoft Foundry, which is how many enterprises deploy it. InfoWorld quotes Claude Code's own documentation on why: the fallback depends on the session fetching feature flags from Anthropic, so a team on a third-party provider, or one that disabled telemetry, keeps needing its CLAUDE.md even though the file itself is local. Third, common format does not mean interchangeable behaviour. CLAUDE.md supports Claude-specific features that AGENTS.md was never designed to carry, so an instruction written for Codex may not behave the same way when Claude reads it.

What belongs in the file

The specification deliberately carries no required structure, but the working pattern that has spread across those 60,000 repositories is consistent. Its own documentation suggests a short project overview, the exact build and test commands, code style guidelines, testing instructions, and security requirements such as how authentication and data handling must be treated. Size discipline matters in both directions. Claude Code's own documentation advises keeping the file under 200 lines, because longer files consume more of the agent's context and reduce how well it follows the rules. Codex, for its part, caps the combined instructions it will read at 32 KiB by default. In practice: name the commands, state the conventions, list what the agent must never touch, and stop.

What a useful entry looks like

A worked entry makes the difference between a rulebook an agent follows and one it skims. "Run tests with pnpm test before committing" is actionable; "maintain good test coverage" is not, because the agent cannot tell what satisfies it. The same specificity applies to limits: naming which directories the agent must not modify, and which credentials it must never read, gives the tool a checkable boundary rather than an aspiration. Everything in the file should be something a new human contractor could also follow on their first day, which is a fair test of whether a rule is real.

The nested-file pattern large projects use

Agents do not read only the root copy. The specification's documented behaviour is that a tool walks from the file it is working on up to the repository root, and the nearest AGENTS.md in that path takes precedence. That is what makes the format work in large codebases: each package can ship its own tailored instructions while the root file carries the rules that apply everywhere. OpenAI's own main repository ships 88 of them, one per service or package. For a smaller team the practical consequence is simpler: you can give the agent one rule for the web frontend and a different one for the billing code, without either instruction contaminating the other. Where a CLAUDE.md exists in a subfolder, Claude Code's per-folder check means the same priority logic applies locally as it does at the root.

Why a versioned rulebook matters beyond the build

There is an aspect of this that reaches beyond developer convenience. A committed AGENTS.md is a dated, version-controlled record of the rules an autonomous tool was given. When something goes wrong, you can read the exact instructions the agent operated under, and when the rules change, the change carries an author and a timestamp. In discovery workshops, owners rarely arrive with a written statement of what their automation is and is not permitted to do; that list gets built in conversation, task by task. The pattern behind AGENTS.md is the same instinct applied to code: if a tool acts on your behalf, the standing orders belong in a file someone can inspect, not in anyone's head. A readable, versioned rulebook is also what makes agent behaviour auditable after the fact, which matters the moment more than one person, or more than one agent, works in the same repository.

Sources

Tier A sources used in this piece: