AGENTS.md and CLAUDE.md in a Monorepo: Where Instruction Files Go and Which One Wins

The first AGENTS.md in a monorepo is easy. The second one is where teams get into trouble. Someone adds apps/web/AGENTS.md with the web app's test command, someone else adds a rule to the root file that contradicts it, and a week later an agent working in apps/web runs the wrong suite and nobody can say which file it listened to.

The answer depends on the agent, because the two most common instruction formats resolve nested files in opposite ways. The AGENTS.md spec says agents read the nearest file in the directory tree and "the closest one takes precedence." Claude Code's memory documentation says the opposite for CLAUDE.md: every file from the root down to your working directory is concatenated, not overridden. Scale is not hypothetical either: the AGENTS.md site notes that OpenAI's main repository contains 88 AGENTS.md files.

This guide covers how each format resolves nested files, a layout that works for both, what belongs at each level, and how to keep a dozen instruction files from drifting into contradiction.

Why one root file stops working#

A single root instruction file works until the repo has more than one way of doing things. A typical monorepo has a Next.js app, a worker, a few shared packages, and maybe a Python service, each with its own test command, lint config, and conventions. Put all of that in one file and you get two problems.

The file gets long. Claude Code's docs recommend targeting under 200 lines per CLAUDE.md, because longer files consume more context and reduce adherence. A root file that documents five apps blows through that quickly, and every session pays for all five apps even when you are working in one. We made the general case in managing AI agent context without the bloat.

The instructions start to conflict. "Run npm test" is true at the root and wrong inside the Python service. An agent reading one flat file has to guess which rule applies where, and guessing is exactly what the file was supposed to prevent.

Nested files fix both — as long as you know how your agents combine them.

How AGENTS.md and CLAUDE.md resolve nested files#

flowchart TD
  subgraph Repo["monorepo/"]
    R["AGENTS.md or CLAUDE.md at the root"]
    subgraph Web["apps/web/"]
      W["apps/web/AGENTS.md or CLAUDE.md"]
      F["src/page.tsx being edited"]
    end
  end
  F --> A1["AGENTS.md agents: use the closest file, apps/web/AGENTS.md"]
  F --> C1["Claude Code: root CLAUDE.md, then apps/web/CLAUDE.md, both in context"]

The difference matters more than it looks:

The consequence: with AGENTS.md, a nested file must be complete for its subtree, because the root file may not be read at all. With CLAUDE.md, a nested file should contain only the delta, because the root file is always in context above it and repeating it wastes tokens.

Claude Code also reads AGENTS.md now. Since v2.1.277, it loads a repository's AGENTS.md files as project instructions when there is no CLAUDE.md in the working directory or above it, including subdirectory AGENTS.md files as it works in them. If a CLAUDE.md exists, it wins by default, unless you import AGENTS.md from it or switch the project instructions setting to load both.

A layout that works for both#

The layout below holds up for teams using several agents at once. It keeps one source of truth per level and avoids writing anything twice:

monorepo/
├── AGENTS.md                  # repo-wide: layout, commit rules, boundaries
├── CLAUDE.md                  # one line: @AGENTS.md
├── apps/
│   ├── web/
│   │   ├── AGENTS.md          # web: commands, framework conventions
│   │   └── CLAUDE.md          # one line: @AGENTS.md
│   └── worker/
│       └── AGENTS.md          # worker: commands, queue conventions
├── services/
│   └── billing-py/
│       └── AGENTS.md          # Python: uv, pytest, typing rules
└── .claude/
    └── rules/
        └── migrations.md      # paths: ["**/migrations/**"]

1. Put repo-wide rules in the root AGENTS.md. Repository layout, commit and PR conventions, security boundaries, anything that is true in every directory.

2. Give each deployable its own AGENTS.md. Its setup, test, and lint commands, its framework conventions, and its own boundaries. Write it so it stands on its own, since AGENTS.md agents may read only this file.

3. Make each CLAUDE.md a one-line import. @AGENTS.md pulls the sibling file in. Claude Code resolves imports relative to the file containing them and allows up to four hops of nested imports, so this pattern stays cheap.

4. Use path-scoped rules for cross-cutting concerns. A migrations policy or an API design rule that applies to matching files anywhere in the repo belongs in .claude/rules/ with a paths: glob, so it loads only when Claude touches those files. For AGENTS.md agents, repeat the rule in the nearest AGENTS.md for each affected package.

5. Skip what you don't own. In a large monorepo, other teams' instruction files can end up in your context. Claude Code's claudeMdExcludes setting skips specific files by path or glob.

