AGENTS.override.md vs AGENTS.md: Codex Instruction Precedence

If Codex keeps following an instruction you thought you replaced, the problem may not be the wording. It may be which instruction file Codex discovered, where the file sits in the repository, or when the current session loaded it.

Codex supports layered project guidance through AGENTS.md and AGENTS.override.md. The override filename is useful for a temporary or more specific set of instructions, but it is not a universal priority switch across every AI coding tool. This guide explains Codex's discovery order, how nested instructions combine, and a repeatable way to debug unexpected behavior.

The short answer

In Codex, discovery checks AGENTS.override.md before AGENTS.md in each directory. It includes at most one of those files from that directory. Across the project path, Codex combines the selected instruction files from the repository root down to the current working directory. More specific instructions appear later in the combined context, so they can refine or override earlier guidance when the instructions conflict.

There are two separate ideas here: the override filename wins the choice between two files in the same directory, while directory depth determines how project-level instruction files are layered. An override file in a parent directory does not automatically erase all guidance from child directories.

What each filename is for

AGENTS.md: the default project instructions

Use AGENTS.md for the instructions that should normally apply to work in a project or a subdirectory: setup commands, test commands, architecture boundaries, coding conventions, security cautions, and the definition of done. Keep it actionable. A short command with a clear reason is usually more useful than a page of generic advice.

AGENTS.override.md: a higher-priority choice in the same directory

Use AGENTS.override.md when you need a directory-specific alternative to that directory's regular AGENTS.md. For example, a repository may have standard test guidance in the root file, while a temporary override in a service directory tells Codex to use a special test command during a migration.

The important nuance: if both filenames exist in the same directory, Codex uses the override file rather than loading both files from that directory. Do not assume that putting only one extra bullet in the override file will automatically append it to the sibling AGENTS.md. Include the instructions that directory needs, and keep shared baseline rules in parent directories where they can still be inherited.

How Codex discovers instruction files

Codex builds its instruction chain at the start of a run or session. According to the official documentation, discovery works in three layers:

• Global scope. In the Codex home directory (usually ~/.codex unless CODEX_HOME changes it), Codex reads AGENTS.override.md if present; otherwise it reads AGENTS.md. Only the first non-empty file at this level is used.
• Project path. Starting at the project root (typically the Git root), Codex walks down to the current working directory. In each directory it checks AGENTS.override.md first, then AGENTS.md, then any configured fallback instruction filenames. At most one file per directory is included.
• Merge order. The selected files are concatenated from root to leaf, separated by blank lines. Guidance from directories closer to the current working directory appears later and can be more specific.

This means the current working directory matters. Starting Codex at the repository root and starting it inside services/payments can result in a different instruction chain because the second run can include instructions found along that deeper path.

A concrete example

Imagine this repository:

project/

• AGENTS.md — project-wide build, style, and review guidance
• frontend/AGENTS.md — UI conventions and frontend test commands
• services/payments/AGENTS.override.md — temporary payment-service migration guidance

When Codex runs from project/frontend it can combine the root instructions with the frontend instructions. When it runs from project/services/payments it combines the root instructions with the payment override. If services/payments/AGENTS.md also exists beside that override, Codex selects the override for that directory rather than loading both sibling files.

A practical rule is to put broad expectations at the root and only the differences in nested instruction files. If a nested override replaces the sibling file, do not accidentally drop important local test or safety steps that were present only in the sibling file.

Instruction precedence is not a security boundary

Instruction files are context for the coding agent; they are not a replacement for operating-system permissions, sandboxing, branch protection, CI checks, or code review. A sentence such as “never modify production data” is useful guidance, but a robust workflow should also restrict credentials and permissions so the agent cannot perform prohibited actions simply because a prompt was misunderstood.

Use an override to change project guidance, not to grant access. Keep secrets out of instruction files, and do not place private tokens in examples that may be committed to version control.

Why an instruction may seem to be ignored

1. The file is outside the discovered path

Codex's project discovery follows the path from the repository root to the current working directory. A file in a sibling directory is not automatically part of that chain just because it exists somewhere in the repository. Check the directory from which the task is being run.

2. Both files exist, but the override replaced the sibling file

If a directory contains both AGENTS.override.md and AGENTS.md, Codex selects one for that directory. Compare the selected override with the sibling file and make sure it contains the local guidance that must remain active.

3. You changed the file after the session started

The instruction chain is built when a run or session starts, not continuously reassembled after every file edit. After changing instruction files, start a fresh Codex session or run and ask it to report the instruction sources it loaded.

4. The combined instruction text reached its size limit

The documented default limit for combined project instructions is 32 KiB. Codex skips empty files and stops adding content when the configured project_doc_max_bytes limit is reached. If you have many large instruction files, later guidance may not make it into the context. Trim repetition, split guidance by area, or review the relevant configuration before raising the limit.

5. The instruction is vague or conflicts with another rule

“Write clean code” is hard to verify. “Run pnpm test --filter payments after changing payment-service files and report failures” is testable. Search the full instruction chain for contradictory commands, then state which instruction should win and how success will be checked.

A five-minute debugging checklist

• Confirm the current repository root and working directory.
• List all AGENTS.md and AGENTS.override.md files from the root down to the directory being edited.
• In every directory containing both names, inspect the override: it is the selected file for that directory.
• Start a new Codex run after edits so discovery is refreshed.
• Ask Codex to summarize the instruction sources and the key rules it received; compare that summary with the files on disk.
• Reduce duplicated or contradictory guidance and keep local instructions short, specific, and verifiable.
• Enforce critical requirements with tests, permissions, and CI—not prompts alone.

Does this behavior apply to Cursor too?

Do not assume every editor uses identical precedence rules. Cursor documents support for root and nested AGENTS.md files, with nested instructions combined and more specific guidance taking precedence. Cursor also has its own project-rule system in .cursor/rules/*.mdc, where frontmatter controls whether a rule is always applied, attached to matching files, selected based on its description, or included manually.

If you need portable instructions across several coding tools, keep shared, tool-agnostic guidance in AGENTS.md and verify each client's documented discovery behavior. Use tool-specific rule files for conditions or features that a shared Markdown file cannot express. Our related guide on AGENTS.md best practices covers what to keep in the file; the Cursor migration guide explains the separate .mdc rule format.

Official references

OpenAI: Custom instructions with AGENTS.md — Codex discovery order, global guidance, nested instructions, overrides, and the default size limit.

OpenAI Codex repository documentation — repository reference that points to the maintained AGENTS.md guide.

Cursor: Rules documentation — Cursor's own behavior for AGENTS.md, nested guidance, and .mdc project rules.

Frequently asked questions

Does AGENTS.override.md replace AGENTS.md?

Within the same directory, Codex checks AGENTS.override.md first and includes at most one instruction file from that directory. If both exist, the override is selected instead of the sibling AGENTS.md.

Do nested AGENTS.md files override the root file completely?

Not by default. Codex combines selected project instruction files from root to the current directory. More specific guidance appears later and can resolve conflicts, but the files are not simply treated as one file that erases all parent content.

Do I need to restart Codex after editing an instruction file?

Start a fresh run or session to ensure the instruction chain is rebuilt from the updated files. The documented discovery process occurs at run or session start.

Can AGENTS.md prevent an agent from performing a dangerous action?

It can communicate a rule, but it is not a security control. Use least-privilege credentials, sandboxing, protected branches, tests, and human review for actions that must be restricted.