Write a useful Codex AGENTS.md and check it loads

1. Start with facts from your repository

Use this guide after you can open your project and run a small Codex task. If you are still installing Codex or signing in, finish that setup first. Here the result is a reusable project instruction file, not another installation step.

Read the existing README, instruction files and build configuration. Identify the real test command, important source folders, generated files and any rules your team already follows. Keep an existing AGENTS.md; propose a small change rather than replacing somebody else's guidance.

In an npm project, the command below lists the scripts that actually exist. A Python, Rust or other project needs its own commands. Do not add a test script or install a tool just to make an example instruction look complete.

npm run

2. Write a small, project-specific AGENTS.md

Create AGENTS.md in the repository root for instructions shared across the project. The example below assumes npm test is already the right command. Replace that line with a verified command, or state that no automated tests exist and name the useful manual check.

Choose instructions that change a concrete action. 'Check the changed screen at a mobile width' is more useful than 'make the UI excellent.' Keep temporary task progress in the task discussion rather than making every future session read it.

# Working in this repository

## Checks
- After source or test changes, run npm test.
- For UI changes, inspect the affected view on desktop and mobile.
- Report which checks ran and any failures.

## Changes
- Read existing instructions before editing.
- Preserve unrelated work and keep the patch focused.
- Keep public-facing text in English.
- Change source files rather than generated output.

## Publishing
- Ask before publishing or changing production.
- Do not read or print credentials.

Reference: OpenAI: Custom instructions with AGENTS.md

3. Put each instruction at the right scope

Keep team guidance in the repository. Personal defaults belong in your Codex home. A reusable workflow that should activate only for a matching task usually belongs in a skill, rather than in every project's instruction file.

The official discovery order checks personal guidance, then directories from the project root down to the directory where Codex starts. Within one directory, a non-empty AGENTS.override.md is preferred over AGENTS.md; both are not loaded together. Later project guidance resolves applicable conflicts with broader project guidance, while higher-priority instructions still apply.

Add a nested file only when that folder needs a different instruction. For example, web/AGENTS.md could ask for sentence-case headings and a rendered check after UI edits. Starting at the root does not preload every instruction file in every child folder.

Reference: OpenAI: Custom instructions with AGENTS.md · OpenAI: Build skills

4. Check the active instructions in a fresh session

After saving the file, start a fresh Codex task in the intended project. Ask which instruction sources are already active and which checks apply. Compare the response with the files you wrote. Finding a file on disk is not the same as proving that its contents were included at startup.

For the CLI, open a terminal in your project and start Codex with the first command below. To check a nested file, use the second command from the repository root, replacing web with a real folder. These start interactive sessions; they are not commands to paste into the Codex chat composer.

In the app, start a new task for the intended project and use the read-only verification prompt below. If the response cannot establish which files were provided automatically, treat that part as unknown and inspect the documented instruction sources rather than assuming success.

codex

# CLI: check a real nested folder in a separate session
codex --cd web

Reference: OpenAI: Custom instructions with AGENTS.md · OpenAI: Codex CLI

5. Diagnose missing or conflicting rules

Check the project directory, exact filename, non-empty contents and any AGENTS.override.md at the same scope. If you use a custom Codex home, check that you edited the intended profile. Restart after changing instruction files so the next run rebuilds its instruction chain.

The documented default combined instruction budget is 32 KiB, controlled by project_doc_max_bytes. A large earlier file can leave little room for later guidance. Remove irrelevant material from the active chain before assuming another nested file will solve truncation; preserve important rules and your team's existing policy.

Do not solve a missed instruction by weakening sandbox permissions or moving secrets into AGENTS.md. Instructions guide the model; actual access controls and approval settings govern what it can do. A successful check today also does not prove that every future action will follow the file.

Reference: OpenAI: Custom instructions with AGENTS.md · OpenAI: Permissions

6. Keep the file useful as the project changes

Try one small, reversible task. Review whether Codex used the correct source files, ran the relevant check and reported its result. Fix the smallest inaccurate instruction when the repository or command changes; do not add a long rule for every isolated mistake.

Review the AGENTS.md diff with the same care as other project changes. Remove obsolete commands and duplicated prose. Keep detailed reference material near its own owner and link it when the reader needs it, rather than turning the startup file into a project archive.

Try it in Codex

Check project instructions without changing files

Check the project instructions for this Codex task. Do not edit files, install tools, change permissions, read credentials, commit, push, or deploy.

Report the current project directory and the instruction sources that were already provided to this task. Distinguish automatically supplied instructions from files you only found by inspecting the repository; if startup loading cannot be established, say it is unknown.

Summarize the applicable setup/test commands, important source or generated-file boundaries, and any conflicting project guidance. Check named commands against the repository's actual configuration without running them yet. Explain which instruction applies to the directory where this task started.

Suggest the smallest correction if the file is missing, stale, shadowed by an override, or too large. Preserve existing guidance and unrelated work. Finish with one small task and the checks that would demonstrate the instructions are useful.

Check your result

• The AGENTS.md uses commands and paths that actually exist in your project.
• A fresh task identifies the intended project and its applicable instruction sources, or clearly reports a loading uncertainty.
• A nested-folder check reflects that folder's guidance without confusing a discovered file with an active startup instruction.
• One small task is checked against the instructions; permissions and secrets remain protected.

Sources and scope

Official references support the product behavior described above. The task prompts and practical checks are our community guidance.

• OpenAI: Custom instructions with AGENTS.mdInstruction discovery, per-directory override selection, restart verification and the combined size limit.
• OpenAI: Build skillsTask-specific reusable workflows and how they differ from always-needed project guidance.
• OpenAI: Codex CLIStarting a local CLI session; CLI entry is distinct from a chat prompt.
• OpenAI: PermissionsActual approval and access controls remain separate from prose instructions.

Something changed in your version? Send a correction with the guide URL, platform, and version. Leave out credentials and private project content.