What goes in AGENTS.md?

The portable operating contract for agents across harnesses: commands, verify steps, guardrails, handoffs — not product marketing prose, not secrets, not novel-length tutorials.

What goes in CLAUDE.md?

Prefer a thin bridge that imports @AGENTS.md (or the documented import). Don't maintain a second full encyclopedia that drifts from AGENTS.md.

What goes in `.cursor/rules`?

Cursor-only constraints: short alwaysApply / glob rules under .cursor/rules/*.mdc. Don't paste the whole AGENTS.md into always-on rules.

Symlink CLAUDE.md to AGENTS.md?

Symlinks can work but break across machines and checkouts. Prefer an explicit import/@ bridge so the relationship is visible in git.

README vs these three?

README is for humans. AGENTS.md is for agents. CLAUDE.md and .cursor/rules are harness adapters — keep them thin.

Where do nested monorepo overrides go?

Optional nested AGENTS.md at package/app boundaries for short local verify/don'ts. Root stays canonical; nested stays local. Full precedence notes: /blog/agents-md-cursor-claude-codex.

Draw the file map once, start at /free, then /products/agent-starter-kit ($47) for harness templates under that map. Cheat Sheet OK for the pocket checklist.

AGENTS.md vs CLAUDE.md vs `.cursor/rules` — what goes where

AGENTS.md is the shared portable operating contract (commands, verify, guardrails). CLAUDE.md is a thin bridge that imports that contract—prefer @AGENTS.md, not a second encyclopedia. .cursor/rules holds Cursor-only globs and alwaysApply constraints. README stays for humans. Put the shared truth in one place; keep harness adapters thin. Soft path: draw the map, start at /free, then the Agent Starter Kit ($47) when you want harness templates under it. Cheat Sheet OK for the pocket checklist mindset. This page is the decision tree. The full layout, nested overrides, and kit framing live on the companion pillar One AGENTS.md for Cursor, Claude Code, and Codex (/blog/agents-md-cursor-claude-codex)—read that when you need the recipe; use this when you only need “what goes where.”

Decision tree (pick a lane)

Ask one question, then stop adding files:

Will more than one harness read this? → Root `AGENTS.md`. Shared contract only.
Does Claude Code need a project entry? → Thin `CLAUDE.md` that imports `@AGENTS.md` (or the import form your Claude Code version documents). Do not fork the novel.
Is this Cursor path-scoped style, safety, or alwaysApply? → Short `.cursor/rules/*.mdc` with globs. Not a paste of `AGENTS.md`.
Is this for humans (product story, install overview)? → `README.md`. Agents don’t own the marketing voice.
Is this a multi-step on-demand workflow? → Skill territory (see Cursor rules vs skills)—not always-on rules and not a second contract file.

If two files would say the same thing, delete one. Drift is the failure mode this map exists to prevent.

File map (kit layout)

text

/
├── AGENTS.md                 # portable contract: run / verify / guardrails / handoffs
├── README.md                 # humans only
├── CLAUDE.md                 # thin bridge → @AGENTS.md
├── .cursor/rules/*.mdc       # Cursor-only globs / alwaysApply
└── apps/…/AGENTS.md          # optional nested override (short, local)

File	Owns	Does not own
`AGENTS.md`	Commands, verify steps, approval stops, handoff pointers	Product copy, secrets, Cursor-only style dumps
`CLAUDE.md`	Import / bridge to the contract	A second full rulebook that drifts
`.cursor/rules`	Glob-scoped or alwaysApply adapters	The whole operating contract always-on
`README.md`	Human story and install overview	Agent verify/guardrail encyclopedias

Debug order when harnesses disagree: open root `AGENTS.md` → confirm Claude bridge imports it → confirm Cursor rules aren’t duplicating it → check nested override only for the package you’re in. Full nested-precedence notes stay on the AGENTS.md pillar.

Symlink or `@` import?

Prefer an explicit `@AGENTS.md` import (or your Claude Code documented import) in a thin `CLAUDE.md`. The relationship stays visible in git; contributors see one source of truth.

Symlinks *can* work on some machines. They also break on others—Windows clones, CI checkouts, contributor setups that don’t preserve links. Import is the stabler team default. Don’t maintain two long files “in sync by hand”; that’s how Cursor, Claude, and Codex start arguing about verify commands.

Cursor-only rules location

Put Cursor-only constraints in **`.cursor/rules/*.mdc`**—short rules scoped by path glob, or a small alwaysApply set when every chat must see a hard stop.

Do: “In `apps/web/**`, use this test runner.”
Don’t: Paste the entire `AGENTS.md` into always-on rules so every session pays the full context tax.

If remote MCP Connect is the other half of the desk (agents that *consume* tools), keep instruction layout here and auth on the live MCP OAuth for Cursor and Claude Connect pillar—different job, same shelf.

What the Agent Starter Kit is for

The Agent Starter Kit ($47) packs production harness templates under this instruction layer—`AGENTS.md` plus thin adapters—not another “what is AGENTS.md” gloss. Soft path if you’re not buying yet: /free for the starter desk; Cheat Sheet for the skim file-map mindset; kit when you’re standardizing Cursor + Claude Code + Codex on one contract.

Soft next step

Ship one root `AGENTS.md`, bridge Claude with `@AGENTS.md`, and keep Cursor rules thin. Soft path: /free → Cheat Sheet mindset for the map → Agent Starter Kit ($47) when you want the harness pack. Deep layout and nested overrides: the companion AGENTS.md pillar. No rush—write the map into your own runbook either way.