SSD Nodes Learn Hosting plans →
How to do am Matt ConnorBy Matt Connor · Updated 2026-10-28

How to Use Nested AGENTS.md for Monorepo

One giant root AGENTS.md fit waste context and go stale. See how nested files keep service commands, conventions, and agent guidance close to each directory.

Wetin nested AGENTS.md mean for monorepo

Nested AGENTS.md for monorepo mean say one small file dey repository root, and another file dey inside each service directory. Root file get the few rules wey apply everywhere, plus map of where the other files dey. Each service file get the commands and conventions wey apply only to that directory. Agent wey dey edit services/worker/queue.py go first read root file and worker file, and e no go waste any context for front end wey e no go touch.

You no need install anything. AGENTS.md na convention, and upstream project talk am clearly:

AGENTS.md na standard Markdown. Use any headings wey you like; the agent simply parses the text wey you provide.

Na why e good make you learn this technique well. The format no go change under you. Na placement and maintenance dey cause problem, and na you get responsibility for both.

Kí ni make one big root AGENTS.md stop to work?

One AGENTS.md wey get 600 lines for root of repository, and repository dey hold web app, background worker, plus Terraform directory, dey fail for four different ways.

E dey stale, because nobody own am. Engineer wey rename test script for apps/web dey edit files under apps/web. Root AGENTS.md no dey inside that diff, so no reviewer go see the mismatch. Six weeks later, the file still dey describe build step wey no longer exist, and the person wey cause the problem don forget the change.

E dey use context for every task. These files load when session start, before agent know wetin you wan ask. Claude Code documentation put number for am: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Codex stop merging instruction files when their combined size reach 32 KiB, wey be the default project_doc_max_bytes. Root file wey document four services dey use that budget on three of dem for every task.

Instructions start to contradict each other. Web directory need pnpm test. Worker need pytest -q. When dem dey one file, each rule correct only for some situations, so agent must guess which one apply. Claude Code docs describe the result: "if two instructions contradict each other, Claude may pick one arbitrarily." Splitting the file no mean say the other rule go comot from context. Claude Code concatenate every instruction file wey e load instead of allowing one replace another, so root file dey always there. Once agent don open files inside both apps/web and services/worker, both directory files go dey inside context together. Wetin per-directory file do na to connect each rule to the directory wey e control. Put the directory name for top of the file, like the examples below do with # apps/web, and each command still show where e apply when several files load at once. When rule wey you sure say you write clearly still dey skip, working through the reasons instruction never take effect better than rewriting the wording for the fourth time.

E dey fill with facts wey agent fit read from the code. Directory tree, dependency list, and summary of wetin each package do. Claude Code's /doctor check dey there to remove exactly these things. E "cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews" and keeps "pitfalls, rationale, and conventions that differ from tool defaults." That sentence na the best test I know to check whether any line suppose dey inside the file at all.

Agent dey read root file, or na only the nearest one?

Na here plenty people dey get the model wrong, so e make sense to quote the upstream convention instead of paraphrase am:

Put another AGENTS.md inside each package. Agents automatically read the nearest file for the directory tree, so the closest one get priority and every subproject fit ship instructions wey match am.

And for conflict:

The AGENTS.md wey closest to the edited file win; direct user chat prompts override everything.

"Get priority" dey make plenty people think say "root file no dey considered". E no be so. For tools wey implement this convention, dem read every file for the path from repository root reach the working directory and join dem together. The nearest file only win when two files talk different things about the same subject.

Codex explain the mechanism clearly: "Codex concatenate files from the root down, joining dem with blank lines. Files wey dey closer to your current directory override earlier guidance." Claude Code follow the same path. When session start, e read "every AGENTS.md and .claude/AGENTS.md for your working directory and the directories above am", and the docs explain the loading model plainly: "All discovered files dey concatenate into context instead of overriding each other." Directories below the working directory behave differently: Claude Code load a subdirectory AGENTS.md when e need am, "when Claude open a file there with the Read tool."

