What Is AGENTS.md? Full Guide + Example

AGENTS.md is a plain markdown file, checked into the root of your repository, that coding agents read before they start working. Think of it as onboarding documentation for a very fast, very literal new teammate — one who joins your project fresh every single session and can't ask a hallway question.

Where it came from

AGENTS.md started in 2025 as OpenAI Codex's project instruction file, then went further than a single vendor's convention. The specification site, agents.md, now describes the format as having "emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory" — and the standard is stewarded by the Agentic AI Foundation under the Linux Foundation, not by any one company. That's the difference between AGENTS.md and a vendor-specific file like CLAUDE.md: it was built from the start to be read by more than one tool.

Which tools actually read it

Per the current list published on agents.md, these tools read AGENTS.md automatically: Codex (OpenAI), Jules (Google), Gemini CLI (Google), Cursor, Amp, Aider, goose, opencode, Zed, Warp, VS Code, Devin (Cognition), Windsurf (Cognition), UiPath Autopilot and Coded Agents, Junie (JetBrains), RooCode, Kilo Code, Phoenix, Semgrep, GitHub Copilot's coding agent, Ona, and Augment Code. That list keeps growing — check agents.md directly before you assume a tool you use is or isn't on it.

One notable absence: Claude Code reads CLAUDE.md, not AGENTS.md, on its own. If you run Claude Code alongside any of the tools above, see how the two files bridge instead of maintaining both by hand.

Why it exists

An agent dropped into your repo can read code, but code doesn't say why. It doesn't say that the payments module is frozen pending an audit, that you use pnpm and a stray npm install corrupts the lockfile, or that the failing test on main is known and being fixed by someone else. Every fact like that lives in your head — until you write it down. AGENTS.md is where it goes.

Without one, agents guess. With a good one, they follow your conventions, run your commands, and stop at the lines you drew — and a new human contributor gets the same benefit reading it on day one.

AGENTS.md vs. README

The two files serve different readers, and agents.md draws the line explicitly: README files are for humans — quick starts, project descriptions, contribution guidelines. AGENTS.md complements that by holding "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren't relevant to human contributors." In practice that means an AGENTS.md can say things a README shouldn't — internal-only routes, the exact flag order for a flaky test, which directory never gets touched by hand — without turning your project's front door into a wall of caveats.

What belongs in it

The files that work in practice cover seven kinds of content:

• Identity — who the agent is in this repo. A senior pair? A cautious reviewer? One sentence changes tone and risk appetite.
• Knowledge — facts the code can't reveal: what the project is, architecture boundaries, known traps, environment quirks.
• Conventions — the style contract: TypeScript strictness, naming, commit format, framework idioms.
• Workflow — how work happens: plan before coding, test-first, verify before declaring done.
• Tools — the blessed commands: dev server, tests, lint, package manager. Agents guess script names otherwise.
• Constraints — the hard lines: never commit secrets, never edit migrations, never add dependencies unasked.
• Examples — one good commit message or component skeleton pins a format better than a page of rules.

Writing all seven from scratch is the part most people stall on; the Groundrules builder starts from curated blocks for each of these seven types instead of a blank file.

Where it lives, and what wins in a monorepo

Repo root, named AGENTS.md. For monorepos, agents.md's own guidance is simple: "agents automatically read the nearest file in the directory tree, so the closest one takes precedence." A root file carries the org-wide facts — package manager, top-level layout, universal constraints — and each package or app gets its own AGENTS.md for what's true only there. This isn't a theoretical pattern at small scale, either: the OpenAI Codex repository itself ships dozens of nested AGENTS.md files, one per subproject, each overriding the root file for its own directory.

A minimal version of that split looks like this:

An agent working inside apps/api reads apps/api/AGENTS.md for anything specific to that service, and falls back to the root file for what's shared — it doesn't need both files to repeat the package manager or the lint command.

A complete example — TypeScript service

agents.md's own guidance suggests sections like a project overview, build and test commands, code style, testing instructions, and security considerations. Here's a full file built around exactly those, for a small order-processing API:

Notice what's absent: no directory listing, no explanation of what Fastify or Prisma are, nothing a git clone and five minutes of reading wouldn't reveal. Every line answers a question an agent would otherwise have to guess at, or get wrong once before learning.

Living alongside CLAUDE.md, .cursor/rules, and GEMINI.md

Most repos don't get to pick one file and be done — different teammates run different tools. Claude Code is the clearest case: it reads CLAUDE.md and nothing else, so the standard fix is a one-line CLAUDE.md that imports AGENTS.md, plus any Claude-specific additions below it. Cursor and Gemini CLI both now appear on agents.md's own list of AGENTS.md readers, which means projects that used to maintain a separate .cursor/rules directory or GEMINI.md alongside AGENTS.md can often fold them into one file — check your installed version's docs for how it prioritizes an AGENTS.md against its own legacy format if you keep both around. The failure mode to avoid either way is three files that say three slightly different things; pick one source of truth and bridge or generate the rest from it.

A practical rule of thumb: write AGENTS.md first, since it's the one more tools can read without any bridging at all, then layer on a one-line CLAUDE.md import only for the specific gap Claude Code leaves. That keeps the edit-and-maintain surface at one real file no matter how many tools your team ends up running against the same repo.

How long should it be?

agents.md itself gives no line-count or file-size limit — it's deliberately just "standard Markdown," open-ended. The practical constraint is the one every reader of the file already lives with: whichever of the tools above you're running loads AGENTS.md into context on every session, so every line is paid for repeatedly, on every tool, for every teammate who runs one. If you also maintain a CLAUDE.md, Anthropic's published guidance for that file — under 200 lines — is a reasonable ceiling to borrow for AGENTS.md too, since most repos end up keeping the two in sync. Past that, split what's package-specific into a nested AGENTS.md closer to the code, the same way you'd split an oversized README into linked docs rather than growing one file forever.

What to leave out

Everything an agent can discover by reading code: file listings, restated function docs, framework tutorials. Every unnecessary line costs tokens and attention on every request. The test for each line: would the agent plausibly get this wrong without being told? If not, cut it.