AGENTS.md alongside CLAUDE.md, one repo context for several AI tools

You have a clean CLAUDE.md. Your setup runs. Then a colleague joins who works with Codex. A week later someone tries Cursor. Suddenly you are explaining the same setup commands three times, once per tool, in different config files. AGENTS.md solves that. One file read by Claude Code, Codex, Cursor, Gemini CLI, Aider, Continue and VS Code Copilot. According to agents.md, over 60,000 open source projects use it. This playbook shows how you set up AGENTS.md in addition to your CLAUDE.md without having to maintain content twice.

Step 1: Understand what AGENTS.md actually is

AGENTS.md is an open convention, not an Anthropic feature and not a Cursor feature. The file sits in the repo root and contains what an AI coding tool needs to know to work sensibly in the project. Setup commands, test commands, code style, PR rules. The idea comes out of the OpenAI Codex world and spread in 2025 and 2026, because otherwise every tool vendor would have invented its own config file name.

Worth knowing: AGENTS.md is not magic. It is only a file that tools read because they recognise the name. Claude Code does not read it automatically (it reads CLAUDE.md), but if you build a reference into your CLAUDE.md, Claude still gets to it. More on that in step 7.

Step 2: When AGENTS.md is worth it in addition

If you work alone with Claude Code and never touch another tool, you can leave AGENTS.md out. CLAUDE.md is enough.

But as soon as at least one of these applies, the second file is worth it:

• Several people on the team use different AI tools (Codex, Cursor, Copilot)
• You have open source code and want external contributors to get going directly with their own setup
• You yourself sometimes switch between tools (for example Claude Code daily, Codex in CI)
• Your repo is used by auto-coding bots like Sourcegraph Cody or Copilot Coding Agent

In the StudioMeyer repo we use both. CLAUDE.md for the Claude-specific hooks, skills and memory notes. AGENTS.md for everything that is tool-agnostic: build commands, test setup, PR rules.

Step 3: Decide the layout, one file or several

AGENTS.md can sit in several places in the repo. In the root it applies globally. In a subdirectory it overrides the root file for files in that directory. For monorepos that matters.

For a normal single-package repo: one AGENTS.md in the root is enough.

For a monorepo with several packages: one AGENTS.md in the root with the global setup commands, plus one AGENTS.md per workspace with the package-specific notes. More on that in step 9.

Step 4: Create the first AGENTS.md

In the repo root:

touch AGENTS.md
git add AGENTS.md

A structure that has proven itself:

# Project Name

One short sentence on what the repo is.

## Setup commands

- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons
- Functional patterns where possible

## Testing instructions

- Vitest with `pnpm test`
- Focus on one test file: `pnpm vitest run -t "test name"`
- CI runs in .github/workflows/test.yml

## PR instructions

- Title format: `[scope] short description`
- Before every commit: `pnpm lint && pnpm test`
- Squash merges only

That is the skeleton. Usually shorter than CLAUDE.md, because it only contains the tool-agnostic things.

Step 5: Enter setup commands and test commands properly

Here is the crux. When a new AI tool touches your repo, the first command it fires is almost always install plus test. If that is not clearly in AGENTS.md, the tool guesses. Sometimes right, often wrong.

A concrete example from our Academy repo. Before AGENTS.md, new tools mostly tried npm install (we use pnpm). Three minutes wasted, then a packed-lockfile conflict. With AGENTS.md, line two says pnpm install, and the tool starts correctly.

Be explicit. Instead of "run tests", better the full command with the file or the filter, if relevant:

- Run all tests: `pnpm test`
- Run academy lessons tests only: `pnpm test:lessons`
- Skip e2e tests in CI fast-lane: `SKIP_E2E=1 pnpm test`

Step 6: Document code style and PR rules

Code style is the area where AI tools make the biggest mess when it is not written down. Single quote versus double quote. Semicolons. Tabs versus spaces. Functional versus OO.

Write it concretely, with a yes/no example where possible:

## Code style

- TypeScript strict mode, no `any`
- Single quotes only: `const x = 'hello'` not `const x = "hello"`
- No semicolons at the end of statements
- Async/await instead of `.then()` chains
- Named exports, no default export

Another tool's team can follow that immediately. With "use clean code" alone, not so much.

PR rules should contain: title format, mandatory checks before the commit, merge strategy. If you have a PR template file, refer to it instead of duplicating the template here.

Step 7: Adjust CLAUDE.md so nothing is duplicated

Now the critical step. You do not want drift between AGENTS.md and CLAUDE.md. If the setup commands are changed in AGENTS.md and CLAUDE.md still contains the old ones, you find out at the next bug.

The clean solution: CLAUDE.md refers to AGENTS.md at the top.

# Claude Code Instructions

Read @AGENTS.md first, it has all the setup, test and code style rules.

Additions specific to Claude Code:

- Memory layer: studiomeyer-memory MCP server
- Hooks: see .claude/settings.json
- ...

The @AGENTS.md is a Claude Code specific reference that includes the file. That way you have the content once in one place and only add to CLAUDE.md what is genuinely Claude Code specific (hooks, skills, memory setup, plan mode notes).

More details in the companion playbook Claude Code in a team, maintaining CLAUDE.md together.

Step 8: Single source of truth or symlink

If your team finds it simpler, you can also create CLAUDE.md as a symlink to AGENTS.md. Then it is technically the same file, and Claude Code reads CLAUDE.md, Codex reads AGENTS.md, everyone has the same picture.

ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md

Downside: you can no longer make Claude-specific additions without them being visible to other tools too. If that suits you, it is the most convenient route. If not, stay with two separate files plus a reference (step 7).

In the StudioMeyer repo we decided against the symlink, because our CLAUDE.md also contains memory hook notes that are irrelevant for Cursor users. Two files, cleanly separated, AGENTS.md is the master.

Step 9: Monorepo, one AGENTS.md per workspace

If you have a monorepo with pnpm workspaces, Turborepo or Nx, you have the problem that the root AGENTS.md alone gets too generic. Solution: layer it.

In the root: the global things.

# Monorepo Root

## Setup

- `pnpm install` in the root
- Apps in `apps/`, packages in `packages/`
- Switch into the workspace before you build anything: `cd apps/web`

In every workspace its own AGENTS.md with the package-specific commands.

# apps/web/AGENTS.md

## Setup

- `pnpm dev` starts Next.js on port 3000
- DB migrations: `pnpm prisma migrate dev`

## Testing

- Unit tests: `pnpm test`
- e2e: `pnpm e2e` (needs a running DB)

Most AI tools read both. First the nearer AGENTS.md, then the one in the root as a fallback. That way you have context exactly where the agent is currently working, and you avoid bloating the root file.

Step 10: What next

Once AGENTS.md is in place, maintaining it is simple. With every new setup step, every changed test command, every new lint rule: into the file, commit, done. That is the same discipline as with the README, only with a different reader.

Three follow-up topics worth having:

If you serve several branches with Claude Code in parallel, git worktrees help. One Claude session per worktree, no stash chaos. See Claude Code with git worktrees.

If your team is fiddling with a shared CLAUDE.md and that regularly runs into conflicts in PR reviews, look at Claude Code in a team.

And if you want to read deeper into the official AGENTS.md spec, the entry point is at https://agents.md/ including examples from 60,000+ repos.

One file. Several tools. Less explaining.