Two practical results follow. The root file be prefix for every session inside the repository, so treat every line there like something you go pay for a hundred times every week. A per-directory file cost nothing until the agent open a file inside that directory, so detail cheap there and na there e suppose dey.

Dem check this behaviour against the Codex and Claude Code documentation on 27 October 2026. Tools implement the convention small differently and dem fit change, so confirm the loading rules for the agent wey your team dey run.

Layout wey work for repository wey get three services

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

The root file short on purpose. E dey show where to look, and e carry only rules wey apply for every directory.

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

Na the per-directory file dey carry the details, and e fit long as much as the directory need.

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

The worker file get the same format but different content: the install command, pytest -q, why the consumer must remain idempotent, and the migration wey must run before the tests pass. Na the infra file you go use write rules wey stop agent from causing damage. Never run terraform apply. Run terraform plan and stop there, then name the state backend wey don already configure so the agent no go try initialise another one.

Notice wetin no dey inside any of these files: description of wetin each service dey do. Na humans suppose handle that one. Upstream draw the same boundary, as e talk say "README.md files na for humans: quick starts, project descriptions, and contribution guidelines", while AGENTS.md carry "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions." The difference between AGENTS.md and README wey humans dey read explain that boundary sentence by sentence, and DESIGN.md wey record why the code get that structure cover the third file, the one wey explain decisions instead of commands.

Who dey update the file when code change?

Put one rule for the root file: anybody wey change code inside a directory must update that directory's AGENTS.md for the same commit.

This one work for mechanical reason, no be cultural reason. The per-directory file dey inside the same diff with the code, so the person wey review the pull request go see both together. Root file belong to everybody, and that mean e belong to nobody. E no dey inside the diff wey anybody already dey read.

Support the rule with check for the pull request. The check go find the nearest AGENTS.md above each changed file, then report when dem no touch that file.

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

For branch wey change the API client but no touch the docs, the output go look like this:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

Make am warning instead of failure. Hard gate go teach people to add empty line to the file just to make CI green. File wey person edit only to satisfy robot worth less than no file at all. The warning give reviewer one question to ask, and na that part dey actually work.

How I fit spot AGENTS.md wey don stale?

You fit run two checks today, and you go see one symptom inside a session.

Compare the age of each file with the age of the code wey e describe. %cs prints the commit date as YYYY-MM-DD.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done
apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

If doc date dey six months behind code date, e no prove say the file wrong. E just tell you which file to read first, and na all you need from a check wey take one second.

Look for paths wey no longer exist. Documentation dey rot for one specific way: e continue describe code wey dem don delete. Every path for these files dey inside backticks, so e easy to pull dem out and test.

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

Read the output instead of wiring this one into CI. E also flags globs like src/**/*.ts and any URL wey you quote, because both get slash and neither one be file for disk. For Claude Code v2.1.283 or later, /doctor prompt-audit fit run similar pass for you: e dey look for "references to files or commands that don't exist" and files wey contradict each other, e cover your AGENTS.md files by default, and e no change anything until you ask am to apply the edits wey e propose.

The symptom inside a session. The agent reads the file, tries open src/api/client.ts because na wetin the file tell am, and the tool returns:

No such file or directory

So e do the reasonable thing and write im own fetch wrapper. Na this be the real cost of stale file. The agent no ignore your documentation. E follow the documentation, reach path wey dem delete three months ago, and rebuild code wey you already get. Skill like Ponytail, wey dey hold agent to the smallest change wey work, fit make this rebuilding instinct happen less often, but e no fit find helper wey your file point to wrong place.

Claude Code dey read AGENTS.md files?

