agents-md monorepo memory

AGENTS.md in a Monorepo: The Precedence Rules Nobody Wrote Down

Codex walks root-down. Claude Code walks cwd-up. AGENTS.override.md trumps AGENTS.md at the same level. The published rules disagree enough that you can ship a correct layout and still hit the wrong file.

jordan · May 22, 2026 · 6 min read

A platform team I talked to spent ninety minutes debugging why Codex kept running pnpm test in their payments service when the team had written pnpm test --filter=@org/payments in services/payments/AGENTS.md. The root AGENTS.md said pnpm test. Codex concatenated both. The leaf appeared last in the prompt, so on paper it should have won. It didn't. The root phrased its rule as a directive ("always run the full suite before pushing") and the leaf phrased its rule as a fact ("the payments service uses a filtered test run"), and the model picked the more confident sentence. That is the agents.md monorepo problem in 2026: the published precedence rules across Codex, Claude Code, and the agents.md spec disagree enough that you can hit this even when your file layout is correct.

AGENTS.md is what your agent reads on every turn. Skills (the SKILL.md format Knack publishes) are what it reaches for when it needs a procedure. The rest of this piece is about the AGENTS.md side in a multi-package repo.

What each tool actually does

Three runtimes matter: Codex, Claude Code, and tools that follow the agents.md spec verbatim (OpenCode, Aider, Cursor in AGENTS mode). They don't behave the same.

Codex walks root-down. Starting at the repo root, it concatenates every AGENTS.md on the path to your cwd, joining with blank lines. The Codex docs: "Files closer to your current directory override earlier guidance because they appear later in the combined prompt." Codex checks AGENTS.override.md at each directory before AGENTS.md, including ~/.codex/ for global rules. Concatenation stops at project_doc_max_bytes, default 32 KiB.

Claude Code walks cwd-up. From the memory docs: "Claude Code reads CLAUDE.md files by walking up the directory tree from your current working directory, checking each directory along the way for CLAUDE.md and CLAUDE.local.md files." Subdirectory files under cwd are not loaded eagerly; they get pulled in on demand when Claude reads files in those subdirectories. Claude Code reads CLAUDE.md natively. If your repo uses AGENTS.md, use a one-line CLAUDE.md containing @AGENTS.md, or a symlink.

The agents.md spec itself says only this: "Agents automatically read the nearest file in the directory tree, so the closest one takes precedence." That sentence, quoted in issue #53 when a user asked whether files merge or the nearest wins outright, is ambiguous. Codex chose concatenation. Some implementations chose nearest-only. The spec didn't pick a side.

Two practical consequences:

For Codex, the leaf wins on average because it appears last, but a confidently worded root rule can still drown out a hedged leaf rule. Phrasing matters.
For Claude Code, files above your cwd are always loaded; files below are loaded only when you touch a file in that subtree. Editing services/api/handlers.go does not pull in services/web/AGENTS.md.

AGENTS.override.md and the same-directory override

AGENTS.override.md is a Codex extension, not part of the agents.md spec. At any directory level, Codex checks the override before AGENTS.md and uses it if present. It's a same-directory swap. There is no magic precedence across the tree.

Codex issue #11838 (February 2026) documents $REPOBASE/AGENTS.override.md being silently ignored under certain CLI flags. Issue #15421 (March 2026) covers the same problem in ~/.codex/. Both are still open. If you rely on overrides in CI, test that they are being read in your Codex version.

Datadog took a different route. Their DEV.to post (Simon Boudrias, September 2025) uses AGENTS.local.md, gitignored, for per-developer customization, and the root file tells the agent: "If present, prioritize instructions inside @AGENTS.local.md." Routing is explicit in prose, so override precedence stops mattering.

The 32 KiB cap and why nesting matters

Codex's project_doc_max_bytes defaults to 32 KiB across all concatenated AGENTS.md files combined. Not per file. Combined. If your root AGENTS.md is 28 KiB of org-wide policy, your service-level files get 4 KiB and a prayer. Codex walks root-down and stops once the cap is reached, so the leaves get truncated first.

