Mastering AGENTS.md: Codex Custom Instructions

What Is AGENTS.md?#

AGENTS.md is Codex's custom instruction file — the primary mechanism for steering the AI coding agent's behavior without modifying its source code. Think of it as a project-level system prompt that Codex reads automatically every time a session starts. Unlike ad-hoc instructions typed into the chat, AGENTS.md persists across sessions, lives in your repository, and can be version-controlled alongside your code.

Every Codex session begins by discovering and loading one or more AGENTS.md files. These files tell Codex how to navigate your codebase, what conventions to follow, which tools to prefer, what to avoid, and how to handle edge cases. A well-crafted AGENTS.md transforms Codex from a generic coding assistant into a domain-specialized collaborator that understands your project's architecture and rules.

Discovery Hierarchy: How Codex Finds Your Instructions#

Codex loads custom instructions using a multi-layer discovery system with clear precedence rules. Understanding this hierarchy is critical because it determines which instructions win when conflicts arise.

Layer 1: Global Instructions (~/.codex/AGENTS.md)#

The global file lives at ~/.codex/AGENTS.md (or $CODEX_HOME/AGENTS.md if the CODEX_HOME environment variable is set). This file applies to every Codex session on your machine, regardless of which project you are working on. It is ideal for personal preferences that span all projects: preferred coding style, documentation habits, testing conventions, and generic best practices.

Example use cases for the global file:

• "Always write tests before implementing features."
• "Prefer functional components over class components."
• "Include JSDoc comments on all exported functions."

You can override the global home directory by setting CODEX_HOME to any path. Codex will look for AGENTS.md inside that directory instead of ~/.codex/.

Layer 2: Project Root Walk#

Codex walks from the project root directory down toward the current working directory, collecting AGENTS.md files at each level. If your repository has this structure:

/~/projects/myapp/AGENTS.md          (project root)
/~/projects/myapp/src/AGENTS.md      (src subtree)
/~/projects/myapp/src/api/AGENTS.md  (API subtree)

And you run Codex from /~/projects/myapp/src/api/, it will load all three files in order: root first, then src, then api. Later files override earlier ones for conflicting instructions, meaning the most specific (closest to CWD) file wins. This lets you set broad conventions at the project root and refine them in subdirectories.

Layer 3: Override File (AGENTS.override.md)#

At any directory level, if Codex finds a file named AGENTS.override.md, it takes absolute precedence over the regular AGENTS.md in the same directory. This is a deliberate escape hatch for situations where you need to completely replace (not just amend) the instructions at a given level.

Use AGENTS.override.md when:

• A subdirectory has fundamentally different conventions from the rest of the project.
• You are experimenting with alternative instructions and want a clean slate.
• An automated pipeline injects instructions that should replace hand-written ones.

The override file does not cancel files from parent directories — it only replaces the AGENTS.md at its own level.

Fallback Filenames via Config#

Codex also supports custom fallback filenames through the project_doc_fallback_filenames setting in your config.toml. This array tells Codex to look for additional filenames if AGENTS.md is not found. Common fallbacks include:

[project]
project_doc_fallback_filenames = [".cursorrules", ".claude", "CONVENTIONS.md"]

This is useful for teams migrating from other AI coding tools who already have instruction files in place. Codex will check each fallback filename in order and use the first one it finds. Note that fallbacks are only consulted when AGENTS.md is absent at that directory level — if AGENTS.md exists, fallbacks are skipped.

Size Limits and Truncation#

Codex enforces a default 32 KiB limit on the combined size of all loaded instruction files, configured by project_doc_max_bytes in config.toml. If your AGENTS.md files exceed this limit when concatenated, Codex truncates the result. To increase the limit:

[project]
project_doc_max_bytes = 65536  # 64 KiB

Be deliberate about what you include. A bloated AGENTS.md consumes context window space that could be used for your actual code and conversation. Prioritize concise, high-impact instructions over exhaustive documentation.

What to Include in AGENTS.md#

A strong AGENTS.md file balances breadth with precision. Here are the categories that deliver the most value:

Project Context: Brief description of the architecture, tech stack, and directory layout. Codex does not read your entire codebase before starting — it relies on you to orient it.

