AGENTS.md Hierarchy Playbook 2026: From Single Repo to Monorepo with Codex CLI

AGENTS.md Hierarchy Playbook 2026: From Single Repo to Monorepo with Codex CLI

Author: CodeGateway Team · Tested on 2026-05-26

TL;DR: AGENTS.md is how Codex CLI learns your project — the "system prompt" that ships with every session. It is not config. Codex builds an instruction chain from your global ~/.codex/AGENTS.md plus every AGENTS.md along the path from your git root to your current directory, concatenated in that order, capped at 32 KiB by default. The closer to your cwd, the higher the precedence. This guide covers the full lookup order, the AGENTS.override.md escape hatch most teams miss, three single-repo templates (Next.js / FastAPI / Rust), a monorepo example, side-by-side comparison with CLAUDE.md and .cursor/rules, and how to wire it through CodeGateway when api.openai.com is unreachable from your region.

Table of contents

1. Why AGENTS.md, not .codex/config.toml
2. The instruction chain — exact lookup order
3. AGENTS.override.md — the escape hatch most teams miss
4. Single-repo templates: Next.js / FastAPI / Rust
5. Monorepo playbook
6. AGENTS.md vs CLAUDE.md vs .cursor/rules
7. Subagents and AGENTS.md
8. Pairing AGENTS.md with MCP servers
9. Five common mistakes
10. Verifying what Codex actually loaded
11. Routing Codex through CodeGateway when api.openai.com is unreachable
12. FAQ

Why AGENTS.md, not .codex/config.toml

.codex/config.toml is tooling configuration — which model, which reasoning effort, which MCP servers, which hooks. AGENTS.md is behaviour instruction — what to test before declaring "done", what package manager you use, which folders Codex should never touch, what the code review checklist is.

The two answer different questions. Config tells Codex how to run. AGENTS.md tells Codex what your team expects. In practice the second one drives 80% of the agent quality gap, because it is the only knob that survives across model upgrades — when GPT-5.5 ships next month, your AGENTS.md still applies; your prompt patterns may not.

Per the OpenAI docs: "Codex reads AGENTS.md (and related files) and includes a limited amount of project guidance in the first turn of a session." It is built into the first message of the session, ahead of any user prompt.

The instruction chain — exact lookup order

Codex CLI builds the instruction chain once per session (not lazily, not cached across launches). The order is:

1. Global scope (~/.codex/ by default, or whatever CODEX_HOME points at):
   - AGENTS.override.md      ← if present, only this is used at this level
   - AGENTS.md               ← used only if the override file is absent

2. Project scope — walking from the git root *down* to your cwd:
   - For each directory along the path:
     - AGENTS.override.md
     - AGENTS.md
     - any filename listed in project_doc_fallback_filenames
   - At most one file per directory.

3. If Codex can't find a project root, it falls back to checking only the
   current directory.

The picked files are then concatenated with blank lines between them, root-first, leaf-last. "Files closer to your current directory override earlier guidance because they appear later in the combined prompt."

Two implications that bite teams the most:

• Closer wins. If your repo root says "use pnpm" and packages/legacy-yarn/AGENTS.md says "use yarn", Codex follows yarn while working inside that folder. Use this on purpose, not by accident.
• The size cap is real. project_doc_max_bytes defaults to 32 KiB. Codex stops adding files once the combined size reaches the limit, in lookup order. Crowding the global file with 28 KiB of style guidance can starve repo-specific instructions further down the chain.

Default project root is "the nearest ancestor directory containing .git". You can override with project_root_markers in ~/.codex/config.toml if your repo uses something other than git.

AGENTS.override.md — the escape hatch most teams miss

At every level — global, repo, sub-directory — Codex checks for AGENTS.override.md before AGENTS.md. If both exist at the same level, the override wins; AGENTS.md at that level is ignored.

This is how you ship team-wide standards without forking the file every contributor needs to touch:

• Commit a thorough AGENTS.md to your repo. Every dev gets it on clone.
• Each dev (or each branch) can drop a .codex/AGENTS.override.md in .gitignore to layer personal preferences without disturbing the committed file.
• For temporary work — a security drill, a perf benchmark — drop AGENTS.override.md in the working folder, run Codex, delete it afterwards. No commit, no risk of leaking the override.

Recommended workflow:

• Commit: AGENTS.md at the repo root, and one at each meaningful sub-package.
• Don't commit: any AGENTS.override.md — add AGENTS.override.md and **/AGENTS.override.md to .gitignore.

Single-repo templates: Next.js / FastAPI / Rust

A useful AGENTS.md describes intent and constraints, not commands Codex can already discover. Keep each section to 5-15 lines. Aim for 1-3 KiB.

Next.js + TypeScript + Vitest

# Repository instructions

This is a Next.js 15 app router project using TypeScript, Tailwind, and Vitest.

## Conventions
- Components: PascalCase under `components/`. Hooks: `useFoo` under `hooks/`.
- Server actions live under `app/actions/`. Never call them from useEffect.
- Use Zod for any boundary validation (forms, API inputs, env parsing).

