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? 👇
Top comments (2)
Monorepos are where AGENTS.md rules become real architecture, not just a prompt file. Precedence matters because different packages often have different test commands, deploy risks, and ownership rules. The agent should know which local instruction wins before it edits anything.
Agreed, and I'd push it one step further: in a monorepo the interesting design decision isn't just "which file wins" but which kind of rule should be allowed to be overridden at all.
Test commands, lint config, local build steps — those are fine as pure overrides. Closest AGENTS.md to the file being edited wins, same mental model as a cascading .eslintrc or .gitignore. No ambiguity, no need for the agent to reconcile anything.
But deploy risk and ownership rules are a different category. Those usually want to be additive, not overridable — a root-level "this package touches billing, get a human review" shouldn't be something a package-level file can quietly cancel out. If a nested file can silently override a safety constraint from the root, you've built a way for a rule to disappear exactly where it matters most, and nobody notices until the postmortem.
So the practical split I'd recommend: local/operational rules cascade and override cleanly; risk/ownership rules cascade and accumulate. And the agent should say out loud which precedence path it resolved, not just silently pick one — that's the same visibility argument as the command log from the other thread. Precedence you can't see is precedence you can't trust.