AGENTS.md: A Template for Coding Agents

In short

AGENTS.md is a plain Markdown file at the root of your repository that tells coding agents how to build, test and behave in your project. The format has no required fields — the official site calls it "a README for agents" and says agents read the nearest file in the directory tree, so a package-level file beats the root one. Support is broad: Cursor, GitHub Copilot, Codex, Jules, Zed and Aider read it. Claude Code does not — its docs say plainly that it reads CLAUDE.md, not AGENTS.md, and recommend a one-line @AGENTS.md import or a symlink to bridge the two. Keep the file short. A 2026 study found that context files did not generally improve task success rates while adding over 20% to inference cost, and repository overviews — the section everyone writes first — were the least useful part. Write commands, constraints and non-obvious gotchas. Delete the architecture essay.

Where AGENTS.md came from and who reads it

The agents.md repository was created on 19 August 2025 and lives at agentsmd/agents.md, with about 23k stars as of July 2026; github.com/openai/agents.md still redirects there. The pitch is deliberately small: one Markdown file, no schema, no frontmatter, no required headings. As the site puts it, "just standard Markdown. Use any headings you like; the agent simply parses the text you provide."

That minimalism is why adoption spread. The site lists over 25 tools that read the file and claims 60k+ open-source projects using it. Treat both numbers as vendor-reported — nobody has audited them, and a GitHub code search counts files, not files that anyone maintains.

Two behaviours are worth knowing before you write anything:

• Nearest file wins. In a monorepo, put an AGENTS.md in each package. The one closest to the file being edited takes precedence. GitHub's Copilot docs describe the same rule: "the nearest AGENTS.md file in the directory tree will take precedence."
• Chat beats the file. Per the spec, "explicit user chat prompts override everything." The file is a default, not a lock. If you need something enforced regardless of what the model decides, use a hook or a CI check, not a bullet point.

How it differs from CLAUDE.md and Cursor rules

The three formats overlap in purpose and differ in mechanics. This is the part most guides skip, and it's the part that bites you when you add a second tool.

The practical differences: Cursor and Claude Code both give you conditional loading — rules that only enter context when the agent touches a matching path — and AGENTS.md gives you none. Its only scoping mechanism is where you put the file. And Claude Code concatenates every CLAUDE.md up the tree rather than picking the nearest, which is the opposite of the AGENTS.md rule. In a monorepo those two behaviours produce different context, from the same directory, for the same task.

If you already maintain Cursor rules, our breakdown of the .mdc format and the four rule types covers the frontmatter that AGENTS.md deliberately doesn't have.

A template you can copy

Six sections, in this order. Everything here is either a command an agent will run or a fact it will get wrong on its own.

# AGENTS.md

## Setup
- Node 22, pnpm 9. `pnpm install --frozen-lockfile`
- Copy `.env.example` to `.env.local`; the app crashes on boot without `DATABASE_URL`

## Commands
- Dev server: `pnpm dev` (port 3000)
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Full check before you claim done: `pnpm lint && pnpm typecheck && pnpm test`
- Never run `pnpm build` to verify a change — it takes 6 minutes

## Code style
- TypeScript strict, no `any`. Prefer `unknown` plus a type guard
- Named exports only; `export default` is banned outside `app/**/page.tsx`
- Errors: throw `AppError` from `src/lib/errors.ts`, never bare `Error`

## Non-obvious rules
- `src/db/schema.ts` is generated. Edit `drizzle/*.sql` and run `pnpm db:generate`
- Anything under `src/legacy/` is frozen. Do not refactor it, even if it looks wrong
- API routes must stay Node runtime; the edge runtime breaks our PDF worker

## Testing
- New behaviour needs a test in the same PR. Snapshot tests are not accepted
- Integration tests need Docker running: `docker compose up -d postgres`

## Pull requests
- Title format: `area: short imperative summary`
- Run the full check above; paste the output in the PR body

Notice what's missing: no directory tree, no architecture narrative, no list of dependencies. The agent can read package.json and ls a folder faster than it can read your prose about them, and the study cited below found overview sections specifically unhelpful. Keep the file under roughly 150–200 lines; if it grows past that, split by package rather than adding sections.

