Know which guidance is actually loaded
Codex first reads global guidance, then project instructions along the path to the current working directory. AGENTS.override.md takes precedence over AGENTS.md at each location. Closer rules can refine or override earlier ones. In nested projects, check the starting directory and discovered instruction chain rather than only the repository-root file.
Write concise rules with verifiable outcomes
A useful project file lists valid build and test commands, important directories and acceptance criteria. Explain how to reproduce a form error or which language variants must be checked. Remove obsolete commands. Long generic warnings add little when the next step and meaningful evidence are unclear.
Combine guidance and enforcement
Text alone does not enforce write protection, network limits or merge rules. Combine guidance with sandboxing, repository protection and appropriate automated checks. Use a fresh test task to find the applicable rule and run the intended test. Evidence is not that AGENTS.md exists, but that rules, tools and observed behaviour agree.
Decision matrix
| Decision point | Proceed when | Stop when |
|---|---|---|
| Assignment and inputs | Documented: scope, commands, tests, protection boundaries and definition of done. | Scope, data or accountability remains unresolved. |
| Repeatability | A new example assignment finds the applicable rules and leads to the correct test commands and a reviewable acceptance decision. Parent and local instructions are consistent within the affected scope. | There is only an unevaluated demo without acceptance evidence. |
| Maintenance and boundaries | Owner, approval, fallback and next review date are defined. | AGENTS.md is guidance, not a security boundary. Critical permissions and mandatory checks need additional technical or organisational enforcement. |
Keep it verifiable
Primary sources
- OpenAI: Custom instructions with AGENTS.mdSource checked:
- OpenAI: Agent approvals and securitySource checked:
