TL;DRWhen Codex misbehaves in an old repo, the model usually isn't the problem — nobody told it the rules. This is a 20-minute SOP for backfilling an AGENTS.md: draft with /init, fill in a four-block skeleton, validate on a small task, write corrections back.
Sources SOURCES
Distilled from public community discussions. This page only breaks them down and verifies — it never reposts the original; opinions belong to their authors.
Facts FACTS
Check these claims against the listed sources. For allowance mechanics, first-party account displays outrank community summaries.
- AGENTS.md is now an open, pure-Markdown standard under the Linux Foundation: drop it in the repo, ship it with the code, and humans and agents read the same file — no proprietary format, no special tooling, it just rides along with every clone.
- Official best practices list persistent instructions as a core use case: constraints you would otherwise repeat every single session belong in AGENTS.md, not in anyone's memory — the file remembers so you don't have to.
- Community templates converge on a four-block skeleton for AGENTS.md: project context, architecture notes, dev commands, coding conventions.
- Codex CLI ships an
/initcommand that scans the repo and generates an AGENTS.md draft — a rewrite starting point, not a finished file.
Concepts CONCEPTS
Not everything said in a community thread is a fact — each concept carries its nature label. Read the label first.
A file that lives in the repo and is written for coding agents: what the project is, how the commands run, what the rules are. Pure Markdown, one copy shared by humans and agents.
The official best-practices framing: constraints that hold across sessions get locked into standing instructions instead of being re-issued by hand every time you open a session.
Running /init and adopting the output without proofreading. Community experience says drafts routinely mix in model guesses — script names that don't exist, stale paths — and shipping them as-is cements the errors into an instruction file the agent will trust more than its own judgment.
An influential community position: AGENTS.md should serve the agent first — commands it can execute, boundaries it can verify. Vision statements and sentiment don't constrain a model.
Step-by-step SOP STEP BY STEP
- 01Generate the draft
Start
codexin the repo root, type/init, and let it scan the codebase into a first-draft AGENTS.md. - 02Delete what it guessed wrong
Read the draft end to end. Anything you can't personally vouch for — script names, paths, version numbers — check one by one: fix the wrong ones, delete the nonexistent ones. The draft is a starting point, not a deliverable.
- 03Fill in the four blocks
Complete project context, architecture notes, dev commands, and coding conventions. Every command must actually run in this repo — the agent will execute what you wrote, not what you meant. While you're at it, mark which commands are slow and which have side effects.
- 04State the no-go zones
List what must never be touched: generated directories, lockfiles, environment configs. Silence reads as permission — for anything you didn't explicitly forbid, the agent defaults to trying it, so the fence has to be written down.
- 05Validate on a small task
Have it fix one known small bug or add one unit test. Watch whether it reaches for the right commands from AGENTS.md and whether it stays out of the no-go zones.
- 06Write corrections back
For every class of mistake it makes during validation, add the matching constraint to AGENTS.md. This file earns its keep through continuous appending, not one heroic write.
Keep reading NEXT
Want today's verdict? Back to the live radar.