## Test discipline
- Before declaring a change done: `pnpm typecheck && pnpm test --run`.
- New utility code requires a co-located `*.test.ts`. UI changes with logic
  require a Vitest test, not just snapshot.

## Things not to do
- Don't introduce new state-management libraries; Zustand is the only one.
- Don't add ESLint disables without a comment explaining why.
- Don't touch `src/generated/` — it is regenerated from OpenAPI on every build.

FastAPI + SQLAlchemy + pytest

# Repository instructions

FastAPI service backed by Postgres via SQLAlchemy 2.0 async. Python 3.12.

## Conventions
- Routes in `app/api/v1/`, business logic in `app/services/`, DB models in
  `app/db/models.py`. Routes are thin: parse, call service, return.
- All public endpoints require a Pydantic response_model.
- Use Alembic for any schema change. Never edit the DB by hand on dev.

## Test discipline
- Run `uv run pytest -q` before declaring a task done.
- New endpoints require at least one integration test using TestClient.
- Mock the model provider; never call the live LLM in tests.

## Performance budget
- Each request must finish in p95 < 300 ms on the dev box.
- Add a SQLAlchemy explain() trace for any new query touching `orders`.

Rust + cargo workspace

# Repository instructions

Rust workspace, edition 2024. Crates: `core`, `cli`, `server`.

## Conventions
- Public APIs return `Result<_, ServiceError>` — never `anyhow::Result` outside
  `main.rs`.
- Use `tracing` (not `log`) and structured fields, not formatted strings.
- All `unsafe` blocks need a `// SAFETY:` comment.

## Test discipline
- `cargo nextest run --workspace` must pass before any commit.
- Public API changes need a doctest demonstrating the new shape.
- Property tests for parsing code; unit tests for everything else.

## Things not to do
- Don't add new dependencies without flagging size impact in the PR description.
- Don't touch `crates/legacy/` unless explicitly asked; it is on track to be deleted.

These templates are deliberately short. The 32 KiB cap goes fast when you also have a global ~/.codex/AGENTS.md and three nested sub-package files.

Monorepo playbook

In a monorepo, the chain composes — that is the whole point. Put cross-cutting rules at the root and specifics where they specialise.

repo-root/
├── AGENTS.md                  # universal: PR conventions, security rules
├── apps/
│   ├── web/
│   │   └── AGENTS.md          # Next.js conventions
│   └── api/
│       └── AGENTS.md          # FastAPI conventions
├── packages/
│   ├── ui/
│   │   └── AGENTS.md          # design system rules
│   └── shared-types/
│       └── AGENTS.md          # type-gen workflow
└── infra/
    └── AGENTS.md              # Terraform style, secret handling

The combined prompt Codex builds when you cd apps/web/components is:

~/.codex/AGENTS.md
   ↓ (concatenated, blank-line separated)
repo-root/AGENTS.md
   ↓
apps/web/AGENTS.md

apps/api/AGENTS.md and packages/ui/AGENTS.md are not loaded — they are on a different path from your cwd. This is by design: only relevant context comes in, your token budget breathes easier.

What goes in the root:

• PR title conventions, commit-message format, sign-off rules
• Security rules: no secrets in code, log redaction list, dependency policy
• "Never push directly to main" / branching strategy
• Cross-package contracts: shared types, RPC schemas, error codes

What goes in each sub-package:

• Language / framework conventions for that subtree
• Test discipline specific to the stack
• Local "don't touch" lists (vendored code, generated artefacts)

AGENTS.md vs CLAUDE.md vs .cursor/rules

The three coding agents use different filenames for the same idea. They are not interchangeable in practice — each agent reads only its own filename — but the content discipline transfers cleanly.