If you are starting from nothing, the AGENTS.md generator and the CLAUDE.md generator share the same sections, so you can produce the root file and each package file from one form.

What goes at each level#

The hardest judgment call is placement. A rule in the wrong file is either invisible where it matters or noise everywhere else.

Two placement rules cover most cases. Commands live with the code they run, because the command is wrong one directory over. Boundaries live at the widest scope where they are true, because an agent that never sees a boundary cannot respect it.

For the content of each file, the advice in AGENTS.md explained and how to write the perfect CLAUDE.md still applies: imperative bullets, runnable commands in fenced blocks, the most important rule near the top.

The trap: files that contradict each other#

Nested instruction files fail quietly. Nothing errors when the root file says pnpm and a package file says npm. Claude Code's docs are blunt about it: if two rules contradict each other, Claude may pick one arbitrarily. AGENTS.md agents avoid that particular problem by reading only the closest file, and replace it with another: a package file written before a root rule changed never learns about the change.

Contradictions creep in three ways:

• A root rule changes and the package files do not. The team moves from Jest to Vitest, updates the root file, and three package files still say jest.
• A package is renamed or moved. Its instruction file moves with it, but the root file's layout section still points at the old path.
• Commands drift from package.json. Someone renames the test:unit script, and every instruction file that mentions it is now wrong.

The common thread is that instruction files describe code, and code changes without anyone reopening the files that describe it. It is documentation drift with a sharper edge: a stale README misleads a person who can notice, a stale AGENTS.md misleads an agent that will run the wrong command with total confidence.

Keeping a dozen files honest#

Hand-maintaining ten instruction files is the kind of chore that works for a month. Moxie Docs takes the other approach: it indexes the repository, discovers the conventions and verified commands the code actually uses, and serves them to coding agents over the Moxie MCP server, so an agent working in apps/web asks for that package's current commands instead of trusting a file someone wrote in March. Before committing, an agent can call moxie.review_change to catch convention breaches and docs the change makes false, and when docs fall behind the code, Moxie opens a Cleanup PR for a human to review. It is a companion to your instruction files, not a replacement — you can see it on one repository with the free plan. For the broader strategy, see context engineering for coding agents.

Measuring whether it's working#

• Agents run the right command the first time. Watch the first test or build command an agent runs in each package; a wrong one points at a stale or missing file.
• No two files disagree. Search for every command mentioned across instruction files and compare them to the scripts that actually exist.
• Each CLAUDE.md stays under about 200 lines. Past that, move content into a package file or a path-scoped rule.
• Every package that ships has its own file. A deployable without one inherits guesses.
• Instruction files change when the code does. If a package's scripts changed this quarter and its AGENTS.md did not, check it.

None of these need a dashboard.

Frequently asked questions#

Can you have multiple AGENTS.md files in one repository?#

Yes. The AGENTS.md spec explicitly supports nested files for monorepos: place one in each package, and agents read the nearest file in the directory tree, so the closest one takes precedence. Large repositories use dozens; OpenAI's main repository has 88.

Does Claude Code read AGENTS.md?#

Yes, since v2.1.277. Claude Code loads a repository's AGENTS.md files as project instructions when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. If you also keep a CLAUDE.md, make it a one-line @AGENTS.md import so both tools read the same content.

How does Claude Code handle nested CLAUDE.md files?#

It concatenates them rather than overriding. Files in the working directory and every directory above it load at launch, ordered from the root down, so the closest file is read last. CLAUDE.md files in subdirectories load on demand when Claude reads files in those directories.

Should every package in a monorepo have its own AGENTS.md?#

Every package with its own commands or conventions should. Shared libraries that follow the root conventions exactly can rely on the root file, but anything with a separate test command, language, or framework needs its own file, written to stand on its own for agents that only read the closest one.

How do I stop instruction files from contradicting each other?#

Keep each rule at exactly one level, make package files hold only what differs from the root, and check commands against the scripts that actually exist whenever build tooling changes. Tools that derive commands and conventions from the code itself remove the need to keep copies in sync by hand.

The short version#

In a monorepo, put repo-wide rules in the root AGENTS.md, give every deployable its own file that stands on its own, turn each CLAUDE.md into a one-line import, and use path-scoped rules for concerns that cut across packages. Remember that AGENTS.md agents read the closest file while Claude Code stacks them all, and write each file accordingly. The layout is the easy part. The hard part is that every one of those files describes code that keeps moving — and an instruction file that was true in March is a confident wrong answer in September.