Debug repository instructions without adding more rules

Identify the global instructions and the project instruction files that apply to the directory you are working in. Codex builds an instruction chain from broader context toward the working directory; a nearer instruction can change an earlier one. AGENTS.override.md has special precedence within its directory.

Use the official documentation for exact discovery behavior and limits. The practical debugging task is to locate the applicable files and compare their meaning, rather than assuming a single file controls every session.

Pick a small rule whose effect is easy to see: the documented test command or the location of a component. Ask the session to identify that rule and its source before doing a larger task. If the answer points somewhere unexpected, investigate scope first.

Start a fresh session after editing instruction files so the next check begins from the updated instructions. Keep the test task the same when comparing results.

Look for rules that ask for incompatible behavior. Examples include always running every check while forbidding the required setup, or demanding a particular output format that omits the requested evidence. Rewrite the conflicting rule to say what should happen in the real situation.

Keep factual instructions current. An obsolete command can make a well-followed instruction look like poor task execution. Confirm commands against the repository before adding them to the file.

Prefer a concise map, actual validation commands, and important boundaries. Move long explanations into linked project documentation. Review the file when the repository structure or development process changes.

• Build a starter AGENTS.md

Primary source: AGENTS.md discovery and precedence. Source checked September 10, 2026.