Recommended Free Tools
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. For a file, follow every applicable AGENTS.md in its path; when instructions conflict, the deeper file takes precedence within its subtree.
How AGENTS.md directory scope works
Think of each AGENTS.md as setting guidance for a branch of the filesystem. A file at the repository root can establish conventions across the project; a file in services/api/ can add rules for that service and its descendants. An instruction file does not automatically govern sibling directories.
When working on a file, apply all instruction files whose directory trees include it. For example, a change to services/api/routes/users.ts may be covered by a repository-root AGENTS.md and another in services/api/. The Codex repository specification describes this tree-based scope and says more deeply nested instructions take precedence when they conflict. A deeper file refines guidance for its own subtree; it does not erase broader guidance elsewhere. Codex repository AGENTS.md specification.
Where to put each instruction file
| Location | Use it for | Example |
|---|---|---|
| Repository root | Rules genuinely shared across the project | Shared language, broad contribution conventions, or common build expectations |
| A nested directory | Rules specific to a package, service, or other subtree | Service-local commands, architecture constraints, or package conventions |
Keep root-level guidance short and broadly useful. Put local details near the code they govern, rather than making unrelated parts of the repository inherit them. If a rule applies only to a particular kind of task, phrase it conditionally—for example, “For database changes, consult docs/database.md”—instead of requiring every agent to read that document for every edit.
#1 Best Overall
How Codex CLI finds project instructions
Directory-tree scope and automatic discovery are related but not identical. Codex CLI documentation describes loading global instructions from ~/.codex and project instruction files along the path from the repository root to the current working directory. Its implementation describes collecting that project chain from root to CWD inclusive and not traversing above the detected project root. Codex CLI AGENTS.md guide · Codex CLI project instruction discovery implementation.
In the cited implementation, .git is the default project-root marker when configuration does not specify markers. If no root is found, it considers only the current directory; an empty marker list disables parent traversal. Configured fallback document names are also supported. These are implementation details, not guarantees for every release, editor integration, hosted agent, or third-party harness. When exact loading behavior matters, check the documentation and configuration for the specific tool and version you use.
Check the instruction chain for a task
- Identify the target file and working directory. The directory tree containing the file determines which instructions can apply; the tool’s current working directory and project-root detection affect which files it loads automatically.
- Check from the project root down the target path. Look for an
AGENTS.mdat the root and in each relevant directory between it and the target. For a task below your current working directory, check for nested instructions too; for work outside that directory, do not assume the right instructions were already loaded. - Combine compatible rules and resolve conflicts by depth. Follow all applicable guidance that does not conflict. Where instructions disagree, use the deeper file for its subtree, while higher-priority system, developer, and user directions still outrank repository guidance.
- Place new guidance at the narrowest useful level. Keep a rule at the root only if it should apply broadly; otherwise put it in the relevant subtree. Link to longer documentation when a task needs it instead of making it mandatory for every task.
Keep AGENTS.md useful over time
Instructions are most helpful when they are concise, current, and relevant to the work agents actually perform. OpenAI’s September 11, 2026 article recommends task-specific documentation references and gives this example: “Use architecture.md for service boundaries, database.md for schema changes, and deployment.md when preparing a deployment.” That is a recommendation for organizing contextual guidance, not a rule about Codex’s loading algorithm. Rethinking skills and prompts for GPT-6 Astra.
Review instruction files as the repository changes. Remove stale commands and broad requirements that force readers through unrelated documentation; keep specialized procedures in focused documents and point to them only when the relevant task calls for them.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Best Value
Rank #3
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.
