One AGENTS.md to rule Claude Code, Cursor and Codex

If you use more than one AI coding agent, you've probably ended up with three instruction files: a CLAUDE.md for Claude Code, a pile of .cursor/rules for Cursor, and an AGENTS.md for Codex. They start out identical. A month later one still says npm, another says pnpm, and the third forgot that tests live next to the code.

That's how instruction files drift apart. The fix is simple: make AGENTS.md the single source of truth and keep every tool-specific file thin. This post shows the layout, how each tool actually picks up AGENTS.md, and a template you can copy.

The layout

your-repo/
├── AGENTS.md            # canonical: commands, layout, conventions, definition of done
├── CLAUDE.md            # "@AGENTS.md" + Claude-only notes
├── .claude/
│   ├── settings.json    # permissions + hooks
│   ├── agents/          # subagents
│   └── skills/          # procedures that load on demand
├── .cursor/
│   ├── rules/           # .mdc rules, with the core rule pointing at AGENTS.md
│   └── cli.json         # permissions for the `agent` CLI
├── .cursorignore
└── .codex/
    ├── config.toml      # sandbox + approval defaults
    └── agents/          # custom agents

AGENTS.md holds everything every agent needs. The other files hold only what is specific to one tool: its behaviour, permissions and features.

How each tool picks up AGENTS.md

This is the part people get wrong, because the three tools load it differently.

Codex builds an instruction chain once per run. It starts with the global file (~/.codex/AGENTS.override.md or AGENTS.md), then walks every directory from the project root down to your working directory. In each one it checks AGENTS.override.md, then AGENTS.md, then any project_doc_fallback_filenames, and takes at most one file per directory. Files closer to your working directory come later, so they win when instructions conflict. The combined chain has a default size cap of 32 KiB, and Codex stops adding files once it reaches it.

Cursor supports AGENTS.md in the root and in subdirectories. Nested files combine with their parents, and the more specific instructions take precedence.

Claude Code has the catch. It reads AGENTS.md directly only when there's no CLAUDE.md or CLAUDE.local.md in the working directory or above. Once you add a CLAUDE.md, put an import at the top so both load:

# CLAUDE.md
@AGENTS.md

A personal, uncommitted CLAUDE.local.md also counts as "a CLAUDE.md exists". So even if you never create a project CLAUDE.md, adding a local one silently stops Claude reading AGENTS.md. Keep the explicit @AGENTS.md import and that can't happen.

The canonical AGENTS.md

Here's a trimmed version of the template I use. Replace the placeholders with your own stack.

# AGENTS.md

## Project snapshot
- What it is: <one sentence>
- Main language / runtime: <TypeScript 5, Node 22>
- Package manager: <pnpm>. Do not use any other package manager.
- Layout:
  - `apps/web/`: frontend
  - `apps/api/`: HTTP API (handlers in `apps/api/src/handlers/`)
  - `packages/db/`: schema + migrations

## Commands
- Install: `<pnpm install>`
- Unit tests (fast, run often): `<pnpm test>`
- Single test file: `<pnpm test -- path/to/file.test.ts>`
- Lint + types: `<pnpm lint && pnpm typecheck>`
- Build: `<pnpm build>`

## Conventions
- Named exports, no default exports.
- Errors: return `{ code, message }` objects from services; never throw raw strings.
- New code needs tests next to it (`*.test.ts`).

## Working agreement
1. Restate the task in one or two lines and list the files you expect to touch before editing.
2. Make the smallest change that solves the task. No drive-by refactors.
3. If requirements are ambiguous, stop and ask. Do not guess on behaviour.
4. Never commit secrets, tokens, or `.env*` files.
5. Do not run `git push`, `git reset --hard`, `git clean -fd`, force-pushes,
   or destructive DB commands unless explicitly asked.

## Definition of done
- [ ] Lint + types pass
- [ ] Tests pass (and a new test covers the change)
- [ ] Diff is limited to files related to the task
- [ ] Short summary: what changed, why, how it was verified, open risks

## Code Review Rules
- Flag any handler that reads request input without validation.
- Flag SQL built with string concatenation.

Why it's built this way

• Commands come first because wrong commands cause most wasted agent turns: npm instead of pnpm, or the wrong test runner. The single-file test command also saves tokens, since the agent stops running the whole suite on every iteration.
• The working agreement turns common failure modes, like silent scope creep and guessing, into explicit rules.
• The definition of done gives every agent the same exit criteria. Without it you get "Done!" while the tests still fail.
• ## Code Review Rules is a heading Codex's GitHub code review looks for, so the review guidance comes along for free.

Keep it short. Leave formatting checks to CI, not the rule file. And write instructions the agent can verify: "Run pnpm test before finishing" works better than "test your changes".

The thin files

CLAUDE.md

# CLAUDE.md: project instructions for Claude Code
<!-- Keep this file under ~200 lines. HTML comments are stripped before Claude sees them. -->

@AGENTS.md

## Claude Code specifics
- Use plan mode before touching more than 3 files.
- For searches that would flood the context, delegate to a subagent
  and ask for a summary with file paths.
- Before calling a task done, run the checks in "Definition of done"
  and paste the command output summary.

## Things that went wrong before
- Do not "fix" failing tests by loosening assertions or adding `.skip`.

Two details: imports are relative to CLAUDE.md and can nest up to four hops. Block-level HTML comments are stripped before injection, so notes for humans cost no context. Run /context to confirm which memory files actually loaded.

.cursor/rules/00-core.mdc

Cursor project rules must be .mdc files in .cursor/rules/. A plain .md file there is ignored. The always-on core rule just points to AGENTS.md and adds a few hard limits:

---
description: "Core working agreement for every Agent chat in this repo"
alwaysApply: true
---

- Follow `AGENTS.md` at the repo root for commands, layout and definition of done.
- Before editing, list the files you plan to change. Keep the diff limited to the task.
- Never read, print, or edit `.env*`, `*.pem`, `*.key` or credential files.
- Finish every task with: what changed, how you verified it (exact commands), open risks.

Stack-specific rules go in separate .mdc files that attach by globs, so they only cost tokens when a matching file is in context.

.codex/config.toml

Codex instructions come from AGENTS.md. Behaviour (sandbox, approvals, subagents) lives in config.toml:

approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[agents]
max_concurrent_threads_per_session = 4

Codex loads a project's .codex/ layers only when you trust the project.

When the agent "ignores" the rules

If an agent ignores your conventions, the cause is almost always that the rule file is too long, vague or contradictory, or wasn't loaded at all. Check before rewriting anything:

• Claude Code: /context and /memory
• Codex: /status
• Cursor: Customize → Rules

Then shorten the file, make the instructions verifiable, and remove conflicts. One canonical file makes that much easier, because there's only one place to fix.

Wrap-up

• AGENTS.md is canonical. CLAUDE.md and .cursor/rules stay thin and point to it.
• In CLAUDE.md, always add an explicit @AGENTS.md import.
• Put commands first, use verifiable instructions, and give every agent the same definition of done.
• Keep tool behaviour (permissions, sandbox, hooks) in each tool's own config, not in the instructions.

---

Free excerpt: https://lirenplr.gumroad.com/l/zocmzn

This article is adapted from the **AI Coding Agent Workflow Pack: a 37-page guide plus a drop-in template bundle (the full AGENTS.md, CLAUDE.md, all four Cursor rule types, Codex config, 10 copy-paste workflows and a security checklist). Every file name and flag was checked against the official docs in October 2026. Get it on Gumroad ($24). I post tested agent workflows as @Mars_Peakul on X.