AGENTS.md Explained: the README for AI Coding Agents

AGENTS.md is a Markdown file you put in your repo to tell AI coding agents how to work in it — build commands, code style, test instructions, PR rules. Its own site calls it "a simple, open format for guiding coding agents": think of it as a README for agents. It is an emerging convention, not a ratified standard — it came out of a collaboration across OpenAI Codex, Amp, Google Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. This guide covers what goes in it, which tools actually read it (Codex, Cursor, Jules and GitHub Copilot's coding agent do; Claude Code natively does not), and how it differs from README and CLAUDE.md — plus a section-by-section template and a support table.

What AGENTS.md is

AGENTS.md is a Markdown file in your repo that tells AI coding agents how to work in it — a README written for agents instead of humans. The official site describes it as "a simple, open format for guiding coding agents": a dedicated, predictable place to put the context and instructions an agent needs — build commands, code style, test steps, PR rules — so it does not have to guess them from your source tree.

Be precise about its status: this is an emerging convention, not a ratified specification. By its own account it "emerged from collaborative efforts across the AI software development ecosystem, including OpenAI Codex, Amp, Jules from Google, Cursor, and Factory" — multiple vendors converging, not a standards body handing down a spec. It is "now stewarded by the Agentic AI Foundation under the Linux Foundation." The site self-reports that AGENTS.md is "used by over 60k open-source projects" (a GitHub code-search count, so treat it as a self-reported site metric rather than an audited figure — older cached pages still cite roughly 20k).

Why a separate file from README

Because README is for people and AGENTS.md is for agents — mixing the two makes both worse. A README answers a human's questions: what is this project, how do I install it, how do I contribute. An agent needs something narrower and more literal: the exact command to build, the exact command to run tests, the lint rule that will fail CI, the branch-naming rule that will bounce a PR.

Splitting them keeps the README concise for humans while giving agents a single file they can rely on. The agents.md site frames the file as deliberately "README-like" for exactly this reason — familiar format, different audience. If you already keep a good CONTRIBUTING guide, AGENTS.md is that guide rewritten as direct, imperative instructions an agent can execute without interpretation.

What goes in it

There are no required fields — it is freeform Markdown — but a handful of sections recur. The convention imposes no schema; you write whatever headings help an agent. Commonly cited sections, and what each is for:

The canonical example file in the project's own repo uses headings like "Dev environment tips," "Testing instructions" and "PR instructions" — a good signal of what real usage looks like, but a suggestion, not a required layout.

A section-by-section template

Here is a starter you can drop in your repo root and trim. Every heading below is optional; keep the ones that earn their place and delete the rest. Nothing here is a mandated field — it mirrors the sections the project's own example uses.

# AGENTS.md

## Project overview
Short description. Monorepo: `web/` (Next.js), `server/` (FastAPI),
shared types in `packages/schema/`.

## Dev environment
- Install: `pnpm install`
- Run everything: `pnpm dev`
- One package: `pnpm --filter web dev`

## Testing instructions
- Run before you finish: `pnpm test && pnpm lint`
- A change is not done until tests and lint pass.
- Add or update tests for any behaviour you change.

## Code style
- TypeScript strict mode; no `any`.
- Prefer named exports; no default exports.
- Keep functions small; comment the *why*, not the *what*.

## Security
- Never read or print `.env` or anything under `secrets/`.
- Do not add new network calls without noting them in the PR.

## PR instructions
- Title format: `[area] short summary`
- Use Conventional Commits.
- Include a one-line test plan in the description.

Because closer files win (see nested files), you can keep this root file general and drop a tighter AGENTS.md inside any subproject that needs different rules.

Which tools read AGENTS.md

Support is real but uneven — a few tools read it deeply, many list it, and one big one does not. The table below draws only on primary sources: each tool's own docs or changelog. The official site self-reports 20-plus supporting tools (Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Phoenix, Semgrep, GitHub Copilot coding agent, Ona, Windsurf, Augment Code) — a self-reported list, so read it as breadth, not uniform depth.

Sources, in order: Codex docs, Cursor rules docs, Jules docs, and the GitHub Copilot changelog (all verified July 2026).

AGENTS.md vs CLAUDE.md and the naming split

Claude Code does not read AGENTS.md — it reads CLAUDE.md, and that difference is the whole reason AGENTS.md exists. Anthropic's memory docs define CLAUDE.md as "a markdown file you add to your project root that Claude Code reads at the start of every session." AGENTS.md support in Claude Code is only open community feature requests (issues #6235 and #34235), not a shipped feature — so people bridge it by symlinking CLAUDE.md to AGENTS.md:

# make Claude Code and AGENTS.md-aware tools share one file
ln -s AGENTS.md CLAUDE.md

This is the fragmentation AGENTS.md is trying to solve. Different agents grew their own context files — Claude Code uses CLAUDE.md, Gemini tooling uses GEMINI.md, GitHub Copilot uses .github/copilot-instructions.md — and AGENTS.md is positioned as the convergence file that many of them can read. It is not the only format that exists; it is the one trying to unify them. (There is even a competing, differently-named proposal — agentsmd/agents.md is the canonical repo, while a separate agentmd/agent.md pushes singular AGENT.md — which is a good reminder the convention is not fully settled.) If you live in Claude Code day to day, our how-to-use-Claude-Code guide covers CLAUDE.md in depth, and Claude Code vs Cline compares how two agents treat project context.

Nested files and precedence

You can have more than one AGENTS.md, and the nearest file wins. Nested files are part of the convention: an agent reads the closest AGENTS.md in the directory tree, so a subproject's file takes precedence over the root one for files beneath it. That lets a monorepo carry one general root file plus tighter per-package rules.

Codex makes the layering explicit — it builds an instruction chain from a global ~/.codex/AGENTS.md (or an AGENTS.override.md) down through the project root to the current directory, with closer files overriding earlier guidance. Cursor likewise applies a subdirectory's AGENTS.md automatically to files in that directory and its children. The mental model is the same everywhere: more specific beats more general.

One file, many agents, one gateway

AGENTS.md standardises the instructions your agents read; a gateway standardises the models they run on. The two solve parallel fragmentation problems. AGENTS.md gives Codex, Cursor, Jules and Copilot one context file instead of four bespoke ones. A gateway gives all of those agents one OpenAI-compatible endpoint and one API key instead of a separate integration per provider — so you can point an AGENTS.md-driven agent at Claude, GPT-OSS or GLM without rewiring auth, and fail over if one provider is down. If you are choosing the model behind the agent, our best coding LLM guide and best LLM for AI agents rank the current options.

FAQ