AGENTS.md file: best practices and a full example

What is an AGENTS.md file?

The AGENTS.md site describes the file as “a simple, open format for guiding coding agents”, a README written for agents rather than people. A README explains the project to a new contributor; AGENTS.md holds the extra detail an agent needs to change code safely, such as exact commands and conventions that would clutter a README.

The format is deliberately minimal. There is no schema and no required heading: it’s ordinary Markdown, and the agent reads the text. The site lists support in Codex, Cursor, GitHub Copilot’s coding agent, Gemini CLI, Jules, Aider, Devin, Windsurf, Zed, Warp and others, and says the file is used by over 60,000 open-source projects. AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation.

The file pays off in measurable ways. In a study of 10 repositories and 124 pull requests, Lulla and colleagues ran coding agents with and without an AGENTS.md file. With the file, median runtime was 28.64% lower and output token use 16.58% lower, while task completion stayed comparable (arXiv 2601.20404).

Where AGENTS.md lives: root and nested files

Start with one file at the repository root. When a package or service has rules of its own, add another AGENTS.md in that folder. Agents read the files from the root down to the code they’re working on, so the nested file adds to the root one rather than replacing it.

AGENTS.md                  # repository-wide: commands, structure, style
apps/web/AGENTS.md         # frontend conventions
services/billing/AGENTS.md # money, idempotency, migrations

When two files disagree, the agents.md FAQ gives the rule: “The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything.” A change in services/billing/ gets the root rules plus the billing rules, with billing winning any conflict. A change in apps/web/ never sees the billing file.

Nesting is also how you keep the root file short. Instructions that matter for one folder load into every task when they sit at the root; in that folder’s own file, they load when an agent works there.

What to put in AGENTS.md

The agents.md site suggests a project overview, build and test commands, code style guidelines, testing instructions and security considerations, plus commit or pull request guidelines and deployment steps where they help. GitHub’s analysis of more than 2,500 custom agent files in .github/agents/ landed on a similar set: commands, testing, project structure, code style, git workflow and boundaries.

• Commands, early. The exact commands to install, build, test, lint and type-check, with flags. An agent that can run the checks can verify its own work.
• Structure. Where things live: one line per important folder, and which folders are generated or vendored.
• Conventions. The helpers and libraries to use, naming, error handling, and how tests are written. Name the file or function each rule is about.
• Boundaries. GitHub’s analysis suggests three tiers: always do, ask first, never do. “Never commit secrets” was the most common helpful constraint it found.
• Git and pull requests. Branch naming, commit style, and what a pull request description must include. A pull request template can hold the structure, and AGENTS.md can tell agents to fill it in.

Leave out what any experienced engineer already knows. “Write clean code” and “use meaningful names” cost tokens in every session and change nothing, because agents follow common practice already.

A full AGENTS.md example

This root file is for a TypeScript web app with a Postgres database. Swap in your own commands and paths; the shape is what carries over.

# AGENTS.md

## Commands

- Install: pnpm install
- Dev server: pnpm dev (port 3000)
- Tests: pnpm test, or pnpm test src/api/invoices.test.ts for one file
- Type check: pnpm typecheck
- Lint and format: pnpm lint --fix
- Run tests, type check and lint before you finish a task.

## Structure

- src/app/: Next.js routes and pages.
- src/api/: API handlers, one file per resource.
- src/jobs/: background jobs. Jobs are idempotent, because the queue
  can run a job twice.
- src/generated/: generated API client. Don't edit; run pnpm codegen.

## Conventions

- Retries use retry() from src/lib/retry.ts, which adds backoff.
- Read the current time through now() from src/lib/clock.ts, so tests
  can set it.
- Return client errors through AppError with a stable code, such as
  new AppError('INVOICE_NOT_FOUND', 404).
- Database queries in API handlers are scoped to the caller's
  workspace ID.

## Tests

- Each new API handler has a test in tests/api/ that runs against a
  real database. Don't mock the database.
- A bug fix comes with a test that fails without the fix.

## Boundaries

- Always: keep changes to the task; ask before large refactors.
- Ask first: adding a dependency, changing a database migration that
  has shipped, editing CI workflows.
- Never: commit secrets or .env files, disable a failing test to make
  it pass, edit files in src/generated/.

## Pull requests

- Branch names: type/short-description, such as fix/invoice-rounding.
- Fill in .github/pull_request_template.md. List the commands you ran
  and anything you assumed that the task didn't specify.

And a nested file for the billing service, which adds to the root rules:

# services/billing/AGENTS.md

- Every call to chargeCard() passes an idempotency key derived from
  the order ID, so a retried request can't charge twice.
- Amounts are integers in cents. Never use floating point for money.
- Migrations here must be backward compatible: add, backfill and
  remove in separate releases.

AGENTS.md best practices

