Spec file
Splitting agent instructions by directory in a monorepo
Per-directory AGENTS.md and CLAUDE.md in a monorepo: an example tree, then load scope, nesting and conflict rules per tool. Per official docs, not tested.
Different directories in a big repo often need different rules, such as one set of commands for the frontend and another for the backend. This page starts with an example tree we made up, then compares Claude Code, generic AGENTS.md (the agents.md site) and Cursor in three columns: when each file is read, which one wins when nested, and whose rule applies on conflict. Cells the official pages do not cover say "Not stated officially".
- Verified
- · Not tested by us
- Applies to
- Tools
File locations
| Path | Scope | How it is read |
|---|---|---|
./AGENTS.md | Repository root | Claude Code: read at session start when there is no CLAUDE.md in the working directory or above; Cursor: project root; agents.md: repository root[1][2][3] |
./CLAUDE.md | Project root (or ./.claude/CLAUDE.md) | Claude Code: CLAUDE.md files in the working directory and above are read at launch; those in subdirectories load on demand[2] |
frontend/AGENTS.md | Subdirectory (path style taken from the Cursor page sample) | agents.md: nearest file in the directory tree is read; Cursor: applied automatically when working with files in that directory or its children[1][3] |
When to use
- One repository holds several sub-projects and you want one instruction file per directory.[1][3]
- You use Claude Code and want to know when a subdirectory's AGENTS.md or CLAUDE.md gets read.[2]
- Your team mixes Claude Code and Cursor users and you want to see how each handles nested files.[1][2][3]
When not to use
- The repository is small and a single root file is enough, so no split is needed.[1]
- You need Codex loading details: this page does not cover them, see the section "Codex is left out for now".[1]
- You need rules that are strictly enforced: the Claude Code docs say these files are context, not enforced configuration.[2]
Example directory tree
The tree below is an example we designed to explain the rules. It is not an official sample. The root has only AGENTS.md, apps/web has only AGENTS.md, and services/api has both AGENTS.md and CLAUDE.md, to show three different cases.[1][2][3]
Version basis: neither the agents.md site nor the Cursor rules page states a document or format version, so what this page says about them is based on the pages as read on the verification date, 2026-10-28; the Claude Code page says reading AGENTS.md directly needs v2.1.277 or later, which is a minimum feature version, not a document version.[1][2][3]
monorepo/
├── AGENTS.md
├── apps/
│ └── web/
│ └── AGENTS.md
└── services/
└── api/
├── AGENTS.md
└── CLAUDE.md
The tables below read against this tree. The Claude Code column assumes you start in monorepo/ and that neither monorepo/ nor its parent directories contain any CLAUDE.md.[2]
Load boundary for each file
| File | Claude Code | Generic AGENTS.md (agents.md site) | Cursor |
|---|---|---|---|
| monorepo/AGENTS.md | By default read only when there is no CLAUDE.md in the working directory or above; if so, every AGENTS.md in the working directory and above is read at session start. | Placed at the repository root. | Supported in the project root. |
| apps/web/AGENTS.md | Under the same condition, and only if that subdirectory has no CLAUDE.md of its own, it is read when Claude opens a file there with the Read tool. If you start Claude inside apps/web, it is read at session start. | The site says the agent reads the nearest file in the directory tree. | Applied automatically when working with files in that directory or its children, combined with parent AGENTS.md files. |
| services/api/AGENTS.md | The documented condition is that the subdirectory has none of the CLAUDE.md files, and services/api has one, so by that condition it is not read by default. Details for this case under the Project instructions setting that reads both are not stated officially. | Same: the AGENTS.md closest to the edited file wins. | Same directory-scoped rule as apps/web; the official page does not mention a CLAUDE.md in the same directory, so this is not stated officially. |
| services/api/CLAUDE.md | Not read at session start; loaded once when Claude reads, writes or edits another file in that subdirectory. | Not stated officially (the site does not mention CLAUDE.md). | Not stated officially (the official page does not mention CLAUDE.md). |
Also: reading AGENTS.md directly needs Claude Code v2.1.277 or later; if a CLAUDE.md imports it with @AGENTS.md, both take effect.[2]
Nesting priority and whose rule wins
| Question | Claude Code | Generic AGENTS.md (agents.md site) | Cursor |
|---|---|---|---|
| Which nested file wins | No override: all discovered files are concatenated into context, ordered from the filesystem root down to the working directory, so the one closest to where you launched is read last. | The closest AGENTS.md takes precedence. | Nested files are combined with parent directories, and more specific instructions take precedence. |
| Two instructions conflict | The docs say that if two instructions contradict each other, Claude may pick one arbitrarily, and recommend removing conflicting content. | The closest AGENTS.md to the edited file wins. | More specific instructions take precedence; across rule sources the order is Team Rules, Project Rules, User Rules, and earlier sources win on conflict. |
| Explicit user prompt in chat | Not stated officially; the docs only say these files are context, not enforced configuration. | The site says explicit user chat prompts override everything. | Not stated officially. |
| Skipping irrelevant files | The claudeMdExcludes setting skips given CLAUDE.md files by path or glob; the docs also say claudeMdExcludes patterns apply when AGENTS.md is read. | Not stated officially. | Not stated officially. |
Codex is left out for now
The agents.md site lists OpenAI Codex among the contributors to AGENTS.md, but under this site's source rules the official Codex AGENTS.md page has no usable final address at the moment, so Codex loading details are to be confirmed and are not written here. The "Generic AGENTS.md" column above reflects only what the agents.md site says, not Codex's actual behaviour.[1]
Points to watch when splitting
- Keep only directory-specific content in a subdirectory file and leave shared conventions in the root file. The agents.md site's approach is one more AGENTS.md inside each package.
- If you serve Claude Code and other tools, note that Claude Code by default does not read AGENTS.md when a CLAUDE.md exists; to share one file, import it from CLAUDE.md with @AGENTS.md.
- Do not write contradicting instructions at different levels: Claude Code does not guarantee which one it follows.
- When other teams' CLAUDE.md files get picked up, exclude them locally with claudeMdExcludes.
Sources
All links are official pages; verification dates are listed per source, and links point to the version checked.
Related tools
Claude Code
Anthropic's coding agent for reading codebase context, editing files, running commands and assisting development work.
Cursor
A coding agent for understanding repositories, planning features, changing code, and reviewing diffs.