One canonical agent instruction file beats three half-synced rulebooks. Put the shared operating contract in root AGENTS.md—commands, verify steps, guardrails—not novel-length prose. Point Claude at it with a thin CLAUDE.md that imports @AGENTS.md. Keep Cursor .cursor/rules for globs and alwaysApply only. Nested files override at package boundaries. Human README stays for humans. When you want harness templates under that instruction layer, start with the free desk on /free or go straight to the Agent Starter Kit ($47).
The problem you’ll actually hit
You run Cursor on one machine, Claude Code on another, Codex in CI or a third desk. Each harness grows its own instruction pile: a fat `.cursorrules`, a long `CLAUDE.md`, a Codex-facing note that drifted last sprint. Agents disagree about verify commands, approval stops, and where secrets live. Official agents.md, Cursor, and Codex docs explain the format. What’s missing for multi-harness teams is one opinionated layout—what belongs where—so you stop maintaining three encyclopedias.
If you’re also wiring remote MCP that those agents consume, see the live companion on MCP OAuth for Cursor and Claude Connect—auth recipe there; instruction contract here.
Canonical layout (shared operating contract)
Treat root `AGENTS.md` as the portable contract every harness should read:
/
├── AGENTS.md # canonical: commands / verify / guardrails
├── README.md # humans: product story, install overview
├── CLAUDE.md # thin bridge → @AGENTS.md
├── .cursor/rules/*.mdc # Cursor-only globs / alwaysApply
└── apps/…/AGENTS.md # optional nested override (short, local)Put in AGENTS.md: how to run, how to verify, what not to do, handoff expectations, stop-before-send/publish/pay language.
Keep out of AGENTS.md: product marketing copy, secrets, long tutorials that belong in docs or skills, duplicate Cursor-only style guides.
Short beats clever. If a section needs a novel, link out or move it to a skill—don’t paste the whole guide into always-on context.
Claude bridge: `CLAUDE.md` imports `@AGENTS.md`
Don’t fork the encyclopedia into `CLAUDE.md` and `AGENTS.md`. Prefer a thin Claude file that imports the canonical contract—commonly `@AGENTS.md` (or the import form your Claude Code version documents). One source of truth; Claude gets a bridge, not a second novel.
Symlinks can work on some machines and break on others (Windows, CI checkout quirks, contributor clones). Import is the stabler default for teams.
Cursor adapters: `.cursor/rules` for globs only
Cursor still needs project rules for path globs and alwaysApply constraints. That is adapter territory—not a second copy of `AGENTS.md`.
- Do: short `.mdc` rules scoped by glob (e.g. “in `apps/web/**`, use this test runner”).
- Don’t: paste the entire operating contract into always-on rules so every chat pays the full tax.
When a workflow is multi-step and on-demand, that is skill territory—see the planned companion on Cursor rules vs skills (and Spec Kit). Keep this post’s rule: Cursor rules adapt; `AGENTS.md` owns the shared contract.
Optional handoff contract
For agent-ops desks that pass work between design → implement → verify, add short handoff notes under something like `docs/handoffs/` (names are yours). Point at them from `AGENTS.md` so every harness knows the expected artifacts—not three different chat rituals. Keep handoffs checklists, not essays.
Nested monorepo precedence (pointer)
Root `AGENTS.md` holds repo-wide commands, verify steps, and guardrails. Nested `AGENTS.md` files override at package or app boundaries. Keep nested files short and local—package-specific verify, local don’ts—not a rewrite of the root contract.
Deep monorepo playbooks (merge order edge cases, tooling that only reads one level) can wait for a dedicated nested-files post. For day-one: root canonical, nested local, no conflicting encyclopedias.
What belongs vs doesn’t (checklist)
| Belongs in AGENTS.md | Belongs elsewhere |
|---|---|
| Install / run / verify commands agents must use | Human product story → `README.md` |
| Guardrails and approval stops (send / publish / pay) | Secrets → env / secret store |
| Handoff expectations between roles | Multi-step reusable workflows → skills |
| Pointers to nested package overrides | Path-scoped style/safety → `.cursor/rules` |
| “Stop and ask” language for irreversible actions | Long tutorials → docs, not always-on context |
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.
What the Agent Starter Kit is for
The Agent Starter Kit ($47) is aimed at production harness templates under the instruction layer—`AGENTS.md` plus adapters—not another “what is AGENTS.md” gloss. Use it when you want a kit-backed file map instead of stitching vendor docs. Soft path if you’re not ready to buy: grab the free starter desk at /free, then come back to the kit when you’re standardizing Cursor + Claude Code + Codex on one contract.
If remote MCP Connect is the other half of your desk, pair this with the MCP Starter Kit—different job, same agent-ops shelf.
Soft next step
Ship one root `AGENTS.md`, bridge Claude with `@AGENTS.md`, and keep Cursor rules thin. When you want the harness pack under that contract, use /free for the starter desk, or the Agent Starter Kit ($47) for production templates. No rush—write the file map into your own runbook either way.