Codex — Part 4 — Understanding and Writing AGENTS.md

Introduction

Part 3 covered starting and navigating a session. Like Claude Code, Codex starts from zero context beyond what it reads from the folder itself, unless you give it something persistent to read first. AGENTS.md is that file.

Readers who have already gone through the Claude Code series on this site will recognise the shape of this immediately, a markdown file of standing instructions, read automatically, that saves you from re-explaining the same conventions every session. The details underneath differ enough to be worth covering properly rather than assuming they transfer.

What Is AGENTS.md?

AGENTS.md is a configuration file that gives Codex persistent instructions and context before it starts any work. It combines global defaults that apply everywhere with project-specific overrides, the same layered idea as CLAUDE.md’s managed, user, project, and local scopes.

Where AGENTS.md Files Live

Files concatenate from the git root down to your working directory, joined with blank lines. A file closer to your current directory is read later in the combined instructions, so it effectively overrides guidance from a file higher up.

What Belongs In It

The same test applies as it did for CLAUDE.md: if you find yourself typing the same correction into chat more than once, it belongs here instead. Specificity matters more than length.

# Workspace Instructions

## Scope And File Safety
- Do not write output files outside C:\Temp\Reports unless approved.
- PowerShell scripts may run locally for testing, never against
  production without explicit approval.

## Quality Baseline
- Use Set-StrictMode -Version Latest.
- No aliases in delivered scripts: Where-Object, not ?.
- Typed parameters with validation attributes where appropriate.

## Environment Assumptions
- WinRM is assumed blocked. Use Get-WmiObject for remote collection,
  not Invoke-Command.

This is the same illustrative example used in the Claude Code series’ CLAUDE.md post, deliberately, since the underlying question is identical for both tools: what does Codex have no way to guess on its own about this specific project?

Creating One

# Generate an AGENTS.md scaffold in the current directory
/init

# Verify what Codex actually loaded, without making any changes
codex --ask-for-approval never "Summarize current instructions."

The second command is worth running any time you are unsure whether an AGENTS.md edit actually took effect, since it asks Codex to report back what it currently sees rather than you guessing from behaviour.

Keeping It Effective

AGENTS.md content is loaded into every run, so size has a real cost. The default combined limit is 32 KiB, set by project_doc_max_bytes in config.toml. Once the combined size hits that limit, Codex stops adding further files, silently, which is worth knowing before assuming a deeply nested override is being read.

# %USERPROFILE%\.codex\config.toml
project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

Raising the limit is one option if you have a genuine need for more. The other, matching the advice given for CLAUDE.md, is to place instructions as close as possible to the specialised work they apply to, so a deeply nested AGENTS.md only loads for the part of the project that actually needs it.

Final Thoughts

AGENTS.md and CLAUDE.md solve the same problem with slightly different mechanics: a discovery walk instead of a directory-tree walk with subdirectory lazy-loading, an explicit byte limit instead of a line-count guideline, and an override file instead of a local, gitignored variant. The underlying discipline is identical: write specific, checkable instructions, and keep them close to the work they actually govern.

Once your project conventions persist across sessions, the next question is the same one the Claude Code series asked next: how to package a repeatable procedure so it runs on demand instead of being re-explained every time.