Yes, from Claude Code v2.1.277, and the exact rule important because nested layout depend on am. We check am against documentation for 27 October 2026: "Claude Code fit read AGENTS.md as your project instructions, so repository wey don set up for other coding agents go work without adding CLAUDE.md, import, or setting." The default Project instructions value, claude-md-or-agents-md, dey read "your AGENTS.md files when you no get CLAUDE.md or CLAUDE.local.md for your working directory or above am." Nested files dey included too: Claude dey read subdirectory's AGENTS.md "when Claude open file there with the Read tool", as long as "that subdirectory no get any of the three CLAUDE.md files for itself." Those three na CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md, so personal CLAUDE.local.md for apps/web enough to stop apps/web/AGENTS.md from loading.

This one turn the old advice of putting CLAUDE.md beside every AGENTS.md into trap. If you get AGENTS.md and CLAUDE.md or CLAUDE.local.md for your working directory or above am, the docs talk say Claude dey read "Your CLAUDE.md files only". .claude/CLAUDE.md count the same way. One companion file for root wey get one Claude-specific line fit hide every AGENTS.md for the path, and personal CLAUDE.local.md do the same thing. If you want keep one, type /config and set Project instructions to claude-md-and-agents-md, wey dey read both: each directory's CLAUDE.md first, then its AGENTS.md.

Version number alone no confirm say e work. You need v2.1.277 or later, but before v2.1.281 some sessions, like ones for Amazon Bedrock or sessions with telemetry disabled, dey read CLAUDE.md files only. For some cases, the first session after you upgrade from v2.1.276 or earlier still skip AGENTS.md: the docs talk say "Claude reads AGENTS.md from your next session on". So check the session itself. For interactive session, Claude Code dey print line like no CLAUDE.md found; AGENTS.md loaded: followed by the path, and for current versions /memory dey list the file. Before v2.1.280, /memory and /context no dey list AGENTS.md wey Claude read directly, so for those versions ask Claude wetin its project instructions talk.

The import form still correct where Claude no fit read AGENTS.md directly: older version, session before v2.1.281 for Amazon Bedrock or with telemetry disabled, session where built-in plugin wey read am don disable, or project wey keep CLAUDE.md with Project instructions set to claude-md. Put this inside services/worker/CLAUDE.md:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

The symlink form correct when you no get anything tool-specific to add.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln no print anything when e succeed, so check the listing: apps/web/CLAUDE.md -> AGENTS.md. Then start session and run /context, where the loaded files go appear under Memory files. For Windows, symlink need Administrator rights or Developer Mode. Git go check committed symlink out as plain text file unless core.symlinks dey enabled, and that one leave the clone with one-line CLAUDE.md instead of your instructions. If anybody wey clone the repository dey work for Windows, use @AGENTS.md import instead. If you set either workaround before Claude Code start to read AGENTS.md by itself, you fit leave am: the docs talk say keeping the import "never makes Claude read AGENTS.md twice", and symlinked CLAUDE.md dey read once.

One trap still remain here. After /compact, project-root CLAUDE.md dey read again from disk, but nested files for subdirectories no dey inject again. Claude Code dey reload dem when e need dem, the next time the agent work with file for that directory. Documentation explain this for CLAUDE.md files and no describe compaction separately for AGENTS.md wey Claude read directly, so expect nested files with either name to behave this way. If per-directory rule stop to apply halfway through long session, na usually this cause am, and reading any file for the directory go bring am back.

Settings wey point other agents to AGENTS.md

Codex dey read AGENTS.md natively. For each level e dey check AGENTS.override.md first, so one directory fit get local override without editing the shared file. E stop merging when combined size reach 32 KiB, the default project_doc_max_bytes, and this na another reason to keep root file small.

Aider dey take am through .aider.conf.yml with line read: AGENTS.md.

Gemini CLI dey take am through .gemini/settings.json with { "context": { "fileName": "AGENTS.md" } }.

Upstream documents backward-compatible rename for repositories wey still dey use the older singular name: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

For very large monorepo, Claude Code's claudeMdExcludes setting dey skip ancestor files by path or glob. This useful when another team's directory dey above your own. Its patterns dey apply to the AGENTS.md files wey Claude Code dey read too.

