h6nk
← Back to writing

How to Structure AGENTS.md in a Monorepo

March 31, 2026·7 min read·agentic-engineeringmonorepoaideveloper-experiencearchitecture

As coding agents become normal infrastructure, teams are running into a new architecture problem:

instruction files need architecture too.

A single AGENTS.md works fine in a small repo. In a big monorepo, it turns into the same kind of failure mode as any oversized shared abstraction: too much responsibility, too much noise, and too much irrelevant information loaded into the wrong place.

If you dump every team workflow, every build command, every migration warning, and every subsystem quirk into one root file, you have not created a better guidance system. You have created prompt smog.

The better pattern is simple: global defaults, root routing, local specificity.

That is the part most teams miss. The root file should not be the whole handbook. It should be the dispatcher.

TL;DR

If I had to explain this like you are five:

  • the root AGENTS.md should say where to go
  • the local AGENTS.md files should say what to do in that area
  • the shared docs should hold reusable rules that multiple teams need
  • the agent should only load the instructions relevant to the part of the repo it is touching

The mistake is putting the whole company handbook in one root file.

The better pattern is:

root routes, local specializes, shared docs de-duplicate

That keeps context small, behavior predictable, and instructions relevant.

The Real Cost of a Bloated Root File

Instruction files are not free. Every extra paragraph competes with the actual task.

In practice, a bloated monorepo AGENTS.md creates four problems at once:

  • it consumes context window budget
  • it pulls attention toward irrelevant rules
  • it increases the chance of contradictory guidance
  • it makes the agent less reliable in the exact places where specificity matters

An agent fixing a bug in a small UI package does not need instructions for warehouse backfills, mobile release trains, payments rollback policy, or infrastructure rotation procedures. Loading all of that is not just inefficient. It actively lowers quality.

This is the same rule good systems design already teaches:

  • global concerns belong globally
  • shared concerns belong in shared modules
  • local concerns belong near the code
  • routing belongs at the boundary

AGENTS.md files should follow the same shape.

What the Public Guidance Is Pointing Toward

The tooling ecosystem is not fully standardized yet, but the direction is pretty clear.

OpenAI Codex documents a hierarchical discovery model: a global instructions file, then repository instructions, then nested instructions along the path of the current working directory, with more local files applied later in the chain. That strongly favors small layered files, not one giant monorepo manual. Their guide is here: Custom instructions with AGENTS.md – Codex.

The broader AGENTS.md ecosystem says roughly the same thing. The Agent Experience concept page recommends concise repository files, optional subdirectory files for monorepos, and keeping instruction bytes small because they count against context.

Datadog has one of the clearest practical writeups I have seen: use the root file as a router, not as a wall of policy. Their article is here: Steering AI Agents in Monorepos with AGENTS.md.

That routing idea is the key design move.

The Pattern That Actually Scales

For a large monorepo, the cleanest structure is usually three layers:

  1. global instructions
  2. repo-root router
  3. local subtree instructions

Global Instructions

These live outside the repo, in the tool home directory — for example ~/.codex/AGENTS.md.

This is where default working style belongs:

  • response style
  • approval posture
  • minimal-diff preference
  • testing habits
  • review stance

What does not belong here:

  • product architecture
  • repo-specific commands
  • team workflows
  • service-specific rules

Think of the global file as a personal operating profile, not a company playbook.

Root AGENTS.md as Router

This is the most important file in the monorepo, and it is also the one most likely to be overstuffed.

The root file should answer a narrow set of questions:

  • What is true everywhere in this repository?
  • What package manager and workspace conventions apply globally?
  • If I am working in payments, mobile, or infra, where do I read next?
  • If I am making a schema or release change, which shared docs matter?

That means the root file should contain things like:

  • monorepo-wide invariants
  • package manager basics
  • shared safety rules
  • routing pointers to deeper instructions
  • references to reusable shared docs

What it should not contain:

  • every team’s workflow
  • every service’s architecture
  • duplicated local rules
  • long essays for subsystems the current task never touches

If the root AGENTS.md reads like an internal wiki page, it is already too big.

Local Project or Subtree AGENTS.md

These belong close to the code:

  • apps/mobile/AGENTS.md
  • services/payments/AGENTS.md
  • packages/design-system/AGENTS.md

This is where the high-value local rules belong:

  • local commands
  • local invariants
  • local architecture boundaries
  • test expectations
  • sharp edges like “never touch this without also updating that”

