AGENTS.md: give a coding agent useful project instructions
Neaptide · September 6, 2026 · 7 min read
What to put in AGENTS.md, where Codex looks for it and how to check that rules are applied. Includes a concise example and a scope diagram.
On this page
When an agent repeatedly edits the wrong folder or suggests a test command that does not exist, repeating yourself in chat gets tiring. Put lasting project agreements in AGENTS.md, a Markdown file for agent instructions. Its value is the context an agent cannot reliably infer from the code.
Start with observable rules: where content belongs, which check applies and what completion means. “Write good code” barely narrows the choice. “Preserve published article URLs and check the build” gives the agent a decision it can act on.
Separate project rules from other documentation
| Location | Purpose |
|---|---|
| README | Human setup and project orientation |
| AGENTS.md | Persistent project working agreements |
| Skill | A reusable procedure such as research or review |
| Task message | The current request and any specific exception |
Link to existing documentation and say when to read it. Duplicating every setup instruction creates several places to update when a command changes.
A concise example for a content site
These paths and the build command exist in our site. Check and adapt them before using the example elsewhere. The download is a .txt file; save your adapted version as AGENTS.md in the intended directory.
# Working in this project
- Read package.json and neighbouring files before editing.
- Articles live in content/blog/articles, not in interface dictionaries.
- Preserve a published article slug unless the task requires a URL change.
- Run npm run build after content changes.
- For new logic, run the relevant checks from scripts.
- Report completed checks and remaining limitations.Do not add npm test just because another template includes it. Your package may have no such script. Match verification to the change rather than requiring a full audit for every caption edit.
How Codex discovers instructions
At startup, Codex reads global instructions, then project instruction files along the path from the project root to its current working directory. Within each directory, it checks AGENTS.override.md before AGENTS.md and uses at most one of them. Instructions closer to the working directory refine the earlier guidance. Other agents may load instructions differently, so check their documentation separately.
Add a nested file when a section has genuinely different commands or conventions. Keep shared rules at the root and avoid repeating them throughout the tree.
Check behaviour, not just acknowledgement
- Check the filename and the working directory for the task.
- After editing instructions, start a fresh run and ask which files and rules apply.
- Request a small real change and inspect the edited paths and commands.
- If a rule is missed, check conflicts and override files, then clarify the wording.
Before editing, list the applicable instruction files, working directory and checks relevant to this task. Then make the change and show the evidence that it works.An accurate summary is useful for diagnosis, but it does not prove compliance. Inspect the actual work. Codex also documents a combined size limit for project instructions; shorten an oversized file instead of assuming every line is loaded.
Keep technical controls outside the prose
Writing “do not access secrets” does not restrict file access. Writing “run the tests” does not set up automated checks. Use AGENTS.md to explain how work should be done, and configure access permissions, branch protection and continuous integration (CI) separately. Do not put real credentials in examples.
Update the file when the project changes. Add rules for concrete recurring problems, test them on a later task and remove obsolete ones. The goal is fewer guesses, not a history of every previous mistake.