What belongs in AGENTS.md
Put stable project rules in AGENTS.md: package manager, build commands, test commands, code ownership boundaries, review expectations, and forbidden operations. These rules help Codex avoid rediscovering the same constraints every session.
Avoid writing temporary task details there. A one-off migration plan, a short-lived bug, or a current release decision should stay in the prompt, issue, or task document unless it becomes a lasting rule.
- Use commands exactly as maintainers expect them to be run.
- State forbidden actions directly.
- Prefer examples for non-obvious conventions.
Keep rules close to scope
A repository-wide AGENTS.md can define global behavior, while nested files can define rules for a package, app, or subsystem. This reduces conflict between unrelated parts of a monorepo.
When rules conflict, the closer rule should explain the local exception. For example, one package may require a different test command or generated-code workflow.
Review AGENTS.md like code
Bad instructions are operational bugs. If a rule is vague, outdated, or impossible to verify, it can cause repeated wrong changes. Keep the file under review when build commands, package managers, or release policies change.
A good AGENTS.md tells Codex what to do before editing, how to verify, and how to report risk. That is more useful than stylistic preferences that cannot be checked.