Project Instructions AGENTS.md: Embedding Rules into Codex's Workflow
📚 Series Navigation: The previous article 10 · Cloud Codex detailed how to let Codex run in the cloud and deliver PRs. This article returns locally to discuss a file every project should have, but nine out of ten beginners write incorrectly—
AGENTS.md, the project instructions file that Codex reads before starting every task.
Let's talk about a stupid mistake I made when I first started using Codex.
Last year, I handed a Node project to Codex. I wrote a file named AGENTS.md in the root directory. The very first line stated: "This project uses pnpm; npm is forbidden." Yet, it turned around and ran npm install. I assumed it hadn't read the file, so I copied the rule three times, bolded it, and added exclamation marks. It still didn't listen.
After a lot of troubleshooting, I realized—it did read it, but the rule was buried on line 140. Before that, I had written paragraphs of company background, product roadmaps, and the history of technical choices—a hundred lines of text. By the time Codex scrolled down to "npm is forbidden," its attention was diluted by the fluff. The issue wasn't that it disobeyed; it was that I had buried the only useful rule under a pile of fluff.
AGENTS.md is to Codex what CLAUDE.md is to Claude Code—the same concept under a different filename. However, Codex's discovery mechanism, override rules, and byte limits are unique, presenting a few potential traps. This article clears up how to write it, what to include, and what to omit.
After reading this article, you will get:
- The discovery path Codex uses to find
AGENTS.md(global scope → project scope → merge order), and how conflicts are resolved - How to use
AGENTS.override.mdto temporarily bypass settings, a mechanism not present in Claude Code - A checklist of "What to write vs. What to avoid" to help you bypass the "ignored on line 140" trap
- How to rename files (
project_doc_fallback_filenames) and adjust byte limits (project_doc_max_bytes) in configuration files - A step-by-step validation flow to check whether Codex is actually reading your file
Note: This article focuses exclusively on how to write and load AGENTS.md. The easily confused "Memories" mechanism (which is a local, auto-recall layer disabled by default) was mentioned in Article 02. Remember: team rules that must apply to every run should be written in AGENTS.md; do not rely on memories.
01 Understand First: AGENTS.md is Codex's Pre-Flight Handover List
First, the conclusion: AGENTS.md is a persistent instruction file you write for Codex. It reads it before starting any run, loading the project's background details into its context.
Why do you need it? Because Codex starts every run (per run—the official term, usually referring to starting a new session in the TUI) with a blank slate. The instructions you gave it last time ("use pnpm, don't touch legacy/, run tests like this") are forgotten. Without AGENTS.md, you have to repeat them every time.
Analogy: A shift-handover log. In a factory, workers on three shifts write notes on a whiteboard before leaving—which machines to avoid, which materials need quality checks, and who the emergency contacts are. The next shift takes over by reading the whiteboard without calling the previous workers. AGENTS.md is Codex's whiteboard—the whiteboard it scans before starting every shift.
(Note that we call it a "handover list" rather than an "onboarding handbook," which was used in Article 02. A handover list highlights that it is re-read before every run, rather than read only on the first day.)
When should you add rules to the list? A few clear indicators:
- Codex makes the same mistake twice—document the correction so you don't have to explain it a third time.
- You find yourself repeating a correction you made in a previous session.
- During code review, you notice it made assumptions it should have known were incorrect for the codebase.
- A new team member (or you, three months from now) needs the same context to get started.
My favorite approach, mentioned in Article 02 and emphasized here—treating it as a feedback loop: when Codex makes an incorrect assumption about your codebase, do not just correct it in the chat (which is a one-shot fix forgotten in the next session). Prompt it to write the correction into AGENTS.md itself. I tuned a Python project for two weeks, and its AGENTS.md grew from blank to twenty lines of rules. Now, new sessions rarely repeat past mistakes.
💡 Summary in one sentence:
AGENTS.mdis Codex's pre-flight handover list read before every run. Add rules when mistakes happen, and it gets better over time; it is the same concept as Claude Code'sCLAUDE.md, just under a different name.
02 Discovery Path: How Codex Finds These Files
AGENTS.md files can be placed in multiple locations, ranging from global to project-specific scopes. Codex parses them on startup to build an instruction chain. This section breaks down this discovery path—which differs significantly from Claude Code.
According to the official docs, Codex builds this instruction chain in two steps (on startup of a run/session):
Step 1: Global Scope. In your Codex home directory (defaulting to ~/.codex unless overridden by the CODEX_HOME environment variable), Codex checks for AGENTS.override.md first, falling back to AGENTS.md if missing. It selects only the first non-empty file in this directory, rather than reading both.
Step 2: Project Scope. Starting from the project root (usually the Git root) down to your current working directory, Codex checks each directory in this order: AGENTS.override.md first, then AGENTS.md, and finally any custom filenames specified in project_doc_fallback_filenames. It selects at most one file per directory.
Step 3: Merge. Codex concatenates the discovered files from root to leaf, separating them with empty lines. Files closer to your working directory appear later in the concatenated output, allowing them to override rules defined upstream.
Let's map this chain in a diagram:
This diagram shows the complete chain: selecting one file per level (global, project root, subdirectory) and concatenating them from root to leaf—ensuring the files closest to your current directory have the final say.
Keep these two official rules in mind:
First, it is concatenation, not replacement. The global file and the project file apply simultaneously. Writing a project-level file does not discard global rules; they are both loaded into the context, and conflicting rules are resolved in favor of the later (closer) file.
Second, closer rules win. For example, if the global AGENTS.md specifies "use single quotes" and the project root AGENTS.md specifies "use double quotes"—the project root rule is closer and appears later in the merge, so double quotes win. Simply put: project-specific rules override your personal preferences, which is ideal for team collaboration.
Analogy: Three levels of map zoom. A national map shows the general direction (global scope), a city map shows street routes (project root), and a neighborhood map shows the final steps (subdirectory). All three apply simultaneously without erasing the others. However, if a neighborhood sign conflicts with the city map, the neighborhood sign wins—it is closest to your immediate location. The AGENTS.md chain follows this same logic: closer means more specific, taking priority in case of conflicts.
This diagram stacks the three levels from top to bottom—global (~/.codex/), repository root, and subdirectory are concatenated in order. The "Priority" axis on the right highlights that: files closer to your current directory appear later in the merged output, overriding upstream rules in case of conflicts.
💡 Summary in one sentence: The Codex discovery path runs from global (
~/.codex/, override takes priority, select one non-empty file) to project directories (Git root down to working directory, select one file per folder) → concatenating them from root to leaf, where closer files take priority in case of conflicts. It is concatenation, not replacement.
03 AGENTS.override.md: Bypassing Settings (Unique to Codex)
The name AGENTS.override.md appeared repeatedly in the previous section. This file has no equivalent in Claude Code and is a unique design in Codex. Let's explain it.
First, the problem it solves. Imagine you have written a set of team-wide rules in ~/.codex/AGENTS.md that work well for daily tasks. But today, you are working on a temporary project that requires completely replacing those global guidelines, and you don't want to delete the original file (only to write it again later). What do you do?
Analogy: Sticking an "override" note on a contract. The original contract remains in the drawer; you simply attach a temporary note: "This month, follow these new rules instead." Once the task is complete, you peel off the note, and the original contract applies again. AGENTS.override.md is this temporary note—when present, the同级 AGENTS.md is ignored; delete it, and the original file is loaded again.
Two typical use cases:
- Global Override: Write temporary global rules in
~/.codex/AGENTS.override.md, leaving~/.codex/AGENTS.mduntouched. Delete the override when done to restore the shared configurations. - Subdirectory Rules: A subdirectory requires rules different from the parent project. For example, in the payment service directory
services/payments/, place anAGENTS.override.md:
# services/payments/AGENTS.override.md
## Payment Service Rules
- Use `make test-payments` instead of `npm test`
- Notify the security channel before rotating API keysWhen this override is present, the同级 AGENTS.md in this directory is ignored, and Codex follows the rules in the override when working in this folder.
Understand this key difference—override is not the same as "overriding the entire chain":
| Scope | AGENTS.override.md Behavior |
|---|---|
| Inside the same directory | When present → the同级 AGENTS.md (and fallbacks) are ignored; only the override is loaded for this level |
| Across directories (the chain) | It does not discard rules from other directories; upstream rules are still concatenated, with conflicts resolved by closer rules |
Simply put: override means "use me instead of AGENTS.md at this level," not "ignore the rest of the chain." The concatenation and "closer takes priority" rules remain unaffected. I misunderstood this on my first try, assuming a subdirectory override would block the global file, but global rules were still loaded. The official docs clarified that it only switches files within its own directory slot.
It is also an excellent troubleshooting tool: if Codex follows a strange rule you didn't write, scan your directories up to ~/.codex to check if a hidden AGENTS.override.md is overriding your rules. Rename or delete it to restore your regular guidelines.
💡 Summary in one sentence:
AGENTS.override.mdis Codex's temporary override—when present, theAGENTS.mdat its level is ignored; it does not affect concatenation at other levels. Use it to change rules temporarily without deleting original files; search for overrides when troubleshooting unexpected behaviors.
04 What to Write vs. What to Avoid
This is the core of this article, and the solution to the "ignored on line 140" trap. Poor AGENTS.md files contain too much fluff and miss the essential rules.
First, what to write—simply: "facts Codex must respect during every run." Translate this into five categories:
| Category | What to Write | Example |
|---|---|---|
| Project Summary | A one-sentence description of the project | "FastAPI-based order management backend" |
| Tech Stack | Languages, frameworks, databases, and key tools | "Python 3.11 / PostgreSQL / pytest" |
| Common Commands | How to run tests, builds, and linting | npm run lint, make test-payments |
| Coding Style | Conventions, naming, and required styles | "Functions must include type annotations," "Always use double quotes for strings" |
| Explicit "Do Nots" | Restrictions, forbidden edits, and actions requiring confirmation | "Do not edit existing migrations," "Ask before adding any new production dependencies" |
Common commands are referenced most frequently—Codex reads them before running tests or preparing PRs, saving it from guessing. The official template lists commands first: "Run npm run lint before creating PRs." The restrictions list acts as a guardrail against automated mistakes: which legacy folders are read-only, and which actions require explicit authorization.
Now, what to avoid—the common pitfalls for beginners:
- ❌ Long Background Explanations: Company history, product visions, or technical histories—these are useless for writing code, consume context, and dilute useful rules (as in my 140-line mistake).
- ❌ Outdated Information: Changing package managers without updating
AGENTS.mdleads Codex to run incorrect commands. - ❌ Details Obvious from Code: Avoid listing directory files or copy-pasting styling rules defined in ESLint / Prettier. Codex reads the code; repeating rules wastes context space.
The official docs enforce a size limit on instructions, but Codex limits size by bytes rather than lines (which Claude Code suggests keeping under 200 lines):
Codex skips empty files, and stops loading files once the concatenated size hits the project_doc_max_bytes limit (defaulting to 32 KiB).
This implies two things: first, size is capped at 32 KiB by default, truncating anything beyond that; second, this limit applies to the merged output (global + project + subdirectory combined). A bloated file at one level can block files at other levels. Official advice: if you hit the limit, increase project_doc_max_bytes or split instructions across subdirectories (which reduces token usage, as described in Article 04).
Use a simple check when writing rules: "Can Codex deduce this rule by reading the code? If yes, delete it." This filter shrinks a bloated AGENTS.md file down to a few lines of strict rules. It also significantly reduces package manager errors.
💡 Summary in one sentence: Document "facts to remember every run" (summaries, tech stacks, commands, conventions, and restrictions), and delete anything Codex can deduce from the code; the size limit is bytes—concatenated files are capped at 32 KiB (
project_doc_max_bytes) by default, and you can raise the limit or split rules across subdirectories.
05 Two Config Knobs: Renaming Files and Raising Limits
Most users work fine with the default AGENTS.md. However, if you need to adjust them, write these settings in ~/.codex/config.toml (your user-level config file).
Knob 1: Recognizing Custom Filenames
If your repository already has a TEAM_GUIDE.md file that lists team guidelines, you can tell Codex to read TEAM_GUIDE.md as the instructions file instead of duplicating it into AGENTS.md. Use project_doc_fallback_filenames:
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]Once configured, Codex scans directories in this order: AGENTS.override.md → AGENTS.md → TEAM_GUIDE.md → .agents.md, selecting the first one present.
Codex ignores files not in this list. If you want a custom file to serve as project instructions, add it to
project_doc_fallback_filenames—do not expect Codex to guess.
Knob 2: Raising the Concatenation Limit
If your concatenated instructions exceed 32 KiB and you cannot split them yet, raise the project_doc_max_bytes limit:
# ~/.codex/config.toml
project_doc_max_bytes = 65536This raises the limit to 64 KiB. However, this is a temporary fix. Hitting the 32 KiB limit is a signal to trim or split your files rather than raising the limit. Prioritize trimming and splitting, raising limits only when necessary.
Use case comparison:
| Scenario | Knob to Turn |
|---|---|
Repository has TEAM_GUIDE.md to be read as instructions | Add its name to project_doc_fallback_filenames |
| Merged instructions exceed 32 KiB and get truncated | Try trimming/splitting first; raise project_doc_max_bytes only if needed |
| Switch to a separate configuration profile (e.g., automation) | Override CODEX_HOME to point to a different folder (detailed below) |
⚠️ Remember to restart Codex after modifying
config.toml—these settings are loaded on startup. The troubleshooting guide lists: "Fallback names not working? Verify spelling and restart Codex."
💡 Summary in one sentence: Use
project_doc_fallback_filenamesto recognize custom filenames (others are ignored); useproject_doc_max_bytesto raise the merge limit (default 32 KiB), but prioritize trimming and splitting over raising limits; restart Codex to apply changes.
06 Hands-on: Writing and Verifying an AGENTS.md File
Let's walk through creating a project, writing rules, and verifying that Codex reads them.
Platform Note: The
mkdirandgit initcommands below work on Mac / Linux; on Windows, run them in Git Bash / WSL or create folders manually. The~character represents your home directory (on Windows,C:\Users\username\).
Step 1: Create a playground project and initialize Git
mkdir agents-md-demo
cd agents-md-demo
git initExpected behavior: A .git directory appears in agents-md-demo. Git initialization helps Codex identify the folder as a "project root" (which it scans from) and lets you commit AGENTS.md to share with your team.
Step 2: Write a concise project-level AGENTS.md
In the project root, create AGENTS.md and paste the following content (note the brevity—this is how it should look):
# agents-md-demo — A minimal playground project
Built to demonstrate how to write AGENTS.md, containing no business logic.
## Common Commands
- `npm test` —— Run tests
## Coding Rules
- All functions must include type annotations
- Always use double quotes for strings
## Restrictions
- Ask before adding any new production dependenciesExpected behavior: AGENTS.md appears in the root directory. It is short—keep your real files concise too.
Step 3: Verify Codex reads the instructions
Ask Codex to summarize the active instructions. Run in the project folder:
codex --ask-for-approval never "Summarize the current instructions."Expected behavior: Before proposing changes, Codex recalls the rules you wrote (test command, type annotations, double quotes, dependency restrictions). This confirms AGENTS.md is loaded into its context.
The
--ask-for-approval neverflag keeps the output clean by bypassing approval prompts; do not use this flag in regular workflows. Choose appropriate approval modes as detailed in Article 02 and permission chapters.
Step 4 (Advanced): Verify subdirectory overrides take priority
Let's verify that closer rules win. Create a subdirectory and add an override file:
mkdir -p services/paymentsWrite in services/payments/AGENTS.override.md:
# services/payments/AGENTS.override.md
## Payment Service Rules
- Use `make test-payments` instead of `npm test`Now, launch Codex from the subdirectory and ask it to report its instruction sources:
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."Expected behavior: Codex lists the sources in order—global file (if present in ~/.codex), root AGENTS.md, and the payment service override. It resolves the test command to make test-payments, overriding the root npm test rule for this folder.
- Troubleshooting checklist if it misses rules: (1) run "Summarize the current instructions" to check if it reads the file; (2) run
codex statusto verify the active workspace root; (3) scan directories upstream for anAGENTS.override.mdthat overrides your rules; (4) verify the file is not empty (empty files are skipped).
💡 Summary in one sentence: Follow these steps to verify rules: write a concise file → run "Summarize the current instructions" to check recall → add a subdirectory override to verify "closer overrides win."
07 Summary
This article explored AGENTS.md, Codex's project instructions file:
| Dimension | Key Takeaway |
|---|---|
| What It Is | A persistent handover list read before every run, equivalent to CLAUDE.md |
| Discovery Path | Global scope (~/.codex/ override first) → project scope (root down to active directory) → concatenated root-to-leaf |
| Conflict Resolution | Concatenated, not replaced; closer files override upstream rules in case of conflicts |
| override | Codex-specific override: ignores AGENTS.md at its level, leaving other levels concatenated |
| What to Write | Summaries, tech stacks, commands, coding styles, and restrictions; omit anything clear from the code |
| Size Limit | Merged files are capped by bytes (default 32 KiB via project_doc_max_bytes); trim or split files if exceeded |
| Config Knobs | Custom names via project_doc_fallback_filenames, limit changes via project_doc_max_bytes (restart required) |
You should now be able to decide what information belongs in AGENTS.md and at what level, understand conflict resolution, use overrides to change rules temporarily, manage size limits, and verify files using "Summarize the current instructions." You can now write instructions that Codex actually follows.
The next article 12 · Slash Commands and Shortcuts: we have run several codex commands in the terminal, but what options do you have mid-session? Slash commands let you switch modes, clear context, and check status, and keyboard shortcuts speed up workflows. Let's cover these in the next article. Think about this: AGENTS.md saves rules across sessions, but how do you adjust behaviors mid-session without modifying AGENTS.md?