AGENTS.md is project-level working instructions for Codex. It should record real build commands, directory boundaries, code conventions, and acceptance requirements so every task starts from the same set of reviewable rules. It is not a replacement for README, and it should not be filled with temporary notes that apply only to a single task.
OpenAI’s current documentation states that Codex reads AGENTS.md before starting work and merges global rules with project-directory rules in order. Making this reliable depends less on writing more content and more on placing rules at the correct level and defining clear ways to verify them.
What AGENTS.md is for
An effective project brief should answer the questions Codex must know before starting and can verify from the repository:
- What package manager, runtime, and primary commands the project uses;
- Which checks to run when modifying different directories;
- Which files are generated by tools and must not be edited by hand;
- Which user changes, secrets, media, or production data must be preserved;
- Which results and unverified items to report when completing the task.
Rules should translate into concrete behavior. For example, “run pnpm check after modifying TypeScript” is more actionable than “keep code quality high”; “do not write .env values into logs or commits” is easier to verify than a vague “be careful about security.”
How Codex discovers and merges rules
OpenAI’s official documentation describes the discovery order as a global part and a project part, and the instruction chain is established only once per run. In an interactive terminal, this usually means a new session triggers rediscovery.
- Global scope: Codex looks for rules in
CODEX_HOME; the default location is~/.codex. If a non-emptyAGENTS.override.mdexists, it takes priority overAGENTS.md. - Project scope: Codex walks from the project root, usually the Git root, to the current working directory. At each directory level it checks
AGENTS.override.md, thenAGENTS.md, then configured alternate filenames; at most one file is adopted per directory. - Merge order: Rules are added from the root directory to the current directory. Files closer to the current directory are added later, so they can override higher-level instructions.
Empty files are skipped. The current official documentation also states that merged content is subject to project_doc_max_bytes, with a default limit of 32 KiB. When approaching the limit, remove duplicated instructions or move rules that apply only to a specific subdirectory downward instead of blindly raising the size.
How global, project, and subdirectory rules divide responsibility
Place rules by scope, not by author or date.
~/.codex/AGENTS.md # Personal cross-project habits
my-repo/AGENTS.md # Repo-wide stack and overall acceptance
my-repo/apps/web/AGENTS.md # Web app commands and boundaries
my-repo/packages/api/AGENTS.md # API package rulesPut only genuinely stable cross-project preferences in the global file, such as preserving user changes, reading repository documentation first, and not outputting secrets. The repository root file is responsible for a consistent toolchain, directory structure, and pre-commit checks. Subdirectory files only add or override the differences needed by that directory—for example, the web package uses browser tests while the API package needs contract tests.
AGENTS.override.md is suitable for explicit temporary overrides, but in the same directory it replaces the normal AGENTS.md; it is not appended after it. Remove the override file after the temporary issue ends, otherwise later sessions may keep using outdated rules.
Writing actionable project rules
Here is a minimal structure example. Commands must be replaced with scripts that actually exist in the repository; do not copy the sample as a universal template.
Project agent rules
## Stack
- Astro static output with strict TypeScript.
- Use pnpm only.
## Before editing
- Read docs/CONTENT.md for editorial changes.
- Preserve existing user changes shown by Git status.
## Validation
- Run pnpm check after TypeScript or Astro changes.
- Run pnpm validate before handing off publishable work.
## Security
- Never print or commit .env values.
- Keep editorial media outside public/ and dist/.Write rules as “trigger + action + result” to make them easier to maintain. For example, “run pnpm build after modifying content collections and confirm the new URLs appear in the sitemap” states when to run, what to run, and what to check.
Do not write frequently changing model names, prices, or platform defaults as permanent rules. When they are truly needed, require the task to consult official documentation on the day of execution and record the verified source.
Managing a monorepo with layered rules
If a repository contains both a website and a command-line tool, the root directory can define only the shared boundaries: use the same package manager, do not modify generated files, and check Git differences before delivery. Then write the site build and accessibility checks in apps/site/AGENTS.md, and the CLI testing and compatibility requirements in packages/cli/AGENTS.md.
When Codex starts from apps/site, it merges instructions from the global, repository root, and apps/site scopes, but it will not automatically load packages/cli/AGENTS.md just because it exists in a sibling directory. This avoids unrelated commands polluting the current task and keeps local rules shorter.
If a local requirement conflicts with the root rule, the subdirectory file should explicitly state the override scope and reason, for example: “This directory runs site checks only, not backend integration tests.” A vague “ignore the rules above” makes boundaries hard to audit.
Verify what the current session actually loaded
After writing the files, do not just check whether they exist. OpenAI’s official page gives two ways to verify:
codex --ask-for-approval never "Summarize the current instructions."
codex --cd apps/site --ask-for-approval never "Show which instruction files are active."The first confirms whether the global and current project instructions enter the instruction chain; the second checks local rules from a different working directory. These prompts are read-only verification requests and should not make Codex modify files.
If you need to investigate the discovery process, use a one-off config to write logs to a controlled directory:
codex -c log_dir=./.codex-logLogs and session files may contain local paths, prompts, or project context, and should not be committed or shared publicly. After review, handle these diagnostic files according to project security policy.
Common mistakes and troubleshooting order
File exists but does not take effect
First confirm the file is not empty, then confirm the working directory is inside the intended project path. Check whether a higher-priority AGENTS.override.md exists in the same directory, and whether the filename capitalization is correct. After changing rules, start a new session so Codex rebuilds the instruction chain.
Subdirectory rules override content they should not
Review every rule file from the root directory to the current directory. Instructions closer to the current directory are placed later, so an overly broad local rule can override repository requirements. Change the override to a specific directory, file type, or command condition.
Alternate filenames are not read
Only names configured in project_doc_fallback_filenames take part in discovery. Each directory adopts at most one file, and AGENTS.override.md and AGENTS.md take priority. Do not maintain multiple alternative files with different content and expect them all to load.
Rules later in the file disappear
Check whether the merged content hits project_doc_max_bytes. First remove duplicated passages, long background, and instructions already available from README, then move local rules to the applicable subdirectory. Raising the limit increases context cost for every session and is not a substitute for content governance.
Maintenance and review checklist
Whenever project commands, directories, or release processes change, review AGENTS.md at the same time. At minimum, confirm:
- All commands still exist in
package.json, task files, or CI; - Rules do not require Codex to fabricate tests, deployments, or dates;
- Global and project files do not duplicate large blocks of content;
- Temporary
AGENTS.override.mdfiles have been cleaned up after their purpose ends; - New subprojects have the necessary local rules while still inheriting repository security boundaries;
- Verification commands can reproduce the current instruction chain from the correct working directory.
If you have not installed the terminal tool, start with the Codex CLI setup tutorial; when you need to understand commands inside a session, continue with Codex CLI common commands.
FAQ
Does AGENTS.md automatically run its commands?
No. A command appearing in the file is not unconditionally executed. It gives Codex task rules; actual commands are still constrained by the current task, permissions, approval, and sandbox boundaries. Operations involving installation, network, or production should also keep an explicit human check.
Should README and AGENTS.md have the same content?
Not necessarily. README introduces the project to developers; AGENTS.md is better for recording operational boundaries and validation requirements that agents must follow while working. They can reference the same real commands, but do not copy entire background explanations.
After modifying AGENTS.md, does the current session update immediately?
Official documentation states the discovery chain is established once per run. To avoid old content, start a new session after changes and confirm the active rules with a read-only verification prompt.
Can I create separate AGENTS.md files for different packages?
Yes. Put rules in the corresponding subdirectories. When Codex works from that directory, it merges instructions from the root to the current directory. Local rules should only override the parts that are truly different.