AGENTS.md in a monorepo: nested files and precedence

When one file isn't enough

A single root AGENTS.md is right for most repos. In a monorepo, one root file either bloats trying to cover every package or stays general and loses the specifics each one needs. The hierarchy fixes this: many small files, each close to the code it describes.

Nearest file wins

When an agent edits a file, the closest AGENTS.md up the tree applies. Place files where the rules belong:

monorepo/
  AGENTS.md              # workspace-wide: tooling, shared conventions
  packages/
    api/
      AGENTS.md          # api: its commands, its db rules
    web/
      AGENTS.md          # web: its build, its component conventions

(For scale: the main OpenAI repo reportedly has ~88 AGENTS.md files.)

Root vs leaves

• Root: what's true everywhere — package manager, org-wide conventions, overall layout.
• Leaf: only what's specific — that package's commands, conventions, boundaries.

Don't duplicate the root

Copying shared rules into every package file recreates the drift problem. Trust precedence: state shared rules once at the root and let packages inherit them, overriding only what genuinely differs.

Keep it shallow

Two levels — root + one per top-level package — covers almost every real monorepo. If you want a fourth level, the rules probably want consolidating upward instead.

---

Free cheat sheet: the format, an annotated example, and the one-line test — AGENTS.md Cheat Sheet.

Go deeper: the full reference — cross-tool setup, the monorepo hierarchy, and a 30-day plan — AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard.

What's your monorepo AGENTS.md depth — one root file, or a tree? 👇