AGENTS.md

What Is AGENTS.md?

AGENTS.md is a plain markdown file placed in a repository to tell AI coding agents how the project works: build and test commands, code conventions, architecture notes, and rules to follow. It is a vendor-neutral convention, described as a README for agents, and it is read automatically by most coding agents as of 2026.

Key Takeaways

• One file serves many tools. The point of AGENTS.md is that Codex, Cursor, Gemini CLI, Jules, and dozens of other agents all read the same instructions instead of each demanding its own config file.
• It carries what a README leaves out. Humans get context from onboarding and team chat; agents need exact commands, conventions, and prohibitions written down.
• Placement is hierarchical. A root AGENTS.md covers the repo, and files in subdirectories override it for their subtree, which suits monorepos.
• It is plain markdown with no required schema. The convention standardizes the filename and location, and each team decides the contents.
• Quality shows up directly in agent output. Vague or stale instructions produce agents that guess, and agents that guess produce rework.

How It Works

When a coding agent starts a session in a repository, it looks for AGENTS.md in the project root and loads the contents into its context before doing any work, the same way a new contributor might read the README first. The file then shapes every decision the agent makes: which package manager to invoke, how to run the test suite, what naming conventions to follow, which directories to leave alone. In monorepos, agents apply the nearest AGENTS.md up the directory tree from the files being edited, so a Python service and a TypeScript frontend can each carry their own rules while sharing repo-wide defaults. OpenAI takes this further than most: its own monorepo maintains 88 AGENTS.md files, and the official agents.md site lists roughly 25 supporting agents and tools, including Codex, Gemini CLI, Cursor, and GitHub Copilot's coding agent [1].

The format emerged in 2025 from an OpenAI-led effort to consolidate the pile of per-tool instruction files that had accumulated, and adoption spread quickly because the cost is one markdown file and the payoff applies to every agent that touches the repo. There is deliberately no schema. Effective files tend to converge on the same sections anyway: setup and build commands, test commands with the expectation that agents run them, code style rules, commit and PR conventions, and security boundaries such as files never to modify. A 2025 empirical study of 2,303 agent context files across 1,925 repositories confirmed the pattern, finding test procedures in 75.9% of files, implementation details in 70.8%, and architecture in 68.1%, while security guidance appeared in only 14.8% [2]. Some tools that predate the convention keep their own filename, most visibly Claude Code's CLAUDE.md, and teams commonly maintain one canonical file with the other as a pointer or symlink.

The file matters because it is context engineering at its cheapest. Instructions in AGENTS.md reach the agent on every session with zero per-task effort, which makes it the natural home for anything you find yourself repeating in prompts.

Example

A team notices their coding agent keeps using npm in a pnpm workspace, breaking the lockfile, and writing tests in the wrong directory. They add an AGENTS.md at the root: use pnpm only, run pnpm test --filter <package> before finishing any task, tests live next to source as .spec.ts files, never edit generated files under src/gen/, and all API changes require updating the OpenAPI spec first. The next session, the same agent scaffolds a feature correctly on the first pass. The instructions did not make the model smarter; they removed every place it previously had to guess.

What People Get Wrong

The common failure is writing AGENTS.md once and letting it rot. Agents follow the file literally, so an outdated build command or a rule referencing a deleted directory actively misleads them, which is worse than saying nothing. Treat the file like code: update it in the same pull request that changes the workflow it describes, and prune rules that no longer apply. A short, current file beats a long, stale one every time.

FAQ

Is AGENTS.md an official standard? It is an open convention with a public spec-style site and multi-vendor backing rather than a formal standards-body specification. In practice the ecosystem treats it as the default: the official agents.md site counts more than 60,000 open-source projects on GitHub using the format [3].

How is AGENTS.md different from a README? Audience and precision. A README sells and orients: what the project is, why it exists, how to get started. AGENTS.md instructs an operator with no institutional knowledge and total obedience, so it favors exact commands and hard rules over narrative.

What should I put in it first? Start with whatever you have already told an agent twice: the correct test command, the package manager, the one directory it must not touch. Add conventions as violations appear. Ten accurate lines deliver most of the value.

Sources

1. agents.md. "OpenAI monorepo AGENTS.md count and list of supporting agents and tools." https://agents.md/. Accessed August 2026.
2. arXiv. "Agent READMEs: An Empirical Study of Context Files for Agentic Coding, section frequency across 2,303 context files." https://arxiv.org/abs/2511.12884. Accessed August 2026.
3. agents.md. "Count of open-source projects using the AGENTS.md format." https://agents.md/. Accessed August 2026.