AGENTS.md: brief your coding agents in one file.

AGENTS.md is a plain Markdown file at the root of your repository that tells AI coding agents how your project works: how to install it, run the tests, follow your conventions and avoid known traps. Think of it as a README written for agents instead of people. OpenAI Codex, Cursor, GitHub Copilot, VS Code and recent versions of Claude Code all read it.

The catch is that more is not better. A 2026 study from ETH Zurich found that these files did not generally raise agents’ success rates and added over 20% to inference cost. The instructions inside were followed well, though. So write down what an agent cannot guess, and nothing else.

01What is AGENTS.md?

The format grew out of work across several agent makers, including OpenAI Codex, Amp, Google’s Jules, Cursor and Factory. In December 2025, OpenAI contributed it to the Agentic AI Foundation, a fund under the Linux Foundation that also holds Anthropic’s Model Context Protocol and Block’s goose. At the time, the foundation said more than 60,000 open-source projects and agent frameworks had adopted it.

Why not just use the README? Because the audiences differ. A README welcomes people with a quick start and a screenshot. An agent needs the tedious details: the exact test command, the folder it must never edit, the check that has to pass before a task counts as done.

02Which tools read AGENTS.md?

Support has spread fast, and each tool has its own quirks. As of September 2026, according to each vendor’s docs:

The official site lists many more, including Jules, Devin, Windsurf, Zed, Warp, goose, opencode, Aider, Amp, Junie and Factory. Support changes quickly, so check your tool’s docs when something seems ignored.

03What to put in AGENTS.md

Write down what a new senior engineer would need on day one, and only that. In practice, that is five things.

• Setup. The exact install and run commands, including the package manager you actually use.

• Checks. How to type check, lint, run all tests and run one test file. This is the single most useful section.

• Conventions that differ from the defaults. Where server code lives, how errors are handled, how money is stored.

• Gotchas. Generated folders, fake clocks, slow tests, anything that has burned someone before.

• Boundaries. What needs a human first, such as migrations, billing code or new dependencies.

The ETH Zurich researchers found that agents follow these files closely, but that repository overviews did not help. Their conclusion was that context files are useful for specifying non-standard practices. In other words, document what differs from what an agent would assume.

04A complete AGENTS.md example

Here is a full file for a TypeScript web app. It is short on purpose.

# AGENTS.md

## Setup
- Install with `pnpm install`. Do not use npm or yarn.
- Copy `.env.example` to `.env.local`. Never commit any `.env` file.
- Start the dev server with `pnpm dev` (http://localhost:3000).

## Checks
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- All tests: `pnpm test`
- One file: `pnpm vitest run src/lib/cart.test.ts`
- Before you say a task is done, run all three checks. They must pass.

## Conventions
- TypeScript strict mode. No `any`: use `unknown` and narrow it.
- Server code lives in `src/server/`. Never import it from `src/components/`.
- Store money as integer cents. Format it only in the UI with `formatPrice()`.
- User-facing text goes through `t()` from `src/i18n`. No hardcoded strings.

## Gotchas
- `src/generated/` is written by `pnpm codegen`. Never edit it by hand.
- Tests use a fake clock. Call `vi.useRealTimers()` if a test needs real time.

## Ask before you
- Write a database migration.
- Touch anything in `src/billing/`.
- Add a new dependency.

Every line is either a command, a rule an agent would not infer, or a trap. There is no mission statement and no tour of the folder structure.

These are usually the exact checks a coding agent should also run unattended in CI; our guide to running a coding agent in GitHub Actions shows a working pipeline file.

05What to leave out

Anything that must happen every time belongs in tooling, not prose. Claude Code’s docs make the same point: for rules that can never be skipped, use a hook, a shell command that runs automatically at a fixed point.

And remember that AGENTS.md is usually committed and often public. Treat it like any other file in the repo, and never paste a secret into it.

06How long should AGENTS.md be?

Shorter than you think. Codex stops reading once the combined files reach 32 KiB by default. Claude Code’s docs suggest keeping its own instructions file under 200 lines, warning that longer files “consume more context and reduce adherence.”

The reason is the context window. Every line loads into the context window at the start of every session, whether the task needs it or not. That is why context engineering starts with this file. Know-how that only some tasks need, such as how to cut a release, fits better in agent skills, which load only when relevant.

Keep it current, too. A stale command is worse than a missing one, because the agent will run it confidently. Update AGENTS.md in the same pull request that changes the build.

Read AGENTS.md, then check it against this repository.
1. Run every command it lists and report any that fail or no longer exist.
2. Flag instructions that contradict the code, the config files or each other.
3. Flag generic advice an agent would follow anyway, such as "write clean code".
4. Suggest cuts first and additions second. Keep the result under 200 lines.
Do not edit the file. Show me the proposed diff.

07AGENTS.md vs CLAUDE.md and other tool files

Several tools had their own instruction files before AGENTS.md caught on: CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, .cursor/rules for Cursor and .github/copilot-instructions.md for Copilot. The clean setup today is one AGENTS.md as the source of truth, with tool files that point to it.

For Claude Code, this matters because it reads CLAUDE.md instead of AGENTS.md when both exist. The fix from Anthropic’s docs is a CLAUDE.md that imports the shared file, with any Claude-only notes below it:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

A symlink (ln -s AGENTS.md CLAUDE.md) also works on macOS and Linux. On Windows, use the import, because Git often checks symlinks out as plain text files there.

For Gemini CLI, list AGENTS.md in the context.fileName setting of the project’s .gemini/settings.json:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

Standing instructions set the ground rules. Each task still needs a clear request, and our prompts for coding agents cover that half. For a bigger feature, writing that request as a proper spec first is its own approach, covered in our guide to spec-driven development.

08FAQ

Next, learn how agent skills teach an agent a whole task, or how MCP connects agents to your tools.