AGENTS.md、CLAUDE.md 與 .cursor/rules 比較：為 Cursor、Claude Code 和 Codex 共用一份規則檔

If your team uses more than one coding agent, you've probably got three files saying the same thing slightly differently. Here's what each tool actually reads, according to its own docs, and a setup that keeps one source of truth.

What each tool reads

Codex (docs) reads AGENTS.md. It checks ~/.codex for a global file, then walks from the repo root down to your working directory, taking at most one file per directory (AGENTS.override.md wins over AGENTS.md). Files closer to you appear later and override earlier ones. Combined size stops at project_doc_max_bytes, 32 KiB by default.

Cursor (docs) supports project rules in .cursor/rules/ as .mdc files with description, globs and alwaysApply frontmatter. A plain .md file in that folder is ignored. It also reads AGENTS.md in the root and in subdirectories, as a simpler alternative.

Claude Code (docs) reads CLAUDE.md (or .claude/CLAUDE.md), plus .claude/rules/*.md with optional paths: frontmatter. Recent versions (v2.1.277+) read AGENTS.md directly, but only if there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it. Adding a CLAUDE.md silently stops it reading AGENTS.md, unless you change the Project instructions setting.

The setup

1. Put shared rules in AGENTS.md. All three tools read it.
2. If you need Claude-only rules, import rather than copy. Claude's docs recommend a CLAUDE.md like:

   @AGENTS.md

   ## Claude Code
   Use plan mode for changes under `src/billing/`.

It loads AGENTS.md once, then the extra lines. (A symlink ln -s AGENTS.md CLAUDE.md also works, but Claude's docs warn it's awkward on Windows.)

1. Use .cursor/rules/*.mdc only for scoped rules, e.g. a rule with globs: src/components/**/*.tsx. Don't duplicate your general rules there.
2. Nest for monorepos. services/payments/AGENTS.md is picked up by Codex and Cursor for that folder.

What to put in it

Both Cursor's and Claude's docs say the same thing: short and concrete beats long and vague. Claude's docs suggest under 200 lines per CLAUDE.md; Cursor's say under 500 per rule.

• Build, test and lint commands, exactly as typed.
• Conventions that differ from defaults ("we use pnpm", "no default exports").
• Where things live ("API handlers are in src/api/handlers/").
• Things the agent got wrong twice.

Skip style guides your linter already enforces.

A starter AGENTS.md

# AGENTS.md

## Commands
- Install: `pnpm install`
- Test: `pnpm test` (run before every commit)
- Lint: `pnpm lint`

## Conventions
- TypeScript strict. Named exports only.
- Never edit files in `dist/` or `generated/`.

## When unsure
- Read the nearest existing example before writing new code.
- Ask before adding a production dependency.

Check it loaded

• Codex: codex --ask-for-approval never "Summarize the current instructions."
• Claude Code: /context or /memory and look for the file.
• Cursor: open Customize → Rules and see what's active.

The rules file tells the agent how your repo works. The prompt still decides what it does. I put together 15 free prompts for debugging, refactors and tests that work across all three tools: grab them here.