• Keep it short. Every line loads into every session. Claude Code’s docs suggest under 200 lines per file, noting that longer files use more context and reduce adherence.
• Make each rule checkable. “Amounts are integers in cents” can be checked against a line of code; “be careful with money” can’t.
• Give the reason when it isn’t obvious. “Jobs are idempotent, because the queue can run a job twice” lets an agent handle a case the rule doesn’t spell out.
• Show, don’t describe. GitHub’s analysis found one real snippet of your style beats three paragraphs describing it, and that naming the stack precisely, with versions, beats “React project”.
• Grow it from real mistakes. Add a rule when an agent gets something wrong twice, and delete rules that no longer match the code. Treat the file as living documentation.
• Remove contradictions. Claude Code’s docs warn that when two instructions contradict each other, the agent may pick one arbitrarily. Check nested files against the root one.
• Keep enforcement in CI. An instruction is guidance. Formatting, lint and anything that must hold on every merge belong in CI or a required check.

A good AGENTS.md is short, specific and written from real mistakes. Put exact commands first so the agent can test its own work, name the paths and helpers each rule is about, add the reason when it isn’t obvious, and set boundaries for what the agent must ask about or never do. Push folder-specific rules into nested files.

How Codex, Claude Code, Cursor and Copilot read AGENTS.md

The format is shared, but each tool loads it a little differently. These details come from each vendor’s documentation.

Codex

Codex builds its instruction chain once per run. It starts with your Codex home directory (~/.codex unless CODEX_HOME is set), then walks from the project root, typically the Git root, down to the current directory, taking at most one file per directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. Files closer to the working directory appear later and override earlier guidance. To see what loaded, run codex --ask-for-approval never "Summarize the current instructions." from the repository root. Codex code review follows the same files; our Codex code review guide shows how to write a ## Code Review Rules section.

Claude Code and CLAUDE.md

Claude Code’s own file is CLAUDE.md, at ./CLAUDE.md or ./.claude/CLAUDE.md, with ~/.claude/CLAUDE.md for personal preferences. Since v2.1.277 it reads AGENTS.md directly when the project has no CLAUDE.md or CLAUDE.local.md in the working directory or above. If a CLAUDE.md exists, Claude reads only the CLAUDE.md files by default.

To keep one shared file, make CLAUDE.md import it and add Claude-specific notes below:

# CLAUDE.md
@AGENTS.md

## Claude Code
- Ask before running database migrations locally.

A symlink (ln -s AGENTS.md CLAUDE.md) also works, but Claude Code’s docs recommend the import when anyone on the team uses Windows, where Git may check the symlink out as a plain text file.

Cursor

Cursor treats AGENTS.md as a plain Markdown alternative to .cursor/rules. It supports the file in the project root and in subdirectories; nested files apply when working in that directory and combine with their parents, with the more specific instructions taking precedence.

GitHub Copilot

GitHub’s docs say you can create one or more AGENTS.md files anywhere in the repository, and the nearest one in the directory tree takes precedence while Copilot works. A single root CLAUDE.md or GEMINI.md works as an alternative. When reviewing a pull request, Copilot reads repository custom instructions, agent instructions and agent skills from the head branch.

One AGENTS.md for coding agents and reviewers

The conventions an agent should follow when it writes code are the same ones a reviewer should check. Keeping them in one file means the author and the reviewer work from the same rules, and a rule you add after a bad review also steers the next change an agent writes.

HeyDeer reviews pull requests against the same file. For each changed file, it applies the AGENTS.md files from the repository root down to that file’s directory; a deeper file adds to the ones above it and wins where they conflict. In a directory without AGENTS.md, it reads CLAUDE.md instead. It reads the files from the pull request, so a change that edits AGENTS.md is reviewed with its own version. HeyDeer reads up to 32 KiB of these files and doesn’t follow imports, so write the conventions in AGENTS.md itself and let CLAUDE.md import it, not the other way round. The AGENTS.md docs cover the details.

Split guidance by who needs it:

• AGENTS.md: how the code works and the conventions it follows, for everyone who writes or reviews it.
• REVIEW.md: what reviews should look for, leave alone, and how serious an issue is. Coding agents don’t need it.
• Repository checks: a requirement HeyDeer verifies in every pull request that touches certain files, such as access control on API routes.

See how HeyDeer applies review rules, or how AI code review works for the bigger picture.

Sources

1. AGENTS.md: the open format for guiding coding agents
2. OpenAI Codex docs: Custom instructions with AGENTS.md
3. Claude Code docs: How Claude remembers your project
4. Cursor docs: Rules
5. GitHub Docs: Adding repository custom instructions for GitHub Copilot
6. GitHub Blog: How to write a great agents.md: Lessons from over 2,500 repositories
7. Lulla et al., On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents