AGENTS.md

AGENTS.md is the vendor-neutral version of the same idea: one predictable file at the repository root where a coding agent finds the context it needs, without cluttering the README that humans read.

Checked against the official documentation in August 2026. These tools change quickly, so the date is part of the answer.

A typical AGENTS.md

# Project overview

A Next.js site with a client-side markdown viewer. Nothing a visitor
supplies is sent to a server.

## Setup and commands

```bash
npm install
npm run dev     # port 3040
npm test        # vitest
```

## Code style

- TypeScript, ES modules, 2-space indentation
- British English in user-facing copy

## Testing

Run `npm test` before opening a pull request. New parsing rules need a
test in `lib/*.test.ts`.

## Pull requests

Branch names as `type/short-description`. Keep the diff focused.

Project overview

A Next.js site with a client-side markdown viewer. Nothing a visitor supplies is sent to a server.

Setup and commands

npm install
npm run dev     # port 3040
npm test        # vitest

Code style

TypeScript, ES modules, 2-space indentation
British English in user-facing copy

Testing

Run npm test before opening a pull request. New parsing rules need a test in lib/*.test.ts.

Pull requests

Branch names as type/short-description. Keep the diff focused.

Sharing one file with Claude Code

@AGENTS.md

## Claude Code

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

@AGENTS.md

Claude Code

Use plan mode for changes under src/billing/.

Claude Code reads CLAUDE.md and not AGENTS.md, so a CLAUDE.md that imports it keeps both tools on the same instructions. A symlink works too if you have nothing Claude-specific to add.

Where it came from

The format emerged from a collaboration between OpenAI Codex, Amp, Google Jules, Cursor and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. More than 60,000 open-source projects use one.

Tools that read it include Codex, Google Jules, Aider, Zed, VS Code, GitHub Copilot, JetBrains Junie, Cursor, Windsurf and Semgrep.

Structure

There are no required fields. It is ordinary markdown, and the sections that recur are project overview, build and test commands, code style, testing instructions, security considerations, and commit or pull-request conventions.

In a monorepo, put one at the root and one in each subproject. The closest file to the work takes precedence.

What usually goes wrong

Do not maintain both an AGENTS.md and a CLAUDE.md by hand. They drift within a month. Import one from the other, or symlink them.
The file is for the agent, not the reader. Anything a human needs belongs in the README, and duplicating between the two guarantees one goes stale.
The same length discipline applies as to CLAUDE.md: it is loaded into context, so every line costs attention.
On Windows a symlink needs Administrator rights or Developer Mode, so the @AGENTS.md import is the portable route.

Where it behaves differently

Platform	Behaviour
Claude Code	Reads CLAUDE.md only. Use `@AGENTS.md` inside CLAUDE.md, or symlink.
Cursor	Reads AGENTS.md in the root and in any subdirectory, alongside its own `.cursor/rules/`.
Codex, Jules, Aider, Zed, Copilot, Junie, Windsurf	Read AGENTS.md directly.

Questions

AGENTS.md or CLAUDE.md?

Both, but written once. If your team uses several tools, keep the content in AGENTS.md and have CLAUDE.md import it. If everyone is on Claude Code, a CLAUDE.md on its own is simpler.

Does it replace the README?

No. The README explains the project to a person deciding whether to use or contribute to it. AGENTS.md tells an agent how to work in the repository. Different readers, different files.