Write AGENTS.md for Codex: global rules, project rules, and overrides

Use instructions for stable working agreements

Repeated reminders about package managers, validation, and publishing belong in AGENTS.md. Runtime options belong in config.toml. Instructions guide the model; they do not replace filesystem restrictions or approval policy.

Choose the scope

At startup, Codex builds guidance from global instructions, then the project-root-to-working-directory chain. A nonempty AGENTS.override.md takes priority over AGENTS.md in the same directory, with at most one file per level. More local guidance comes later. Starting at the root does not preload every descendant instruction file.

Adapt this project template

# Working in this repository

## Read first
- Read README.md for project layout and setup.
- Inspect existing code and preserve uncommitted user changes.

## Commands
- Install dependencies: npm ci
- Validate the build: npm run build
- Run tests only through scripts that exist in package.json.

## Changes
- Maintain English and Chinese UI copy together.
- Keep real credentials out of source, logs, and examples.
- Do not start or stop a development server owned by the user.

## Delivery
- Explain changes, validation, and unresolved questions.
- Wait for an explicit request before committing or publishing.

These commands illustrate an npm project. Replace them for pnpm, Python, or your actual toolchain. Concrete validation commands and authorization boundaries are more useful than “ensure code quality.”

Keep each layer focused

• Global files hold language and collaboration preferences, not one repository’s commands.
• Project files hold structure and validation facts; update them when paths change.
• Nested files should express differences rather than repeat the entire root file.
• Do not turn credentials, customer information, or large logs into persistent instructions.

Verify loading in a fresh session

codex "Do not edit files. List the project instruction files you loaded and the validation commands for this repository."

If the result is unexpected, inspect the working directory, CODEX_HOME, overrides, empty files, and instruction length. The default combined limit is 32 KiB. Reduce duplication before increasing it.