This is the real argument for nesting. A 60 KiB single-root AGENTS.md doesn't work; Codex drops everything past 32 KiB and gives no warning. The fix is to push specifics down into per-service files. Mercari's engineering post (October 2025) goes further: their root AGENTS.md is mostly references, linking to @docs/commands.md, @docs/code-style.md, @docs/architecture.md, @docs/authentication.md, and @docs/testing.md. The root file stays under a kilobyte. Detail lives behind references.

A monorepo layout that actually holds up

After eighteen months of watching teams shuffle these files around, here is the shape I keep ending up at:

repo/
  AGENTS.md                   # org-wide, under 4 KiB
  services/
    api/AGENTS.md             # service-specific
    web/AGENTS.md
    db/AGENTS.md
  infra/AGENTS.md
  .agents/
    testing.md                # shared references
    deploys.md

At the root, put rules that apply everywhere without qualification: the language and frameworks the repo uses, the commit-message convention, the policy that secrets never go into source, the link to your architecture doc. Keep it short. If you have to think about whether a rule applies to all services, it does not belong here.

At each service, put what only that team knows: the exact test command with filters, the local dev startup sequence, deployment quirks, the database the service owns, the on-call handle. The phrasing rule matters here. State things as facts about this service ("the api service runs migrations via make migrate-up"), not as global imperatives. When Codex concatenates root-first and the leaf wins, the leaf is then more tightly scoped than the root, and the model treats it that way.

Consider the prompt's test case: "do not run migrations in production without approval." Where does it go? At root, not in services/db/. The rule is about running migrations against production, which can happen from any service that can reach the prod database. A services/db/AGENTS.md file only gets read when cwd is inside services/db/. If an agent is editing services/api/migrations/0042_add_index.sql, the db service's AGENTS.md will not be in context under Claude Code's cwd-up walk. Cross-cutting safety rules go at root and cost root-budget.

The exception is a service-level AGENTS.override.md that strengthens a root rule for one service. If services/payments/ needs the production-migration rule to also block staging migrations, that goes in services/payments/AGENTS.override.md, not the regular AGENTS.md, so it is impossible to miss when someone edits the payments tree.

Failure modes that bite

The root rule contradicted at the leaf. A team writes "we use vitest" at the root, then services/legacy/ uses jest. The leaf says "this service uses jest." Codex concatenates root-down, the leaf wins on paper, but if the root says "always run pnpm vitest" as an imperative and the leaf says "this service is on jest" as a description, the model often runs vitest anyway. Write root rules conditionally ("by default, services use vitest") or move framework choice into a per-service fact list.

The override on the wrong branch. AGENTS.override.md is git-tracked unless you gitignore it. Teams check overrides into feature branches and forget; when the branch merges, the override propagates to main and quietly changes behavior across every Codex session. Either gitignore overrides (Datadog's AGENTS.local.md pattern) or treat them as reviewable artifacts with a CODEOWNERS entry.

The lazy-loaded leaf that never loads. Claude Code does not eagerly load subdirectory CLAUDE.md files. If your agent is planning at the repo root, it will not see services/api/CLAUDE.md until it reads a file there. Teams write architectural rules in service files expecting the planner to consider them, then watch the planner ignore them. Put planning-relevant constraints at root.

The 32 KiB cliff. Codex drops everything past the cap and says nothing. Run wc -c $(find . -name AGENTS.md) periodically. When the sum approaches 24 KiB, factor.

What to do tomorrow

Audit your repo: find every AGENTS.md and CLAUDE.md, sum the bytes, check whether you're over 24 KiB combined. If you are, factor. Move single-service imperatives out of root. Pick one phrasing convention (commands vs facts) per file. Stop using AGENTS.override.md for anything you can't afford to lose to a silent-skip bug.

The agents.md spec will probably get a v1.1 that nails down the precedence ambiguity (issue #135 proposes exactly this). Until then, your layout has to survive three runtimes reading the same files three different ways. Keep the root small, keep the leaves declarative, and put production-safety rules at the root where every cwd can see them.