How a Huge AGENTS.md Wastes Context—and How to Fix It

The decision behind the technique

AGENTS.md is valuable because Codex reads it automatically, but automatic context is paid on every relevant turn. Repeated explanations, project history, and rarely used examples dilute the rules that matter.

Keep durable global rules at the root and move narrow instructions closer to the code they govern.

A practical step-by-step workflow

Use this sequence as a default, then tighten or expand it only when the evidence changes.

• Keep build, test, safety and definition-of-done rules at the root
• Move frontend, backend and service rules into nested files
• Replace long examples with links to maintained references
• Delete information Codex can discover from the repository

Failure boundary and finish line

Shorter is not automatically better; removing the actual test command or a safety constraint creates more rework than it saves.

Finish when the configuration is smaller, reproducible and still preserves every required safety boundary.