The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Put an AGENTS.md in the narrowest directory whose files should follow its rules. Its instructions apply to the directory containing it and that directory’s descendants; when instructions conflict, a more deeply nested file takes precedence within its subtree. In Codex CLI, the automatically discovered project instruction chain is tied to the repository root and current working directory, so the set loaded for a task is not necessarily every instruction file anywhere in the repository.
How AGENTS.md directory scope works
Think of each AGENTS.md as guidance for a filesystem subtree. A file at the repository root can establish conventions for the whole project; a file at services/api/AGENTS.md applies to files in services/api/ and its descendants. For a particular file, follow every instruction file whose directory contains that file. The Codex repository’s AGENTS.md specification describes this scope and says deeper instruction files take precedence when they conflict.
As an Amazon Associate I earn from qualifying purchases.
A nested file does not erase unrelated root guidance. The root’s rules continue to apply unless a more specific instruction conflicts with them; the deeper rule wins for the files in its own subtree. Instructions should therefore be placed according to where they are relevant, not merely where it is convenient to create a file.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Choose the right directory for each rule
| Placement | Good fit | Scope and trade-off |
|---|---|---|
| Repository root | Shared language, broad contribution conventions, or build expectations that apply throughout the project. | Broadest reach, so keep rules concise and genuinely useful to most work. |
Nested directory, such as services/api/ |
Service-specific commands, architecture constraints, or package conventions. | Applies only to that subtree, allowing local detail without burdening unrelated work. |
A practical arrangement might put general formatting and contribution expectations in the root AGENTS.md, then document API-specific test commands in services/api/AGENTS.md. Avoid copying all root rules into nested files: both files can apply, and duplicated guidance is harder to maintain when conventions change.
#1 Best Overall
What Codex CLI loads for a task
Directory scope and automatic discovery are related but distinct. The Codex CLI documentation describes instructions from Codex home and project directories from the repository root through the current working directory (CWD), with later directories ordered after earlier ones. The CLI implementation describes collecting the project chain from root to CWD inclusive and not traversing above the project root.
The implementation also describes root detection details: when configuration does not specify markers, .git is the default root marker; if no root is found, discovery considers only the current directory; and an empty marker list disables parent traversal. Configured fallback instruction filenames are supported as well. These are implementation details, not universal guarantees for every Codex version, editor integration, hosted agent, or third-party harness. If the exact set of loaded files matters, check the documentation and configuration for the version and environment you are using.
When a task targets a nested folder, inspect that subtree for local instruction files rather than assuming a root file is the only relevant guidance. For work outside the current working directory, check the applicable instruction files directly instead of assuming they were automatically loaded.
Keep broad instructions short and task-relevant
Use root guidance for rules that really apply across the repository. For specialized procedures, make the reference conditional—for example, “For database changes, consult docs/database.md”—rather than requiring every task to read unrelated architecture, database, and deployment documents. OpenAI’s September 11, 2026 article “Rethinking skills and prompts for GPT-6 Astra” recommends keeping repository guidance useful, relevant to the task, and maintained over time.
Rank #3
For longer procedures, a focused document can hold the detail while AGENTS.md says when to consult it. The archived OpenAI cookbook planning recipe illustrates that separation; treat it as an organizational example, not current Codex discovery documentation.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
