One File Codex Reads Before Anything Else

Tired of typing the same instructions into Codex every single prompt — "use function-based views," "run the tests before you say you're done"? One file fixes that, permanently. AGENTS.md sits in your project root, and Codex reads it before it does any work, every run. Think of it as onboarding notes for a new teammate who never forgets them.

Why this exists

An AI coding agent has no persistent memory of your project between sessions. Every conversation starts from the same blank state, which means every convention you haven't written down gets re-explained, re-corrected, or silently violated because the agent guessed wrong. AGENTS.md is Codex's answer: a file it deliberately reads at the start of a run, before touching your code, so conventions are already loaded before its first move. It's plain markdown, no special syntax, no schema — write it by hand or generate a starting point with Codex's init flow.

What goes in it

Three sections cover most of what matters:

AGENTS.md
Goal: <what this project is, one or two sentences>
Rules: <non-negotiable conventions the agent keeps getting wrong>
Commands: <the one command to run tests / lint / build>

• Goal — what the project is and what it's for, enough for a new contributor to understand its shape.
• Rules — conventions Codex can't infer from the code alone. "Function-based views only" is a good example: a codebase full of them doesn't tell an agent why it should keep writing that way instead of "modernizing," or that the alternative was already rejected.
• Commands — the exact command to run tests, lint, or build. The highest-leverage line: an agent that can verify its own work catches its own mistakes before shipping them to you.

How Codex uses it

Codex reads AGENTS.md before doing any work each run — loaded as context automatically, no reminder needed. It also merges with parent-directory files: a repo-root file plus a more specific subfolder file (say, a monorepo package with its own conventions) both apply, the subfolder file layering on top. Keep root-level rules broad, and push package-specific exceptions down into the folders where they're actually relevant.

How to create one

1. Create AGENTS.md in your project root (or let Codex's init flow scaffold one).
2. Write Goal, Rules, Commands in plain markdown.
3. Commit it like any other project file.

Start minimal, add on breakage

The most useful advice here is also the easiest to ignore: don't anticipate every rule up front. Start with Goal and Commands, and a near-empty Rules section. The first time Codex does something you didn't want — reaches for a banned library, writes a test in the wrong style — add exactly that rule and move on. This keeps the file short, which matters since every line costs context budget on every run, and keeps it grounded in things that have actually gone wrong rather than a speculative wishlist.

Where this pays off most

• Onboarding a messy legacy repo — write the quirks once instead of re-explaining them every prompt.
• A recurring team convention Codex keeps missing — correcting the same thing twice is the signal to add a Rules line, not to keep correcting it in chat.
• Monorepos — root file for shared conventions, subfolder files for package-specific exceptions, both applied via the merge behavior.

Pitfalls

• Writing it once and never updating it. Update the file in the same commit as the convention change.
• Letting it grow unbounded. Every line costs context on every run — prune stale rules like dead code.
• Treating it as documentation instead of instructions. Write directives ("use X, never Y, run Z to verify"), not architecture prose — that's what your README is for.

Resources

• github.com/openai/codex — AGENTS.md docs
• developers.openai.com — AGENTS.md guide