Documentation inconsistency: README.md vs. Prompting Guide (AGENTS.md vs. CODEX.md/instructions.md)

What is the type of issue?

Documentation is confusing

What is the issue?

Documentation inconsistency: README.md vs. Prompting Guide (AGENTS.md vs. CODEX.md/instructions.md)

There is a documentation inconsistency regarding instruction file references in the Codex CLI repository.

Details:

• The main README.md (see section "Memory & project docs") instructs users to use AGENTS.md files for providing extra instructions and guidance to Codex CLI. It describes a hierarchy:

1. ~/.codex/AGENTS.md – personal, global guidance
2. AGENTS.md at repo root – shared project notes
3. AGENTS.md in the working directory – sub-folder/feature specifics

• However, the prompting_guide.md (see section "Custom instructions") describes a different approach:
• ~/.codex/instructions.md: for global, user-level custom guidance
• CODEX.md: for project-specific instructions (loaded from current directory or repo root)

Observed contradictions:

• The README does not mention CODEX.md or instructions.md at all; it only references AGENTS.md.
• The prompting guide does not reference AGENTS.md; it only discusses CODEX.md and instructions.md.
• The file formats and expected directory locations differ between the two documents.

Why is this a problem?

• New users and contributors get conflicting information about how to provide persistent instructions or context to Codex CLI.
• It is unclear which files are actually supported, which takes precedence, and whether the documented behavior in each document is up to date.

Suggestion:

• Please clarify which instruction file formats and locations are supported by the current version of Codex CLI.
• Update both the README and prompting guide to reference the correct files and provide a consistent, unified explanation for users.

References:

• README.md – Memory & project docs
• prompting_guide.md – Custom instructions

Thank you!

Where did you find it?

_No response_