Root AGENTS.md owns the shared operating contract—commands, verify steps, and guardrails. Nested AGENTS.md files specialize at package or app boundaries; they do not replace the root. Keep child files short and local (package-specific verify, local don’ts). Prefer one nested level per deployable. Don’t duplicate the root novel into every package, into CLAUDE.md, or into always-on Cursor rules. This playbook is the inheritance map plus what not to duplicate—monorepo depth beyond the day-one multi-harness layout. Soft path: /free. Harness templates that assume root + nested: Agent Starter Kit ($47).
The problem you’ll actually hit
Your monorepo grew three apps and a shared package. Someone pasted the whole root encyclopedia into `apps/web/AGENTS.md`. Someone else forked verify commands in `packages/api`. Claude’s thin bridge still points at root, but Cursor alwaysApply rules restate the same stop list. Agents disagree about which test runner wins and whether approval language still applies. Official nested `AGENTS.md` support exists; what’s missing is an opinionated inheritance map—what child files inherit, what they override, and what you must never duplicate.
Day-one multi-harness layout (Claude `@AGENTS.md` bridge, Cursor adapters) lives in One AGENTS.md for Cursor, Claude Code, and Codex. This post owns the monorepo depth that post only pointed at.
Layout map (root + nested)
Treat the tree as one contract with local specializations:
/
├── AGENTS.md # root: repo-wide commands / verify / guardrails
├── README.md # humans
├── CLAUDE.md # thin bridge → @AGENTS.md (root only)
├── .cursor/rules/*.mdc # Cursor globs / alwaysApply — not a second novel
├── apps/
│ ├── web/AGENTS.md # nested: web verify, local don’ts
│ └── api/AGENTS.md # nested: api verify, local don’ts
└── packages/
└── ui/AGENTS.md # nested: package-only notes (keep short)Root owns: install/run/verify defaults, stop-before-send/publish/pay language, handoff expectations, pointers to where nested overrides live.
Nested owns: package-specific verify commands, local “don’t touch X,” path-local conventions that would confuse other packages if they lived at root.
Neither owns: secrets, human product marketing, long tutorials, Cursor-only style guides pasted as always-on rules.
Inheritance rules (what children get)
- Root is still required. Nested files specialize; they do not erase shared verify or approval stops. An agent in `apps/web` still needs the root contract for repo-wide guardrails.
- Override at the boundary. Nest at a deployable or package boundary—where verify commands actually diverge—not every folder in the tree.
- Prefer one nested level. Deep trees of `AGENTS.md` become contradictory. Fold shared rules upward into root (or a single parent) instead of copying them down three levels.
- Claude bridge stays thin and root-facing. Keep `CLAUDE.md` importing `@AGENTS.md` at root. Don’t fork a second encyclopedia per app into `CLAUDE.md`.
- Cursor rules stay adapters. Path globs and alwaysApply constraints belong in `.cursor/rules`. Portable agent contract stays in nested `AGENTS.md`—don’t paste the same novel into both.
When agents that *consume* remote MCP tools sit under this layout, auth recipe stays on the live MCP OAuth for Cursor and Claude Connect pillar—instruction contract here; Connect there.
Anti-patterns (what not to duplicate)
| Anti-pattern | Why it hurts | Do this instead |
|---|---|---|
| Nested file rewrites the whole root | Contradictory stop lists; drift on every edit | Short local override; root stays canonical |
| Same verify block in every package | One package changes; others rot | Root default + only the packages that differ nest |
| Secrets in any `AGENTS.md` | Leak surface in every harness checkout | Env / secret store per package; name vars in README |
| Fat `CLAUDE.md` per app | Two (or N) encyclopedias | Thin root `@AGENTS.md` import |
| Always-on Cursor rules = full contract | Context tax on every chat | Nested `AGENTS.md` for portable contract; rules for globs only |
| Nesting on every folder | Merge-order confusion; “which file wins?” fights | One level per deployable / package boundary |
Debug order when packages disagree: open root `AGENTS.md` → confirm nested file is only for the package you’re in → confirm it doesn’t restate root guardrails → confirm Cursor rules aren’t duplicating either file → confirm Claude still bridges root only.
Inheritance checklist
- [ ] Root `AGENTS.md` has repo-wide commands, verify, and stop-before-send/publish/pay.
- [ ] Each nested file is short, local, and sits at a real package/app boundary.
- [ ] Nested files specialize — they do not replace root.
- [ ] Nesting depth is one level per deployable (no deep contradictory trees).
- [ ] Secrets stay in env / secret stores; README documents env *names* only.
- [ ] `CLAUDE.md` imports root `@AGENTS.md`; no per-app novel.
- [ ] `.cursor/rules` handle globs / alwaysApply only — not a duplicate contract.
What the Agent Starter Kit is for
The Agent Starter Kit ($47) is aimed at production harness templates under the instruction layer—including a root + nested layout—not another “what is AGENTS.md” gloss. Use it when you want a kit-backed file map for monorepo boundaries instead of stitching vendor docs. Soft path: grab the free starter desk at /free, then the kit when you’re standardizing Cursor + Claude Code + Codex on one inheritance map.
Companion for the multi-harness day-one contract: One AGENTS.md for Cursor, Claude Code, and Codex. If remote MCP Connect is the other half of the desk, pair with the MCP Starter Kit—different job, same agent-ops shelf.
Soft next step
Ship one root contract, add nested files only where verify truly diverges, and refuse duplicate novels in Claude bridges or Cursor always-on rules. Soft ladder: /free for the starter desk, then the Agent Starter Kit ($47) when you want harness templates that assume root + nested. No rush—write the inheritance map into your own runbook either way.