AGENTS.md
Published October 10, 2026 · by the AQ team
AGENTS.md is a plain Markdown file, committed to a repository, that gives AI coding agents the project instructions a human would get from onboarding: how to build and test the code, what the conventions are, and what never to touch. The format's own site calls it "a README for agents," and that is the right mental model: a dedicated, predictable place for the context agents need but that would clutter a human-facing README. As of October 2026 it is read natively by Codex, Claude Code, Cursor, OpenCode, and GitHub Copilot's coding agent, among many others, and the format's site counts more than 60,000 open-source repositories carrying one. There is no required structure beyond being Markdown: no frontmatter, no schema, just headings and prose the agent reads at the start of a session.
Where the format came from
AGENTS.md started in August 2025 as OpenAI's convention for Codex, developed with input from other agent vendors (the format's site credits collaboration across Codex, Amp, Jules, Cursor, and Factory). The explicit goal was avoiding a proprietary instruction file per vendor, which was already happening: Claude Code had CLAUDE.md, Gemini CLI had GEMINI.md, Cursor had its rules directory. On December 9, 2025, OpenAI donated the format to the Agentic AI Foundation, a Linux Foundation project, alongside Anthropic's Model Context Protocol and Block's goose, so no single company controls its direction. Adoption did the rest: the holdouts added native support one by one, and today a single committed AGENTS.md is the closest thing the ecosystem has to a universal agent configuration surface.
Which coding agents read AGENTS.md, as of October 2026
Each row below is verified on the vendor's own documentation as of October 2026. The differences that matter in practice are where the file is discovered and how several files combine.
| Tool | How it reads AGENTS.md |
|---|---|
| Codex | Natively, and most completely: a global file in the Codex home directory, then one file per directory from the repository root down to the working directory, concatenated in that order so the closest file wins. An AGENTS.override.md replaces the regular file at its level, empty files are skipped, and the combined chain is capped at 32 KiB by default |
| Claude Code | Natively since v2.1.277 (September 2026): when a project has no CLAUDE.md or CLAUDE.local.md in the working directory or above it, Claude Code loads AGENTS.md as its project instructions, including subdirectory files as it works there. When both files exist, CLAUDE.md wins by default; a personal "Project instructions" setting can load both |
| Cursor | Natively, at the repository root and in subdirectories; nested files combine with parent directories, with the more specific instructions taking precedence. Positioned in Cursor's docs as the simple alternative to .cursor/rules |
| OpenCode | Natively: a project-root AGENTS.md plus a global personal one, created or updated by its /init command, with CLAUDE.md read as a fallback when no AGENTS.md exists and extra instruction files listed in opencode.json |
| GitHub Copilot coding agent | Natively: one or more AGENTS.md files stored anywhere in the repository, with the nearest file in the directory tree taking precedence; a root CLAUDE.md or GEMINI.md is accepted as an alternative |
| Gemini CLI | Only by configuration: the default context file is GEMINI.md, and AGENTS.md loads when the context file name setting lists it |
The format's site lists dozens more supporting agents, including Google's Jules, Devin, Windsurf, Zed, Warp, Aider, goose, Amp, Factory, JetBrains Junie, and Roo Code. The practical summary: if your team runs more than one agent against a repository, AGENTS.md is the one instruction file they can all be expected to read, and keeping AGENTS.md and CLAUDE.md in sync covers the one remaining wrinkle (a repository that still carries both).
What belongs in AGENTS.md, and what does not
The file is loaded into the agent's context at the start of every session, unconditionally, which is both its power and its budget. Everything in it costs context on every task, so the test for each line is: does every session need this? The format's site and the major vendors converge on the same inventory:
- Build, test, and run commands, exactly as they should be typed, including the package manager to prefer. This is the highest-value content: an agent that guesses the test command wrong burns a whole loop discovering it.
- Project layout in a few lines: where the code lives, where tests live, what the big directories mean.
- Conventions and rules: code style the linter does not enforce, naming, commit and pull request expectations, "always do X before Y."
- Security gotchas and boundaries: files the agent must never edit, data it must never log, generated directories it should not touch by hand.
Three things do not belong. Secrets never go in the file: it is committed plaintext that gets pasted into model requests, so reference environment variables instead. Task-specific procedures (the deploy runbook, the release-notes format, the migration review checklist) belong in agent skills, which load on demand and cost nothing until used; a procedure in AGENTS.md taxes every session, relevant or not. And long reference documents belong behind links or imports, not inline: Codex caps the combined instruction chain at 32 KiB by default, and every vendor's guidance says to keep the file short and specific. For a monorepo, the spec's answer is nesting: put a root AGENTS.md with the universal facts and a smaller one in each package, since agents read the nearest file and the closest one takes precedence (OpenAI's main repository carries 88 of them, per the format's site). One more boundary worth knowing: your explicit chat prompt always overrides the file, so AGENTS.md sets defaults, not law, and anything that must be enforced rather than suggested belongs in a hook or CI.
How AGENTS.md relates to CLAUDE.md, skills, and memory
Four mechanisms carry knowledge into an agent session, and teams mix them up constantly. One sentence each: CLAUDE.md is Claude Code's own instruction file, same job as AGENTS.md, read first when both exist; an agent skill is a folder of instructions loaded only when a task matches its description; auto memory is notes the agent writes for itself across sessions; and AGENTS.md is the cross-vendor instruction file loaded every session.
| Topic | Who writes it | When it loads | Scope |
|---|---|---|---|
| AGENTS.md | The team | Every session, unconditionally | Cross-vendor, travels with the repo |
| CLAUDE.md | The team | Every session, Claude Code first (others read it as a fallback) | Claude Code's native file |
| Skills (SKILL.md) | The team | On demand, when a task matches | Cross-vendor since late 2025 |
| Auto memory | The agent itself | Every session | Per machine and per person |
The division of labor that falls out: facts every task needs go in AGENTS.md, procedures only some tasks need go in skills, and the agent's own accumulated observations stay in memory, which does not travel between machines or teammates. The full tour of what persists where, including each CLI's memory quirks, is in coding agent memory explained. As for CLAUDE.md: since Claude Code reads AGENTS.md natively when no CLAUDE.md exists, the cleanest new setup is one AGENTS.md and no CLAUDE.md at all, and the sync guide covers the bridges (an import or symlink) that older setups and mixed-version teams still need.
Where AQ fits
AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. AQ runs the stock CLIs in persistent tmux sessions on your team's VM, so AGENTS.md behaves exactly as it does on a laptop: every workspace is an isolated git worktree of your repository on a fresh branch, which means each agent reads the committed AGENTS.md as it exists on that branch, with no per-machine copy to go stale. That matters most in exactly the situation AGENTS.md was designed for, several different CLIs against one repository: a teammate can open the same workspace, watch the same live session, and see in the transcript whether the agent actually followed the file, instead of reconstructing it from a finished diff. Sessions survive a closed laptop and resume from any device, each engineer signs in with their own Claude or OpenAI account, and agents commit, push, and open PRs that AQ tracks per workspace.
Frequently asked questions
What is the difference between AGENTS.md and CLAUDE.md?
Same job, different origin. CLAUDE.md is Claude Code's native instruction file; AGENTS.md is the cross-vendor standard that started with Codex and is now stewarded by a Linux Foundation project. As of October 2026 the practical difference is precedence: Claude Code reads AGENTS.md natively when a project has no CLAUDE.md, but reads only CLAUDE.md by default when both exist, while several other tools (OpenCode, Cursor's CLI, GitHub Copilot) read CLAUDE.md as a fallback or alternative. A new repository can simply keep one AGENTS.md and no CLAUDE.md.
Does Claude Code read AGENTS.md?
Yes, since version 2.1.277 (September 2026). In a project with no CLAUDE.md or CLAUDE.local.md in the working directory or above it, Claude Code loads AGENTS.md as its project instructions automatically, including subdirectory files as it works in them. When a CLAUDE.md exists too, Claude Code reads only the CLAUDE.md unless a personal Project instructions setting says to load both. It does not read AGENTS.local.md, AGENTS.override.md, or files under a .agents/ directory.
How do nested AGENTS.md files work in a monorepo?
Each package or subproject can carry its own AGENTS.md, and the file nearest the code being edited takes precedence. Codex concatenates the chain from the repository root down so closer files override earlier ones, Cursor combines nested files with parents with the more specific winning, and GitHub Copilot's coding agent applies the nearest file in the directory tree. Keep universal facts in the root file and package-specific commands in the package's own file.
What should I put in AGENTS.md, and how long should it be?
Build and test commands as they should be typed, a short project layout, the conventions a linter cannot enforce, and hard boundaries (files never to edit, data never to log). Keep it short: the whole file loads into context every session, and Codex caps the combined instruction chain at 32 KiB by default. Move task-specific procedures into agent skills, which load on demand, and never put secrets in the file; it is committed plaintext that reaches model requests.
Is AGENTS.md only for OpenAI Codex?
No. It began as OpenAI's convention for Codex in August 2025, but OpenAI donated it to the Agentic AI Foundation under the Linux Foundation in December 2025, and as of October 2026 it is read natively by Codex, Claude Code, Cursor, OpenCode, and GitHub Copilot's coding agent, with the format's site listing dozens more supporting tools including Jules, Devin, Windsurf, Zed, Warp, and Aider. Gemini CLI is the notable tool that still defaults to its own GEMINI.md and reads AGENTS.md only through a settings change.
Does an agent always follow what AGENTS.md says?
No. The file is context, not enforced configuration: models follow specific, concise instructions far more reliably than long or vague ones, and your explicit chat prompt overrides the file by design. Anything that must never happen regardless of what the model decides belongs in an enforcement layer instead: a harness hook that blocks the action, a permission setting, or CI. Treat AGENTS.md as the default briefing, and hooks and CI as the guardrails.