Write AGENTS.md for Codex: file locations and project rules

Record project structure, commands, files not to edit and checks before completion. A concrete path and command such as ‘Run pnpm lint in frontend’ is more useful than ‘Write good code.’

Put one-time requests in conversation and retain recurring rules in the file. For long background, link the relevant document and say when to read it. Check that instructions match current procedures rather than accumulating obsolete commands.

By default Codex reads personal instructions under ~/.codex, then collects project instructions from the repository root down to the current working folder. Setting CODEX_HOME changes the personal location. Instructions closer to the current folder can refine or override earlier project rules.

Within a folder, AGENTS.override.md is selected before AGENTS.md; the two are not always read together. Use an override for a temporary exception and check that it does not remain after the exception ends.

The following example is for a project with frontend and backend. Adapt folders and commands to the actual project and merge needed items into any existing AGENTS.md. Copying it unchanged to every repository could run nonexistent commands.

# AGENTS.md ## Working location - Work on screens in frontend/. - Work on the API in backend/. - Read the target service's AGENTS.md first. ## Scope - Do not edit files unrelated to the request. - If generated files need changing, first check how they are generated. ## Verification - After frontend changes, run pnpm lint in frontend/. - Report checks run and anything not verified.

Save the document and try a practice task. Check whether commands run in the right folder and whether unrun checks are reported honestly.

Startup discovery runs down to the current working folder. Starting at the repository root may leave frontend/AGENTS.md outside that path. In the root instructions, explicitly request reading it before UI work, or start in that folder.

In the CLI you can set the working folder and ask which instructions were read. Run this in a project that actually has frontend:

codex --cd frontend "List the paths and key rules of the instructions currently applied. Do not edit files yet."

If an expected file is missing, check paths, filenames and an override in the same folder. After editing instructions, verify in a new run or session to avoid confusing them with startup configuration.

Keep common project rules in AGENTS.md and a specific workflow in a skill. DESIGN.md can collect color, typography and component standards. Do not assume a design document is loaded just because of its filename; say when to read it.

For example, AGENTS.md can say ‘Before UI changes, read frontend/DESIGN.md and inspect existing components.’ A multistep accessibility check can be a separate skill instead of lengthening common instructions.

Start with repetition and commands that no longer match reality. Retain what to follow and how to check it, and link long background separately. A base instruction-size limit also means endlessly adding text can omit some content.

Example verification request: ‘List the sources of current instructions, the folder for this task and checks to run afterward. Identify files you did not actually read separately.’ Compare the answer with the actual files.

Words in AGENTS.md do not change file-access permissions. Instructions guide work; environment permissions also determine what can execute. Check both rules and results.