AGENTS.md: one instructions file for every coding agent

AGENTS.md is an open format described as a README for coding agents: a predictable place for setup, build, test, and convention notes. The point is one file many CLI agents read, instead of a different dotfile for each tool. It is plain Markdown with no required fields.

1. Create AGENTS.md at the repo root

Put the file at the root of the repository. In a large monorepo you can add nested AGENTS.md files per subproject; an agent reads the nearest one in the tree, so the closest file takes precedence. Explicit chat prompts still override whatever the file says.

2. Write build, test, and conventions

# Project overview
Short description of what this repo is.

## Setup & build
- Install: `pnpm i`
- Build: `pnpm build`

## Testing
- Run: `pnpm test` — all tests must pass before a PR.

## Conventions
- TypeScript strict, no `any`. Do not edit anything under `src/generated/`.

Keep it to what an agent cannot infer from the code: exact commands, conventions, and no-go zones.

3. Know which tools read it

The agents.md spec lists many adopters, including Codex, Cursor, Gemini CLI, GitHub Copilot coding agent, Jules, Aider, goose, Zed, Warp, and Windsurf. A repository already set up for one of these works for the others without a rename.

4. AGENTS.md vs CLAUDE.md in Claude Code

Claude Code reads AGENTS.md directly (v2.1.277 or later), but only when you have no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If both exist, CLAUDE.md wins by default. To load both, type /config and set Project instructions to claude-md-and-agents-md. On older versions, import it with @AGENTS.md inside a CLAUDE.md.

5. Migrate from a tool-specific file

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Renames the old singular file and leaves a symlink for backward compatibility. For Cursor or Copilot rules, Claude Code’s /init reads .cursorrules and .github/copilot-instructions.md and folds the relevant parts into a generated CLAUDE.md. Codex reads AGENTS.md natively, as in Codex CLI first steps.

Verify it worked

In Claude Code, run /memory and look for your AGENTS.md path in the list, or run /context and check Memory files. If the path is there, the file loaded.

If it fails:

AGENTS.md is ignored in Claude Code — a CLAUDE.md on the project path takes precedence; set Project instructions to claude-md-and-agents-md, or add @AGENTS.md to that CLAUDE.md.
claude --version below 2.1.277 — direct reading is unavailable; run claude update or use the @AGENTS.md import.
A CLAUDE.md symlink checks out as one line of text on Windows — Git stored the symlink as plain text; use the @AGENTS.md import instead of a symlink.