Writing an AGENTS.md File with /init

AGENTS.md is the file /init writes, and its actual job is narrower than it sounds — it's not documentation for humans, it's the context a future Codex session reads automatically so you don't have to re-explain your project's conventions from scratch every time you start one.

What actually belongs in it

Genuinely stable, project-specific facts: how the project's tests are run, what the build command actually is, naming or structural conventions the codebase follows that aren't obvious from reading any single file, and anything a new contributor — human or agentic — would otherwise have to ask about or discover by trial and error. What doesn't belong: anything that changes often, since a stale AGENTS.md actively misleads a session that trusts it, which is worse than no file at all.

Why running /init early matters more than running it thoroughly

A rough AGENTS.md written on day one and refined over time is worth more than a comprehensive one you keep meaning to write later — every session between "now" and "later" is a session that didn't get the benefit of it. Running /init on a fresh project and accepting an imperfect first draft, then editing it by hand as you notice gaps, is a better workflow than waiting to write the definitive version in one sitting.

Reviewing what Codex actually wrote

/init generates the file from what Codex can infer about your project — reading the codebase, its structure, whatever conventions are visible from the code itself. That inference is a starting point, not a finished product: it's worth reading the generated file critically and correcting anything it inferred wrong, the same way you'd review any other piece of Codex-generated output before trusting it. An AGENTS.md with a subtly wrong assumption baked in is arguably worse than not having one, since it's specifically the kind of context future sessions are meant to trust without re-verifying.

Keeping it current as the project changes

A project's conventions shift — a build command changes, a testing approach gets replaced, a structural convention gets refactored away. AGENTS.md needs to move with those changes, not sit frozen from whenever it was first written. Treating it as a normal part of a project's documentation that gets updated in the same pull request as the change it describes, rather than a one-time setup artifact, is the difference between a file that stays useful and one that quietly becomes a liability.

One file, or several

For a large monorepo with genuinely distinct conventions in different parts of the codebase, a single root-level AGENTS.md trying to cover everything can end up too generic to be useful for any specific part of it. Whether the CLI supports or expects nested AGENTS.md files per subdirectory is worth checking against the current config reference rather than assumed — this is exactly the kind of structural detail worth confirming against the CLI's own documentation for the version you're actually running, rather than assumed from general practice elsewhere.

What it doesn't replace

AGENTS.md is project-level context, not task-level instructions — it tells a session how your project generally works, not what you want done in this particular session. A well-written AGENTS.md reduces how much you need to explain at the start of every session, but it doesn't remove the need for a clear, specific instruction about the actual task at hand; the two operate at different levels and both still matter.

A reasonable first pass

If you haven't run /init on an existing project yet, doing it now — even on a project that's been running for a while without one — is worth the few minutes it takes. The file benefits every session from the moment it exists forward; there's no advantage to waiting for a "better" time to add it, and every session in the meantime is one that had to work without the context it would have provided.

Treating it as a living contract, not a one-time artifact

The most useful AGENTS.md files this pattern tends to produce aren't the most detailed ones on day one — they're the ones that keep accumulating small corrections over time, the same way a team's internal wiki improves through repeated small edits rather than one comprehensive rewrite. Every time a Codex session gets something wrong because it assumed a convention that wasn't actually true, that's a signal worth turning into a one-line addition to the file, so the next session doesn't make the identical mistake. Treated this way, the file becomes an accumulating record of exactly the misunderstandings your project has actually produced, which is a more useful document than one written speculatively up front by guessing what might be unclear.

Team conventions versus individual preferences

Because AGENTS.md typically lives in the repository itself, it's shared context for everyone working in the project, not a personal configuration file. That's worth keeping in mind when deciding what to put in it — a convention the whole team has actually agreed on belongs there; one contributor's personal stylistic preference that hasn't been discussed with the team doesn't, the same way it wouldn't belong in a shared style guide without buy-in. Committing changes to the file through the same review process as any other code change keeps it from silently drifting into one person's individual preferences dressed up as project-wide conventions.

What happens with no AGENTS.md at all

A project with no AGENTS.md isn't broken — Codex still works, inferring what it can from the code itself each session. What's missing is the accumulated, explicit context a file like this captures once and reuses indefinitely; without it, every session re-derives (or fails to derive) the same conventions from scratch, which is strictly more expensive in tokens and more prone to a session guessing wrong about something a one-line note would have settled instantly.