One AGENTS.md for Claude Code, Codex, and Cursor

What you will learn

• What AGENTS.md is, and why one shared file beats maintaining separate instruction files per agent
• How to write a short root `AGENTS.mdthat covers stack, commands, and clear do / don't rules
• How Claude Code (2.1.277+), Codex, and Cursor each pick up that same file
• How to prove it worked by asking each agent to summarise the current instructions
• When to add a thinCLAUDE.md` bridge later, without inventing a nested override maze on day one

First success: one root AGENTS.md in a real repo, and Claude Code, Codex, and Cursor each quoting those rules back to you.

Prerequisites

• A local git repository you can edit (any small app or course project is fine)
• At least two of these installed the way you already use them in Buildcamp:
  • Claude Code 2.1.277 or later
  • Codex (ChatGPT's coding agent / CLI)
  • Cursor with Agent chat
• Comfort creating a markdown file at the repo root and committing it

You do not need every agent on day one. Two is enough to feel the payoff of one shared file.

Core concepts

What AGENTS.md is

AGENTS.md is a plain markdown file of project instructions that coding agents read before they work. Think of it as a short brief for a contractor: stack, how to run things, house rules, and hard no-gos.

It is not a second README for humans. Keep it agent-facing: concrete commands, file paths, and constraints. Humans can still read it; agents are the primary audience.

Why one file now

Until recently each tool had its own convention (CLAUDE.md, Cursor rules, Codex guidance). Teams ended up copying the same rules three times and watching them drift.

Three things changed that for Buildcamp's allowlisted agents:

1. Codex discovers AGENTS.md from the project root (and optionally a global file under ~/.codex). Official guide: Custom instructions with AGENTS.md.
2. Cursor treats root AGENTS.md as a first-class rules source: a simple alternative to `.cursor/rulesfor straightforward, always-on project instructions. Docs: Cursor Rules.
3. Claude Code 2.1.277+ readsAGENTS.mdwhen the project has noCLAUDE.md(and no.claude/CLAUDE.md/CLAUDE.local.mdon the path). If aCLAUDE.mdis present, it wins by default. You can change that under **Project instructions** in/config`. Changelog note: AGENTS.md support landed in 2.1.277.

So for a beginner-sized setup, one root AGENTS.md is enough. Nested overrides and multi-file rule packs can wait.

Mental model

Jargon check: project instructions means the persistent text the agent loads for this repository, separate from the one-off prompt you type in chat.

Step-by-step: one shared AGENTS.md

1. Open a real repository

Pick a repo you already touch in Buildcamp (Next.js, Expo, or a small API). Open a terminal at the project root. Confirm you are at the root (the folder that contains .git):

pwd
ls -la | head

2. Create a short root AGENTS.md

Create AGENTS.md at the repository root. Keep it small enough to skim in under a minute. Use this starter and edit the bracketed bits:

# AGENTS.md

## Stack
- [e.g. Next.js App Router, TypeScript, Tailwind, Supabase]
- Package manager: [npm | pnpm | yarn]

## Commands
- Install: `[your install command]`
- Dev server: `[your dev command]`
- Lint: `[your lint command]`
- Test: `[your test command]`

## Do
- Prefer small, reviewable diffs over large rewrites
- Match existing file layout and naming in this repo
- Ask before adding new production dependencies

## Don't
- Do not commit secrets, `.env` files, or API keys
- Do not rename or delete unrelated files to "clean up"
- Do not skip lint or tests when the change touches those areas

Save the file. Commit it when you are happy:

git add AGENTS.md
git commit -m "Add shared AGENTS.md for coding agents"

3. Prove Codex picks it up

From the same project root, start Codex the way you normally do, then ask:

Summarise the current project instructions you loaded. Quote the Do and Don't sections.

You should see your stack, commands, and rules reflected back. If Codex quotes nothing useful, confirm you started it from the repo root and that AGENTS.md is not empty. Official discovery rules: OpenAI AGENTS.md guide.

4. Prove Cursor picks it up

Open the same folder in Cursor. Start a new Agent chat and ask the same prompt:

Summarise the current project instructions you loaded. Quote the Do and Don't sections.

Cursor should treat the root AGENTS.md as project instructions. You do not need .cursor/rules for this first success. (You can add scoped .mdc rules later when you need glob-based attachment.)

5. Prove Claude Code picks it up

Important: for the default behaviour, make sure this project does not already have a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md. If one exists, Claude Code will prefer it and ignore AGENTS.md unless you change Project instructions in /config.

Update Claude Code to 2.1.277 or later, open the repo, start a session, and ask the same summarise prompt.

If Claude Code still ignores AGENTS.md:

1. Run `/configand check Project instructions
2. Confirm you are on 2.1.277+3. Note the Bedrock / Vertex / Foundry caveat in Going further below

6. First success checklist

You are done when:

1.AGENTS.mdlives at the repo root and is committed 2. At least two agents quote the same Do / Don't rules back 3. You did not create nestedAGENTS.md` files or a rules maze

That is the whole beginner path: one file, three agents, same brief.

Check your understanding / common mistakes

Quick check

1. Where should the first `AGENTS.mdlive for this guide?
2. In Claude Code 2.1.277+, what happens if bothCLAUDE.mdandAGENTS.md` exist and you leave the default Project instructions alone?
3. Do you need .cursor/rules before Cursor will read a root AGENTS.md?

Answers

1. The repository root (next to .git).
2. CLAUDE.md wins; AGENTS.md is ignored by default.
3. No. Root AGENTS.md is enough for the simple path.

Common mistakes

• Putting instructions only in a nested folder on day one, then wondering why a root-level agent session seems under-briefed. Start at the root.
• Leaving an old empty or conflicting CLAUDE.md in the repo so Claude Code never falls through to AGENTS.md.
• Writing a novel. Long files get skimmed or truncated. Prefer sharp bullets and real commands.
• Duplicating the same rules into .cursor/rules and AGENTS.md with slightly different wording. Pick one source of truth for shared baseline rules; use .cursor/rules later for scoped extras.
• Treating AGENTS.md as a human changelog. Put narrative history in git and READMEs; keep agent instructions operational.

What's next / Going further

Thin CLAUDE.md that imports AGENTS.md

If you already rely on CLAUDE.md features, keep a thin bridge instead of duplicating content:

# CLAUDE.md

@AGENTS.md

Exact import syntax can vary by Claude Code version; the idea is: one shared body of rules in AGENTS.md, with CLAUDE.md only when you need Claude-specific extras. Prefer checking current Claude Code docs for the import form your version supports.

Bedrock / Vertex / Foundry caveat

Claude Code's changelog notes that AGENTS.md support is not yet available on Bedrock, Vertex, or Foundry. If your team routes Claude through those providers, keep a CLAUDE.md (or wait for support) rather than assuming the fallback works.

Codex global defaults

Codex can also read ~/.codex/AGENTS.md for personal defaults across repos. Use that for your own habits (tone, always-run-tests). Keep repo-specific rules in the project's AGENTS.md so teammates inherit them.

When to add Cursor .cursor/rules

Stay on root AGENTS.md until you need rules that attach only to certain paths (for example API handlers only). Then add .mdc project rules with globs. Do not migrate everything into .mdc just because the folder exists.

Why this guide exists now

• Claude Code 2.1.277 changelog: AGENTS.md support when no CLAUDE.md is present (Claude Code changelog)
• OpenAI's first-class guide: Custom instructions with AGENTS.md
• Cursor docs listing AGENTS.md beside project rules: Rules

Next Buildcamp step: once the shared brief exists, point those same agents at a real feature and keep the rules updated whenever they make the same mistake twice.