Making one file work across every tool

The cheapest portable setup is AGENTS.md as the source of truth plus a thin bridge for Claude Code. Anthropic documents both options:

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code
Use plan mode for changes under `src/billing/`.

Or, if you have nothing Claude-specific to add:

ln -s AGENTS.md CLAUDE.md

On Windows the symlink needs Administrator rights or Developer Mode, so prefer the import. Cursor reads AGENTS.md at the project root natively and supports nested files, so it needs no bridge at all — its docs describe the file as "an alternative to .cursor/rules" for straightforward cases. Copilot reads AGENTS.md from anywhere in the repo.

That leaves one honest gap: path-scoped rules do not port. A Cursor .mdc with globs: src/api/** and a Claude .claude/rules/api.md with paths: frontmatter have no AGENTS.md equivalent. If you rely on conditional loading, you are maintaining tool-specific files whether you like it or not — either by hand, or by generating them from one spec, which is the approach we describe in export for Claude Code, Cursor and AGENTS.md.

Does it actually help? The uncomfortable evidence

Two 2026 papers are worth reading before you spend an afternoon on this file.

Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? tested agents with and without context files on benchmark tasks and real issues. The finding: "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average." Agents did follow the instructions in the files — they just didn't finish more tasks. LLM-generated context files did slightly worse than none at all; hand-written ones did marginally better. Repository overviews, the most commonly recommended section, were unhelpful.

Configuration Smells in AGENTS.md Files mined 100 popular repositories with an AGENTS.md or CLAUDE.md and found recurring problems: lint leakage (rules already enforced by ESLint or Prettier, restated in prose) in 62% of files, context bloat in 42%, and skill leakage in 35%.

The reading that survives both papers: a short file of commands and constraints an agent cannot infer is cheap and occasionally saves a wrong turn. A long file restating your linter is a tax you pay on every single request. If your CI already fails on unformatted code, the agent does not need to be told about formatting — it needs to be told to run the check.

Keeping it honest over time

The failure mode is drift. The file describes the repo as it was three refactors ago, and now it actively misleads. Two habits help: put the exact commands in it so a stale entry breaks loudly rather than quietly, and review it whenever a build command changes. Claude Code's /doctor proposes trims for a checked-in CLAUDE.md — it removes content derivable from the codebase and keeps pitfalls and conventions. That's the right editorial rule for AGENTS.md too, tool or no tool.

If you want the wider picture of how instruction files fit alongside subagents, skills and MCP, start with our subagent setup guide or the AGENTS.md trend card.

FAQ

What is AGENTS.md used for?

It's a Markdown file at the root of a repository that gives AI coding agents the project context they can't infer: setup steps, exact build and test commands, code conventions, and rules about what not to touch. Agents read it automatically at the start of a session. It replaces the habit of pasting the same three paragraphs into chat every time.

AGENTS.md vs CLAUDE.md — which one should I use?

Use AGENTS.md as the source of truth, because more tools read it — Cursor, Copilot, Codex, Jules, Zed and others. Claude Code reads only CLAUDE.md, so add a CLAUDE.md containing the single line @AGENTS.md (or symlink it) and put Claude-specific instructions below the import. Maintaining two full files is how they end up contradicting each other.

Does Claude Code read AGENTS.md?

No. Anthropic's memory docs state it directly: "Claude Code reads CLAUDE.md, not AGENTS.md." The documented workarounds are an @AGENTS.md import inside CLAUDE.md or a symlink. Separately, running /init with CLAUDE_CODE_NEW_INIT=1 will read an existing AGENTS.md when generating a CLAUDE.md.

How long should an AGENTS.md be?

Short. Anthropic recommends under 200 lines for CLAUDE.md, Cursor recommends under 500 for rules, and the research suggests the marginal value of extra prose is negative once you're past commands and constraints. Every line is re-read on every request, so a 400-line file is a permanent surcharge on your token bill.

Can I have more than one AGENTS.md in a repo?

Yes, and in a monorepo you should. Put one per package; the file nearest the edited code takes precedence in Cursor, Copilot and Codex. Be aware that Claude Code behaves differently — it concatenates every CLAUDE.md from the repository root down to your working directory instead of picking the closest one.