Fix AGENTS.md Not Working

Match the symptom

• Codex cannot repeat instructions that were just added.
• Root rules load but package-specific rules do not.
• An older or unexpected instruction overrides the repository file.
• The first part of a long instruction chain loads but later content is absent.

First checks

Collect evidence before changing configuration

git rev-parse --show-toplevel
git status --short

codex --ask-for-approval never "Summarize the current repository instructions and their source files. Do not edit files."

Diagnosis 1

Start a new run after editing instructions

Codex builds its instruction chain once per run, so an existing session can retain the earlier file content.

1. Save the file, end the current run, and start Codex again.
2. Launch from the repository or package directory where the intended rules should apply.
3. Ask for a read-only summary before testing edits.

Decision: If the new content appears, discovery is healthy. Continue only if a specific instruction is still not followed.

Diagnosis 2

Confirm project root and directory scope

Codex normally uses the Git root, then walks down to the current working directory and includes at most one instruction file per directory.

1. Confirm `AGENTS.md` is inside the detected repository.
2. For a nested rule, launch from or work within the subtree it governs.
3. If there is no project root marker, expect Codex to check only the current directory.

git rev-parse --show-toplevel

Decision: A file outside the root-to-working-directory chain will not enter this run's project instruction chain.

Diagnosis 3

Inspect overrides and conflicts

At each directory Codex prefers `AGENTS.override.md` over `AGENTS.md`; deeper guidance appears later and can override broader guidance.

1. Check `~/.codex/AGENTS.override.md` before the global base file.
2. Check every directory from repository root to the working directory for both filenames.
3. Remove empty, obsolete, duplicated, and contradictory statements.
4. Do not expect two instruction files in the same directory to merge.

Decision: Keep the canonical guidance in the file Codex actually selects, and make any deeper override explicit rather than accidental.

Diagnosis 4

Reduce size and make the rule verifiable

Codex stops adding project instructions at the configured combined limit, 32 KiB by default, while vague guidance can load successfully but still be hard to apply.

1. Split package-specific details into nested files.
2. Replace prose with exact commands, paths, measurable constraints, and canonical examples.
3. State each rule once and remove architecture documentation that belongs elsewhere.

Decision: Ask Codex to repeat the exact rule, then test it with one bounded task whose result is objectively reviewable.

If it still fails, send this evidence

A useful support request is reproducible and does not expose credentials.

• Codex version and the directory where the run started.
• Output of `git rev-parse --show-toplevel`.
• The ordered instruction-file paths from global scope to working directory.
• A minimal rule that loads but is not followed, plus the task and resulting diff.