AGENTS.md gives AI coding agents durable repository guidance about setup, scope, commands, permissions, tests, evidence, and review. The useful file is not a long style manifesto. It tells an agent how work in this repository differs from generic software work and how to prove completion. Hierarchical files let a root define shared rules while a closer subtree file adjusts commands or risk controls for specialized code.
Put stable repository facts in the root file
The root AGENTS.md should cover the repository map, supported runtime, dependency manager, standard setup, formatting and test commands, generated-file policy, security boundaries, and the expected completion report. State which files are canonical and which artifacts must not be edited directly. Name commands exactly and say when each command is required. If a test is expensive or environment-dependent, provide the safe fallback and the evidence needed when it cannot run.
Write rules as observable behaviors. Prefer instructions such as run the unit suite after changing application logic, preserve unrelated worktree changes, and report skipped checks with their reason. Avoid vague demands to be careful or follow best practices. The planning questions in three tests before AI integration also apply to repository rules: every instruction should protect a real task, have an owner, and lead to evidence that a reviewer can inspect.
Keep secrets, credentials, customer data, and mutable production state outside the file. AGENTS.md can describe how to request access or which operation needs approval, but it should not contain the sensitive value. Separate behavioral guidance from controls that must be enforced by the sandbox, identity provider, branch protection, or continuous integration.
Use closer files for real subtree differences
Codex builds an instruction chain from global guidance and the project root toward the working directory. Files closer to the working directory appear later, so their guidance can override broader rules. At each directory, an override file has priority over the regular file. That makes placement part of the design: keep shared expectations at the root and put a specialized rule as close as possible to the code it governs.
Consider a repository with a services directory and a payments subtree. The root file defines the package manager, standard lint command, ordinary test command, documentation rule, and a prohibition on external writes. A payments AGENTS.override.md replaces the ordinary test command with the payments integration suite, requires a migration compatibility check, and states that the agent may not rotate credentials or alter payment state without explicit authority.
The nested file should not repeat the entire root. Repetition creates drift and makes it unclear which statement is intentional. Record only differences and safety additions. If the team needs facts from company records, keep retrieval authoritative and bounded; company memory beyond vector search explains why similarity alone cannot decide the source of truth for an agent.
Verify behavior with the same task before and after
Create a controlled repository task that touches ordinary code and another that runs from the payments subtree. Before adding or changing guidance, capture the instruction sources the agent reports, the commands it proposes, the files it changes, the verification it runs, and any risky action it requests. This creates an evidence baseline rather than an anecdote.
Run the same tasks after the root and nested files are in place. The root task should use the shared commands. The subtree task should retain root expectations but use the specialized test and permission boundary. Review the diff and command trace, not only the agent’s summary. Apply independent checks for agent metrics if completion counts or test claims are reported.
Frequently Asked Questions
Include stable setup commands, repository structure, scope boundaries, canonical files, required tests, permission limits, review expectations, and completion evidence.
Codex combines project guidance from the root toward the working directory, so a closer file can refine or override broader instructions for its subtree.
Use it where a directory needs a deliberate replacement for the regular guidance, such as specialized tests or stricter permissions for sensitive code.
Repeat the same bounded tasks and compare loaded sources, proposed commands, changed files, verification evidence, permission requests, and reviewed diffs.
Restart the agent run when instruction files change because the chain is loaded at the start. Add a regression task when a rule prevents a recurring failure, and remove rules that no longer match the repository. If you need to design an agent workflow and its repository operating contract, discuss AI agent development with AI4SALE.