Wetin make this different from agent memory, or from a skill?

These mechanisms look alike, but dem dey fail for completely different ways. So e good make we precise about which one you dey use.

Na you write AGENTS.md, you commit am to git, and you review am for pull request. E dey the same for everybody wey clone the repository. Agent memory na the agent dey write am, e dey store am outside the repository, and e dey apply only to one machine. Claude Code documentation draw the same line: CLAUDE.md hold "Instructions and rules" wey you write, while auto memory hold "Learnings and patterns" wey Claude write. The memory directory no dey share between machines. The test simple. If one fact must dey true for colleague wey just clone the repository, e no fit dey memory. How agent memory dey persist between sessions cover that part of the matter.

A skill na the third thing. AGENTS.md na context wey dey load every session; skill na procedure wey dey load when e needed. Claude Code docs give one useful rule: "If an entry is a multi-step procedure or only matters for one part of the codebase, move it to a skill or a path-scoped rule instead." The second part of that sentence na exactly wetin nested AGENTS.md dey solve. The first part na wetin agent skills dey for. And when you need the same procedure for more than one repository, share the skill across repos instead of pasting the same paragraphs inside ten different AGENTS.md files.

Upstream note say "at time of writing the main OpenAI repo has 88 AGENTS.md files". That number na the complete argument. Big repository no need bigger file. E need more small files. Each file suppose dey beside the code wey e describe, and the person wey last change that code suppose own am.

FAQ

Nested AGENTS.md dey replace root file or e dey add to am?

E dey add to am. Upstream talk say "the closest one takes precedence", wey explain wetin happen when conflict dey, no be wetin go load. Codex "concatenates files from the root down, joining them with blank lines", and Claude Code concatenates every file e find as e dey move up from working directory, instead make e override dem. The nearest file dey win only when two files give different instructions about the same subject. Write shared rules for root one time, and no repeat dem for every directory.

How big root AGENTS.md suppose be?

Make e small reach where you no go mind make dem paste am on top every request wey you make for that repository, because na so e dey happen. Claude Code documentation suggest say target under 200 lines for each file and warn say longer files "reduce adherence". Codex dey stop merging instruction files when dem reach 32 KiB combined by default. If your root file dey document four services, most of am na dead weight for any single task. Move the detail go per-directory files and leave map behind.

How I fit stop these files from becoming stale?

Put one rule for root file: anybody wey change code for a directory suppose update that directory's AGENTS.md for the same commit. Putting the file beside the code na wetin make the rule stick, because the change go enter the same pull request diff wey human dey already read. Add CI warning wey map each changed path to the nearest AGENTS.md above am, and from time to time compare git log -1 --format=%cs for each file with the same command wey you run on the directory wey e document.

Claude Code dey read AGENTS.md files?

Yes, from v2.1.277. We check am against the documentation on 27 October 2026. Claude Code dey read AGENTS.md by default when you no get CLAUDE.md or CLAUDE.local.md for your working directory or above am, and e dey read subdirectory's AGENTS.md when e open file there with the Read tool and that subdirectory no get CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md of e own. No add CLAUDE.md beside each AGENTS.md: with one for or above the working directory, Claude dey read "Your CLAUDE.md files only". If you need CLAUDE.md too, set Project instructions to claude-md-and-agents-md for /config, or put @AGENTS.md for e first line. Run /memory for a session and confirm say AGENTS.md path dey appear for the list.

Where I suppose put rule wey only matter sometimes?

No put am for AGENTS.md. That file dey load for every session, so every line inside am dey compete for attention with the request wey you actually type. Procedure wey get several steps and na only sometimes you need am suppose dey inside skill, wey dey load when e need. Rule wey apply to one directory suppose dey inside that directory's AGENTS.md. Fact wey agent fit read straight from the code, like directory tree or dependency list, suppose dey inside neither.

Dis article help you?