Does a child AGENTS.md replace or merge the parent?

Treat it as specialize-at-the-leaf, not delete-the-root. Nested files override local verify / don’ts for that package; shared stops, secrets policy, and repo-wide commands stay at root. Prefer one nested level per deployable.

What belongs only at repo root vs package leaf?

Root: shared commands, verify, guardrails, secrets hygiene. Leaf: package-local verify, deployables, don’ts that only apply in that app/package. Don’t push secrets or “always” walls down the tree.

How do Cursor / Claude / Codex resolve nested AGENTS.md?

Each harness walks the tree from the working context upward/downward per its own rules — document the intended inheritance map in-repo rather than assuming identical merge semantics. Link the multi-harness post; don’t invent product claims.

When is a symlink CLAUDE.md → AGENTS.md still wrong in a monorepo?

When leaf packages need different Claude-facing guidance than the root contract, or when a symlink hides which file is authoritative. Prefer an explicit nested AGENTS.md + clear ownership over a clever symlink that fights package boundaries.

What should never be duplicated down the tree?

Secrets, conflicting “always” rules, and copy-pasted walls that drift per package. One source of truth at root for shared policy; leaves only specialize.

Draw the inheritance map once. Companion: nested-agents-md-monorepo for setup steps — this post is the map, not a rewrite.

Monorepo AGENTS.md inheritance map

Root AGENTS.md is the shared operating contract—commands, verify, guardrails. Nested files specialize at the leaf; they do not delete the root. Parent to child means: shared stops and secrets policy stay at root; package-local verify and don’ts live one level down per deployable. Root owns shared install/run/verify defaults, stop-before-send/publish/pay, and secrets hygiene. Leaf owns package-local verify and deployable-only don’ts. Prefer one nested level per deployable. Don’t duplicate secrets, README marketing, or conflicting always-rules down the tree. This post is the inheritance map—not a rewrite of the setup playbook.

Layout diagram (conceptual)

Treat the tree as one contract with local specializations:

text

/
├── AGENTS.md                 # root: repo-wide commands / verify / guardrails
├── README.md                 # humans (not the agent SoT)
├── CLAUDE.md                 # thin bridge → @AGENTS.md (root-facing)
├── .cursor/rules/*.mdc       # Cursor globs / alwaysApply — not a second novel
├── apps/
│   ├── web/AGENTS.md         # leaf: web verify, local don’ts
│   └── api/AGENTS.md         # leaf: api verify, local don’ts
└── packages/
    └── ui/AGENTS.md          # leaf: package-only notes (keep short)

Root owns: shared install/run/verify defaults, stop-before-send/publish/pay, secrets hygiene, pointers to where leaves specialize.

Leaf owns: package-local verify, deployable-only don’ts, path conventions that would confuse other packages at root.

Neither owns: secrets values, human product marketing, conflicting “always” walls copied down the tree.

Setup steps and anti-pattern depth: Nested AGENTS.md monorepo playbook. Multi-harness day-one: One AGENTS.md for Cursor, Claude Code, and Codex. Human vs agent boundary: What belongs in AGENTS.md vs README.

Inherit vs override (map rules)

Layer	Inherits	Overrides	Never duplicates
Root	—	—	Secrets, README novel, Cursor-only style walls
Leaf (apps/, packages/)	Root commands, shared stops, secrets policy	Local verify, local don’ts	Root encyclopedia, conflicting always-rules
Claude bridge	Root `@AGENTS.md`	Nothing per-app	Fat `CLAUDE.md` per package
Cursor `.cursor/rules`	—	Globs / alwaysApply only	Full portable contract

Specialize-at-the-leaf, don’t delete-the-root. Prefer one nested level per deployable. Deep contradictory trees lose—fold shared policy upward.

When harnesses disagree about merge order, document the intended map in-repo rather than assuming Cursor, Claude Code, and Codex share identical semantics. See the multi-harness post; don’t invent product claims.

Anti-patterns (map view)

Copy-paste walls — same root novel in every package until verify drifts.
Conflicting “always” rules — leaf “always X” fighting root “always not X.”
Secrets in any `AGENTS.md` — leak surface in every harness checkout.
Symlink cleverness that hides ownership — when packages need different Claude-facing guidance, a root `CLAUDE.md` → `AGENTS.md` symlink fights boundaries. Prefer explicit nested `AGENTS.md` + thin root bridge: Symlink CLAUDE.md to AGENTS.md — when / when not.

Debug order: open root → confirm leaf is only local verify/don’ts → confirm no secrets → confirm Claude still bridges root → confirm Cursor rules aren’t a duplicate novel.

What the Agent Starter Kit is for

The Agent Starter Kit ($47) ships harness templates that already assume root + nested inheritance—not another “what is a monorepo” gloss. Soft path: /free for the starter desk; Cheat Sheet for the skim checklist mindset; kit when you’re standardizing the map across Cursor + Claude Code + Codex.

Companion for setup steps: Nested AGENTS.md monorepo playbook. Multi-harness layout: agents-md-cursor-claude-codex. Boundaries: agents-md-vs-readme.

Soft next step

Draw the inheritance map once—root contract, one leaf per deployable, nothing duplicated that should stay shared. Soft ladder: /free for the starter desk, then the Agent Starter Kit ($47) for harness templates under that map. Setup playbook: nested-agents-md-monorepo; multi-harness: agents-md-cursor-claude-codex; boundaries: agents-md-vs-readme; symlink decision: symlink-claude-md-agents-md.