For teams running more than one agent in the same repo, the practical solution is a single source of truth — say .agent-rules.md — and a tiny shell script in .git/hooks/post-checkout that symlinks it to AGENTS.md, CLAUDE.md, and the relevant .cursor/rules/*.mdc file. Diverging copies rot the second one of them does.

Subagents and AGENTS.md

Codex subagents are explicitly user-triggered ("Codex doesn't spawn subagents automatically"). The subagent runs in a separate thread you can inspect via /agent. The official Subagents page does not currently spell out whether subagents see the same AGENTS.md instruction chain as the parent — treat this as an area where the safest assumption is they inherit the parent's context, but verify before you depend on it for security-sensitive constraints.

What is documented:

• Subagent behaviour is steered via the parent prompt ("A good subagent prompt should explain how to divide the work…") and optionally per-agent config (model, model_reasoning_effort in the agent file).
• Subagents return summaries, not raw work output, to keep the main thread focused.

Practical advice: if a subagent must obey a constraint (no PII in logs, no git push --force), put it in the parent's AGENTS.md and in the subagent's task prompt. Belt and braces — the docs leave too much room for the inheritance model to change.

Pairing AGENTS.md with MCP servers

AGENTS.md is where you teach Codex which MCP tool to reach for. The MCP server is configured in .codex/config.toml; AGENTS.md tells Codex when to use it.

Example snippet for a repo with a Postgres MCP and a GitHub MCP wired up:

## Tools you have

You have an MCP server `postgres-readonly` exposing a `query(sql)` tool against
the dev database. Use it instead of guessing schema; never use it for writes.

You have an MCP server `github` for PR and issue operations. Prefer reading PR
comments and check statuses through it instead of asking the user to paste.

## Tool-use rules
- For schema questions, query `information_schema` via the postgres MCP first.
- For PR triage, fetch the PR via the github MCP, summarise check failures,
  then propose a plan.
- Never run a write SQL statement through the postgres MCP. Ask the user to run
  it themselves with a copy of the statement.

Two MCP servers + four lines of guidance change the agent's behaviour from "ask the user" to "look it up itself" on every schema question. This is the highest-leverage section in most production AGENTS.md files.

Five common mistakes

1. Writing commands instead of intent. "Run pnpm test" rots the moment you change scripts. "Run the test suite before declaring done" does not.

1. Stuffing the global file. A 28 KiB global ~/.codex/AGENTS.md is a great way to crowd repo-specific rules out under the 32 KiB cap. Keep global to ≤ 5 KiB.

1. Forgetting `.gitignore` for overrides. AGENTS.override.md is meant for personal/branch-local layers. Committing it makes the override the new normal and surprises every contributor.

1. Nested `AGENTS.md` without scope discipline. A packages/ui/AGENTS.md that talks about backend rules will load when Codex is helping you in packages/ui/ — and confuse it. Keep each file scoped to the directory it lives in.

1. No verification. Several months in, every team I've seen has at least one AGENTS.md whose rules Codex isn't loading because of a precedence quirk or a fallback misconfig. Verify quarterly (next section).

Verifying what Codex actually loaded

The simplest check is to ask Codex itself:

Show me which instruction files are active right now, in load order.

The model will read its own first-turn context and list them. Cross-check with the log:

tail -F ~/.codex/log/codex-tui.log
# or
ls -t ~/.codex/log/session-*.jsonl | head -1 | xargs head -200

If you raise project_doc_max_bytes above 32 KiB, check the log entries after the next launch — the docs note Codex stops adding files once the cap is hit, and your nested overrides may silently drop.

Routing Codex through CodeGateway when api.openai.com is unreachable

If you're behind a corporate proxy or in a region where api.openai.com returns the 451 "unsupported region" error, Codex CLI can be pointed at CodeGateway as an OpenAI-compatible drop-in. Two lines in your shell:

export OPENAI_BASE_URL=https://api.codegateway.dev/v1
export OPENAI_API_KEY=cg-...   # from your CodeGateway dashboard
codex login --skip  # skip OAuth, we set the key directly
codex

Your AGENTS.md does not change — same instructions, same chain, same 32 KiB cap. CodeGateway forwards the Responses API calls to OpenAI; the model picker, subagents, MCP, and hooks behave identically. Pricing follows the same per-token model as direct OpenAI plus a transparent tier markup; see codegateway.dev/pricing.

For teams: each developer signs in with their own key, the gateway aggregates billing, and you get one usage dashboard across the team without standing up your own proxy.

FAQ

Q: Does Codex re-read `AGENTS.md` when I edit it mid-session? No. The instruction chain is built once per session start. "Codex rebuilds the instruction chain on every run." Restart Codex (or open a new session) to pick up edits.

Q: What happens to `AGENTS.md` when I'm not in a git repo? "If no project root is found, Codex only checks the current directory." You still get the global file plus the cwd AGENTS.md, but no chain.

Q: Can I rename `AGENTS.md` to something my team already uses (`AGENT_RULES.md`, etc.)? Yes — add it to project_doc_fallback_filenames in ~/.codex/config.toml. Codex checks AGENTS.override.md, then AGENTS.md, then your fallbacks, in each directory.

Q: How do I split a 50 KiB instruction set without hitting the cap? The docs recommend "Raise the limit or split instructions across nested directories." Raising project_doc_max_bytes to 65536 (64 KiB) is the easy fix; splitting by directory is the durable one because nested files only load when you're working in that subtree.

Q: Is AGENTS.md trusted by Codex automatically? The Advanced Configuration page is silent on whether AGENTS.md is gated by the project-trust mechanism that .codex/config.toml is. Assume it is not — but treat any AGENTS.md you didn't write as untrusted code. Read it before letting Codex follow it.

Q: Should I use AGENTS.md or in-chat system instructions? Both, for different purposes. AGENTS.md is the permanent expectations; in-chat instructions are this-task overrides. The latter trump the former for the current turn but don't persist.

Resources

• Codex models reference
• Custom instructions with AGENTS.md (official guide)
• Codex CLI features
• Codex Subagents (official)
• CodeGateway docs