TL;DRThe fix for big repos isn't a thicker AGENTS.md — it's a thinner, split one: the map and global rules at the root, module details in their own directories. An r/codex field post walked this path end to end; here it is in seven steps.
Sources SOURCES
Distilled from public community discussions. This page only breaks them down and verifies — it never reposts the original; opinions belong to their authors.
Facts FACTS
Check these claims against the listed sources. For allowance mechanics, first-party account displays outrank community summaries.
- AGENTS.md is an open pure-Markdown standard under the Linux Foundation, and it can be placed in layers — per directory — inside a repo.
- The r/codex field post works in two steps: first a static repo analysis that produces a repo map, then the context split across multiple layered AGENTS.md files. The map comes first because everything downstream hangs off it.
- Official best practices back the direction: persist long-lived instructions into AGENTS.md — standing conventions belong there, not one-off tasks.
- Community guides (Codersera among them) have systematically covered the AGENTS.md spec and examples; layered splitting holds up at the spec level.
Concepts CONCEPTS
Not everything said in a community thread is a fact — each concept carries its nature label. Read the label first.
The agent reads but never writes, producing a repo map: directory responsibilities, entry files, dependency relations. The opening move of the r/codex field post — cheap, safe, and it produces the artifact every later step edits.
Global conventions at the root, module-specific rules in their subdirectories — instructions travel with the module, and the agent picks up module rules by proximity instead of by luck. Adopted by the field post and supported by community guides.
The community umbrella term for agents reading the wrong files or editing the wrong modules in large codebases. Widely reported; cause analyses and fix effectiveness are mostly personal experience.
Claims like "after splitting, the agent's first-shot accuracy on the right file clearly improved" rest on single data points so far; controlled public data is missing.
Step-by-step SOP STEP BY STEP
- 01Read-only analysis
Start
codexand declare in the first message: "this session is read-only, no changes." Have it produce the repo map — directory responsibilities, entry files, module dependencies. - 02Fact-check the map
Correct it against your own understanding of the codebase. You are the ground truth here; the map is only as good as this pass, and a wrong module relationship left in it will mislead every session that reads it afterward.
- 03Root gets the map layer
Write the verified overview and directory index into the root AGENTS.md, plus the global conventions: commands, style rules, no-go zones.
- 04Modules get their layers
Drop a short AGENTS.md into each core module, holding only that module's specific rules — no repeats of global content. Short is the point: a module file that duplicates the root just multiplies the places you'll forget to update.
- 05Point the way at kickoff
Open new tasks with "read the root and the target module's AGENTS.md first" — one sentence of directions beats a scavenger hunt through the tree, and it keeps navigation authority with you.
- 06Validate on a fresh module
Raise a small request in a module you didn't touch, and see whether it finds the right files and follows the local rules.
- 07Update with refactors
After a big refactor merges, refresh the affected modules' map and layers in the same pass — a stale map is more dangerous than no map. Put the refresh on the same checklist as the merge itself.
Keep reading NEXT
Want today's verdict? Back to the live radar.