How to Layer AGENTS.md for Real Agent Work

It is tempting to treat AGENTS.md like a readme with a stronger name. That misses the point.

In Codex, instruction files are read before work begins. They become part of the instruction chain that shapes how the task understands its job. The official Codex guide describes that chain as global guidance plus project files from the repository root down to the current working directory.

That makes AGENTS.md valuable context. It also makes it a poor place for every detail anyone has ever learned about the domain. A Practical Architecture for Reliable Multi-Agent Systems places instruction layers inside a wider system of roles, ownership, and return.

I use it as a short operating layer: identity, responsibility, key constraints, and pointers to the material that changes more often. The detailed procedure belongs in a runbook. The deep explanation of a system or tool belongs in a source guide.

This is one practical part of building an agent from coordinated roles in Codex. The goal is not a clever prompt. It is to give every manager, endpoint, and worker the right context without making every task carry the whole organization in its input.

Codex builds a layered instruction chain

Codex first checks the global profile in ~/.codex, then walks from the project root to the task’s current directory. It includes one instruction file per directory and applies nearer files later, so the most specific guidance wins. In one directory, AGENTS.override.md takes priority over AGENTS.md. The combined instruction files have a default 32 KiB limit. Those are documented discovery rules, not a convention I invented.

That means a manager task and a reviewer task can share broad rules without sharing the same identity.

~/.codex/AGENTS.md                         global defaults
  -> repository-root/AGENTS.md             shared project rules
     -> domains/search/manager/AGENTS.md   manager identity and development work

     -> domains/search/operating/AGENTS.md shared live-agent rules
        -> runtime-endpoints/reviewer/AGENTS.md
                                               reviewer-specific rules

The manager and operating projects are siblings. A task started in the manager project loads the manager branch. A task started in the reviewer directory loads the operating branch and the reviewer file. It should not quietly inherit the manager’s developmental identity.

This is why the current working directory matters. The same Codex model can behave like a manager, a domain owner, or a reviewer because the task begins in a different project path with a different instruction chain.

Put each kind of instruction at the right level

The important rule is not “put more instructions deeper in the tree.” It is “put an instruction at the narrowest level where it is true.”

Role-specific files should reflect real responsibility

An expanded development team may have a domain owner, planner, implementer, tester, and reviewer. Each role needs a different local view of the work. This is an example of a topology that has earned several standing roles, not a requirement for a small agent.

• The domain owner owns the product request. Its file says how to select the other roles, integrate their returns, preserve open questions, and send the final result back through the public route.
• The planner turns the request into a small plan with assumptions, affected areas, and checks that will prove the work is complete.
• The implementer makes the change in the right project and records what changed. It does not mark its own work accepted.
• The tester runs the named checks, reports what actually passed or failed, and does not quietly weaken a test to make the result green.
• The reviewer compares the request, plan, change, and test evidence. It can reject a weak result and send specific gaps back to the domain owner.

Those are real differences in responsibility. A single generic AGENTS.md cannot make them clear without becoming large and contradictory. Start with a standing role only when it has a recurring job that needs continuing identity; When an Agent Needs to Be a Service, Not a Chat gives that decision test.

Each persistent role should therefore have a matching local AGENTS.md, role definition, bootstrap, registry row, and model profile. If a role is a fresh worker rather than a persistent endpoint, give it a focused task prompt and the operating-project instructions. Do not pretend it has a standing identity it does not have.

Keep AGENTS.md short by linking out

A small instruction file can still route an agent to the detailed material it needs.

Reviewer endpoint instructions

## Own
Review the proposed change against the accepted plan and the evidence.

## Do not
Approve a change merely because tests pass. Do not change production settings.

## Read when needed
- `../../runbooks/release-validation.md` before reviewing a release path.
- `../../source-guides/jira.md` when checking ticket status or workflow rules.

## Return
Send the domain owner a verdict, the evidence checked, and exact gaps to resolve.

The file tells the reviewer when to read something and why. It does not reproduce the release runbook or the Jira guide.

A runbook is an operational procedure: respond to a failed deployment, triage a stalled ticket, validate a release, or recover a connector. A source guide explains a system the agent may use: the current Jira workflow, an API, a repository subsystem, or a data source. Those documents can be longer, change independently, and receive their own review.

This division keeps the always-loaded layer focused. It also stops unrelated tool detail from consuming attention in every turn.

Use overrides carefully

AGENTS.override.md is useful when a task needs a more specific rule at one directory level. Codex checks it before the ordinary AGENTS.md in that directory, so the ordinary file there is ignored when an override exists. The official documentation spells out that precedence.

That makes overrides powerful and easy to misuse.

Use an override for a short, intentional replacement: a sensitive migration, a temporary experiment, or a special compliance rule. Do not use it as a second permanent operating manual. If a rule should last, fold it back into the normal file once the work is understood.

The same applies to nested files. A reviewer-specific instruction should sharpen the operating rules, not reverse unrelated global safety or delivery rules. If the files conflict, a future maintainer has to guess which context was meant to win.

Verify the chain from the real working directory

Do not assume a file was loaded because it exists.

The official Codex guide suggests asking Codex to summarize its current instructions or list its active instruction sources from the target directory. It also notes that a new run or session rebuilds the chain. Use that check when you add a nested file or an override.

For a persistent endpoint, make that verification part of creation:

1. Start the task in the intended saved project and endpoint directory.
2. Have it report the instruction files it loaded and the role it believes it owns.
3. Check that the model, working directory, service interface, and bootstrap match the registry entry.
4. Run a small route proof before sending real work.

This catches a common failure: a reviewer task starts from the operating-project root, misses its local reviewer instructions, and behaves like a generic agent. The task exists, but it does not have the identity you designed.

Treat instruction files as part of the agent design

An AGENTS.md file is not just documentation for a person who joins later. In Codex, it is part of the context that creates the agent’s working identity.

Keep the global file broad. Keep the project file shared. Give the domain manager a distinct development posture. Give each persistent endpoint a small, local role file. Link outward to runbooks and source guides when the agent needs procedure or tool knowledge.

That layering lets one agent have several coordinated roles without giving every role the same brain.