Write one AGENTS.md that Claude Code, Cursor, and Codex all read

I kept two instruction files in the same repo for a while: AGENTS.md for Cursor and Codex, and a short CLAUDE.md for Claude Code. The Claude sessions still wandered. The shared commands and "ask first" list in AGENTS.md might as well not have been there.

They weren't. Claude Code was never loading that file.

What each tool actually reads

This is the boring part, and it's the part that matters. The following is what the public docs said in November 2026; if you're reading this later, click through and confirm.

• Cursor reads AGENTS.md at the project root. Project rules live in .cursor/rules/*.mdc with YAML frontmatter (description, globs, alwaysApply). A plain .md file in that folder is ignored.
• OpenAI Codex reads AGENTS.md. It does not read CLAUDE.md or Cursor .mdc files by default. If you only put a convention in a Cursor rule, Codex never sees it. Combined AGENTS.md content is capped (32 KiB by default).
• Claude Code reads CLAUDE.md (and CLAUDE.local.md, and .claude/CLAUDE.md). It can also read AGENTS.md, but only when none of those CLAUDE files exist in the working directory or above it. That's the default. The docs are here: How Claude remembers your project.

So a repo that has both AGENTS.md and CLAUDE.md is, by default, three different views of "the rules":

• Cursor and Codex see AGENTS.md.
• Claude Code sees CLAUDE.md only.

If your CLAUDE.md is a stub ("be careful, follow the project style"), Claude Code is working from a stub.

The one-line fix

Put this on line 1 of CLAUDE.md:

@AGENTS.md

@path is Claude Code's import syntax. The imported file is expanded into context, up to four hops. A sentence that says "also read AGENTS.md" is not an import. Claude only opens that file if it decides to.

Keep Claude-specific notes under the import: plan mode, hooks, permissions. Shared commands, boundaries, and conventions stay in AGENTS.md.

Two related traps from the same docs:

1. CLAUDE.local.md counts. People add a gitignored local file for personal notes and accidentally hide AGENTS.md for themselves. The rest of the team is fine; you aren't.
2. You can change the default. In /config, set Project instructions to claude-md-and-agents-md if you want both files loaded without an import. The import is still the more portable fix, and it still helps in sessions that can't load AGENTS.md directly (older Claude Code, or the built-in plugin disabled).

After you change it, run /memory or /context all in a Claude Code session and confirm both files are listed. Don't assume.

What belongs in AGENTS.md

A good AGENTS.md is short. It's the facts an agent can't guess from the tree: the real commands, what "done" means here, and the lines it must not cross.

I use a shape like this:

# AGENTS.md

## Commands
|| Task | Command |
|| --- | --- |
|| Dev | `pnpm dev` |
|| Typecheck | `pnpm exec tsc --noEmit` |
|| Tests (one file) | `pnpm test path/to/file` |

## Definition of done
- Typecheck, lint, and the relevant tests were run, not assumed.
- New behavior has a test, or the reply says why it doesn't.

## Boundaries (ask first)
- Auth, payments, or permissions
- CI and deploy config
- Commands that hit production

A few habits that help:

• Write the actual command. pnpm test is useful; "run the tests" is not. If the command in the file is stale, the agent should read package.json (or pyproject.toml, or go.mod) and say so, not invent a substitute.
• Ask-first beats a long don't-list. Deleting migrations, touching billing, and hitting paid APIs belong in a short boundary section, not a lecture.
• Record the mistake the second time it happens. A "project-specific gotchas" list at the bottom is more useful than a style guide the agent already gets from the linter.
• Don't dump procedures in here. "How to review a PR" or "how to hunt a flaky test" is a multi-step workflow. That belongs in a skill, which loads when you need it, not in the file that's injected into every session.

Cursor-only details can stay in .mdc rules scoped with globs. Claude Code-only details can stay in .claude/rules/ with a paths field. Anything both tools (and Codex) should follow belongs in AGENTS.md.

Rules vs skills, briefly

Rules are always-on: project facts and conventions. Skills are on-demand: a SKILL.md in a folder, with YAML frontmatter (name, description) and the steps for one kind of job. Claude Code looks in .claude/skills/, Cursor (2.4+) in .cursor/skills/ or .agents/skills/ (and it will also read .claude/skills/), Codex in .agents/skills/.

You don't need a huge library to start. One skill that says "review this diff, rank findings, report only the checks you actually ran" already beats pasting the same paragraph into chat. If a test is flaky, a short skill that says "reproduce it 50 times, find the nondeterminism, don't add a retry" is more useful than hoping the agent does that on its own.

A starter you can copy

I put a free, MIT-licensed starter at https://github.com/hwu121380-afk/agents-md-starter. It's a lite AGENTS.md (generic sections plus Next.js, FastAPI, and Go — keep one stack and delete the others), the CLAUDE.md shim, a short writeup of the gotcha, and three sample skills: PR review, flaky-test diagnosis, and a session handoff.

It does not generate Cursor or Claude rule files, and it isn't a 24-skill pack. Copy it, fill in the command table, and check that your tools actually loaded the file.

Honest limits

Instruction files are context, not configuration. Claude Code's own docs say this plainly: if a rule has to be enforced, use a hook, a linter, permissions, or CI. A tidy AGENTS.md will still be ignored the moment a CLAUDE.md hides it, or the moment the commands in it are wrong.

Tool behavior also moves. The default described here is from the Claude Code memory page as of November 2026. Re-read that page when you upgrade.

If you want the rest of this packaged — 12 stack rule sets, Cursor .mdc and Claude Code rules generated from the same source, and a checker that flags a missing @AGENTS.md import, a CLAUDE.local.md that hides your rules, and broken .mdc YAML — that's Agent Rules Kit, $17. The on-demand half is Agent Skill Pack, also $17: 24 workflows, an installer that won't overwrite existing skills unless you pass --force, and a linter for skills you write yourself. Both are optional. The starter and the fix above stand on their own.

Not affiliated with Anthropic, Anysphere (Cursor), or OpenAI.