If a rule only matters inside one subtree, it belongs there — not at the repo root.

Progressive Disclosure Beats Front-Loading Everything

The right instruction architecture is really just progressive disclosure for engineering context.

Load only what the current task actually needs:

  • the global file stays small
  • the root file routes
  • the local file specializes
  • shared docs get pulled in only when relevant

This is the same reason good user interfaces hide complexity until it matters. The goal is not to withhold information. The goal is to avoid spending attention on the wrong information too early.

A Practical Layout

A monorepo that follows this pattern might look like this:

repo-root/
├── AGENTS.md
├── .agents/
│   ├── testing.md
│   ├── migrations.md
│   └── release.md
├── apps/
│   ├── mobile/
│   │   └── AGENTS.md
│   └── web/
│       └── AGENTS.md
├── services/
│   ├── payments/
│   │   └── AGENTS.md
│   └── search/
│       └── AGENTS.md
└── packages/
    └── ui/
        └── AGENTS.md

In that layout:

  • the root file tells the agent where to go next
  • subtree files define local contracts
  • .agents/ holds reusable cross-cutting guidance

That shared .agents/ directory is especially useful for concerns like:

  • testing strategy
  • migration rules
  • release checklists
  • observability expectations
  • security review requirements

That is much better than copying the same testing paragraph into fifteen different subtree files.

What a Root File Should Actually Look Like

A good root AGENTS.md is short, operational, and slightly boring.

Something like:

  • use pnpm
  • prefer focused tests for touched packages
  • do not run full monorepo builds unless necessary
  • for payments work, read services/payments/AGENTS.md
  • for mobile work, read apps/mobile/AGENTS.md
  • for database changes, read .agents/migrations.md
  • for shared test policy, read .agents/testing.md

That is enough.

The root file is there to orient and route, not to narrate the entire organization.

What Small Projects Inside the Monorepo Need

Small projects inside a monorepo should absolutely get their own AGENTS.md when they have real local constraints.

Most of those files only need four things:

  1. scope
  2. local commands
  3. critical invariants
  4. a few high-value rules

For example:

  • applies to services/payments/**
  • run pnpm --filter payments test
  • preserve idempotency in webhook handlers
  • do not mock settlement ledger behavior in integration tests
  • update docs/payments-flows.md when payout behavior changes

That is a useful local contract.

What that file does not need to repeat:

  • monorepo package-manager rules
  • generic git conventions
  • universal testing philosophy already defined elsewhere
  • company-wide engineering culture notes

Local files should be specific, not comprehensive.

The Fastest Way to Pollute Context: Duplication

One of the easiest ways to degrade agent behavior is to duplicate the same instructions across multiple files.

A common version looks like this:

  • a detailed AGENTS.md
  • a CLAUDE.md that repeats most of it
  • another tool-specific file that repeats both again

That wastes tokens, muddies precedence, and overweights repeated instructions in the merged prompt.

If you need multi-tool compatibility, wrappers are cleaner than duplication.

For example:

  • AGENTS.md contains the real shared instructions
  • CLAUDE.md just says “Read @AGENTS.md”

That gives you compatibility without multiplying instruction bodies.

Treat Instruction Files Like Part of the Platform

The healthiest way to manage agent guidance is to treat it like code:

  • keep it modular
  • keep it close to where it applies
  • avoid duplication
  • update it when reality changes
  • keep interfaces clear
  • optimize for composition

A monorepo instruction system is not just documentation. It is part of the engineering platform.

If the instruction architecture is bad, the agent experience will be bad too.

A Good Default Policy

If I were setting a default policy for a big monorepo, it would look like this:

Global file

Only personal or universal working style defaults.

Root monorepo file

Only:

  • repo-wide invariants
  • routing map
  • shared entrypoints
  • references to shared docs

Local subtree files

Only:

  • rules specific to that subtree

Shared .agents/ files

Only:

  • reusable cross-cutting concerns

Tool-specific files

Prefer wrappers over duplicated instruction bodies.

That pattern scales, keeps context lean, and makes agent behavior much more predictable.

Final Takeaway

The right way to structure AGENTS.md in a giant monorepo is not to centralize every detail. It is to centralize navigation and decentralize specificity.

If there is one rule worth remembering, it is this:

Root AGENTS should route. Local AGENTS should specialize. Shared docs should de-duplicate.

That is how you give small projects inside a giant monorepo the instruction precision they need without dragging the entire repository into every task’s context window.

Sources

← Back to writing