How to create an AGENTS.md file for Codex

Repository-specific instructions keep Codex from guessing how a project should be built, tested, reviewed, and changed. A small AGENTS.md file gives each new run the same project conventions before work starts, so repeated reminders become durable repository guidance instead of one-off prompt text.

Codex discovers instruction files when a run starts. It reads a global file from the active CODEX_HOME, then project files from the repository root down to the selected working directory, with closer files appearing later in the model-visible prompt. An AGENTS.override.md file replaces AGENTS.md at the same directory level when both exist.

Keep the root file short and concrete. Put commands, review expectations, ownership rules, and verification criteria in the closest directory where they apply, and keep secrets, tokens, private hostnames, and temporary prompt experiments out of checked-in guidance.

1. Choose the repository that should own the shared Codex guidance.

   $ git -C /work/app rev-parse --show-toplevel
   /work/app

   Use the repository root when the rules should apply to the whole project. Use a nested directory only when that subtree needs different instructions.

   Related: How to set the working directory for Codex

2. Create the root AGENTS.md file from the repository root.

   $ vi AGENTS.md

   Inside an interactive Codex session, /init can generate a starter AGENTS.md for the current project. Edit the generated file before committing it so the rules match the actual repository.

   Related: How to start a Codex interactive session

3. Add concise repository expectations.

   AGENTS.md

   # AGENTS.md
    
   ## Repository expectations
    
   - Run npm test before opening a pull request.
   - Document public utilities in docs/ when behavior changes.
   - Ask before adding production dependencies.
   - Keep generated reports under tmp/artifacts/.

   Prefer rules that name exact commands, paths, review expectations, or completion checks. Move long architecture notes into separate docs and link them from AGENTS.md only when Codex needs the routing rule.

4. Add a nested override when one subtree needs different rules.

   $ vi services/payments/AGENTS.override.md

   AGENTS.override.md

   # AGENTS.override.md
    
   ## Payments service rules
    
   - Use make test-payments instead of npm test.
   - Never rotate API keys without notifying the security channel.
   - Keep fixtures under testdata/.

   AGENTS.override.md replaces AGENTS.md at the same directory level. A nested override is useful when a service, package, or team directory has stricter commands than the repository default.

5. Configure fallback filenames only when the repository cannot use AGENTS.md directly.

   ~/.codex/config.toml

   project_doc_fallback_filenames = [
     "TEAM_GUIDE.md",
     ".agents.md",
   ]
   project_doc_max_bytes = 65536

   Codex still checks AGENTS.override.md and AGENTS.md first. Fallback names are for existing team files that should be treated as instructions instead of copied into a new file.

6. Check the model-visible instruction payload from the target working directory.

   $ codex -C services/payments debug prompt-input "Show instructions."
   [
     ##### snipped #####
     "text": "# AGENTS.md instructions for services/payments
   
   ##### snipped #####
   # AGENTS.md
   
   ## Repository expectations
   
   - Run npm test before opening a pull request.
   - Document public utilities in docs/ when behavior changes.
   
   # services/payments/AGENTS.override.md
   
   ## Payments service rules
   
   - Use make test-payments instead of npm test.
   - Never rotate API keys without notifying the security channel.
   ##### snipped #####"
     ##### snipped #####
   ]

   codex debug prompt-input renders the prompt context locally, so it can confirm instruction discovery before an authenticated model request is sent. The command prints more JSON than shown.

7. Ask an authenticated read-only Codex run to summarize the active instructions.

   $ codex -C services/payments \
     --ask-for-approval never exec \
     --sandbox read-only "Summarize instructions."
   OpenAI Codex v0.139.0
   --------
   workdir: /work/app/services/payments
   approval: never
   sandbox: read-only
   ##### snipped #####
   - Repository: run npm test before pull requests.
   - Payments: use make test-payments.

   If this reports missing authentication, log in or provide a supported API key, then rerun the same command.
   Related: How to check Codex login status