Three sessions in, you notice you keep typing the same sentences. Use pnpm, not npm. Run the tests before saying it is done. Do not touch the generated folder.
Write them down once instead.
What AGENTS.md is
A plain file in your project. Codex reads AGENTS.md files before doing any work, so whatever is in them shapes every task without you repeating it.
There is no special syntax. Headings and bullet points are fine. The Codex docs' own example looks like this:
# AGENTS.md
## Repository expectations
- Run npm run lint before opening a pull request.
- Document public utilities in docs/ when you change behavior.
Where Codex looks, and in what order
When it starts, Codex builds a chain of instructions:
- Your global file. In your Codex home folder,
~/.codex/AGENTS.md. Preferences that should follow you into every repository go here. - The project, folder by folder. Starting at the project root — usually the root of the Git repository — Codex walks down to the folder you are in and picks up an AGENTS.md in each one along the way.
- Root first, nearest last. The files are joined in that order. Something closer to your current folder appears later, so where two files disagree, the closer one wins.
Two details matter in practice. A folder can hold an AGENTS.override.md, which Codex reads instead of that folder’s AGENTS.md. And Codex builds this chain once, when it starts: after editing a file, restart Codex in the folder you are working in.
Quick check
You started Codex, then added a rule to AGENTS.md. It keeps ignoring the rule. What is the likely reason?
Let it draft one
Inside a session, /init generates an AGENTS.md scaffold in the current folder. Use it, and then read every line. A generated file full of confident, wrong statements about your project is worse than no file.
To check what Codex actually loaded, the docs suggest asking it from the repository root:
codex --ask-for-approval never "Summarize the current instructions."
What earns a line
The test: would I otherwise say this at the start of every session?
- Commands. How to run the tests, the build, the linter. This turns “it suggests a command” into “it runs the right one”.
- Boundaries. Generated folders, vendored code, anything that must not be edited by hand.
- Conventions you cannot see in the code. “Dates are stored as UTC strings.”
And keep it short. Codex stops adding files once the combined instructions reach a size limit, and long before that, every line is competing with the actual task for attention.
Write the exercise version in the terminal: the test command and one hands-off folder.
Switching from another agent
Rules kept in another agent’s file, such as CLAUDE.md, are not what Codex reads by default. If your repository already keeps its rules under a different name, you can add that name to project_doc_fallback_filenames in ~/.codex/config.toml, and Codex will treat it like an AGENTS.md.
Should AGENTS.md be committed to Git?
Yes, for project rules: everyone on the project gets the same instructions, and they change together with the code. Personal preferences belong in ~/.codex/AGENTS.md instead.
Do other tools read AGENTS.md too?
AGENTS.md is a plain Markdown convention with its own site at agents.md, which the Codex docs point to. Whether another agent reads it by default is up to that agent, so check its documentation for the file it loads rather than assuming.