Code Conventions: Naming patterns, file organization rules, import ordering, and formatting standards. Be specific: "Use kebab-case for file names" is better than "Follow standard conventions."

Testing Requirements: Which test runner to use, where tests live, coverage expectations, and how to run the suite. Example: "Run pnpm test before committing. All new functions must have at least one unit test."

Git and Commit Rules: Branch naming, commit message format, PR template expectations. Example: "Commit messages follow Conventional Commits: feat(scope): description."

Safety Boundaries: Files and directories Codex should never modify, dangerous commands to avoid, and security-sensitive areas that require human review. Example: "Never modify files in config/secrets/. Always ask before running database migrations."

Tool Preferences: Which package manager, linter, formatter, and build tool to use. Example: "Use pnpm instead of npm. Format with Prettier before committing."

Error Handling Patterns: How to handle errors consistently, logging conventions, and retry strategies.

What NOT to Include#

Avoid including information that Codex can discover by reading files directly: exhaustive API documentation, full function signatures, or step-by-step tutorials. AGENTS.md is for instructions, not reference material. Also avoid vague directives like "write good code" — they add bulk without actionable value.

Scaffolding with /init#

Codex provides a built-in slash command to bootstrap AGENTS.md. Running /init in a Codex session generates a starter AGENTS.md based on your project's detected characteristics — package.json dependencies, directory structure, existing config files, and detected frameworks.

The scaffolded file includes placeholder sections for each category above, with project-specific defaults pre-filled where detection succeeds. You should review and customize the output: the scaffold is a starting point, not a final product. Add your team's specific conventions and remove anything that does not apply.

To use it, simply type /init at the Codex prompt. The generated file is written to the project root as AGENTS.md.

Verification: Confirm Instructions Are Loaded#

After setting up your AGENTS.md files, verify that Codex is reading them correctly. The simplest method is to ask Codex to summarize the current instructions:

codex --ask-for-approval never "Summarize the current instructions."

Codex will output a summary of all loaded instruction files, including which files were found and their effective content. This confirms the discovery hierarchy is working as expected and that no files are being silently skipped due to size limits.

You can also verify at runtime within a Codex session by asking: "What custom instructions are currently active?" The agent will report the loaded files and their key directives.

Troubleshooting Common Issues#

Instructions are not being followed: Check that your AGENTS.md is at the correct directory level. If Codex is launched from a subdirectory, root-level instructions may not load if they are outside the walk path. Use the verification command above to confirm which files Codex sees.

Conflicting instructions between files: Later files in the walk (closer to CWD) override earlier ones. If you have contradictory rules, move the authoritative one to the most specific level. Alternatively, use AGENTS.override.md to completely replace a level's instructions.

Instructions are truncated: Your combined AGENTS.md files likely exceed the 32 KiB default limit. Reduce content, consolidate files, or increase project_doc_max_bytes in config.toml.

Fallback files not loading: Fallback filenames are only checked when AGENTS.md is absent at a directory level. If an AGENTS.md exists — even an empty one — fallbacks are skipped for that level.

Global file not found: Verify that ~/.codex/AGENTS.md exists (or check CODEX_HOME if set). The directory must exist and the file must be named exactly AGENTS.md — not agents.md, AGENTS.txt, or any other variation.

Override file not taking effect: AGENTS.override.md only replaces AGENTS.md at the same directory level. It does not suppress files from parent or child directories. If you need to suppress all parent instructions, place the override at the root level of your project.

Best Practices#

1. Start with /init, then refine: Let Codex scaffold the baseline, then add your team's specific rules.
2. Prefer specificity over volume: Ten precise rules outperform a hundred vague guidelines.
3. Layer intentionally: Use global for personal habits, project root for team standards, and subdirectory files for local exceptions.
4. Version-control AGENTS.md: Commit it alongside your code so every contributor gets the same agent behavior.
5. Review periodically: As your project evolves, instructions that were once critical may become stale or contradictory.
6. Use override sparingly: AGENTS.override.md is a power tool. Prefer additive instructions in AGENTS.md over wholesale replacement.
7. Keep under the size limit: Regularly check that your combined instructions fit within project_doc_max_bytes. Trim redundancies and move reference material to separate documentation files.