# AGENTS.md: one instructions file for every coding agent

> AGENTS.md is the cross-agent conventions file. Where to put it, what to write, which tools read it, and how Claude Code loads it next to CLAUDE.md.

- Canonical: https://guides-ai.com/guides/agents-md-file/
- Plate 14.06 · Topic: Other coding agents (https://guides-ai.com/topics/agents/)
- Published: 19 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

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

```markdown
# 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](https://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](/guides/create-claude-md-project-memory/).

## 5. Migrate from a tool-specific file

```bash
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](/guides/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.