Configure AGENTS.md

Choose the right scope

Configuration 1

Understand the discovery chain

Codex loads global guidance first, then walks from the project root—normally the Git root—down to the current working directory.

1. At the global level, `~/.codex/AGENTS.override.md` wins over `~/.codex/AGENTS.md`.
2. At each project directory, Codex checks `AGENTS.override.md`, then `AGENTS.md`, then configured fallback names, and includes at most one.
3. Root guidance appears before deeper guidance, so the more specific file can override it.
4. Discovery happens once per run; start a new session after changing instructions.

Important: Codex stops adding project instruction files at the configured size limit, 32 KiB by default. Keep root guidance compact and scope details closer to the code.

Configuration 2

Make the root file a repository contract

The root file should answer how to orient, work safely, verify changes, and hand off—not explain the entire product.

1. Copy commands from repository files and CI, then run them.
2. Name non-obvious source-of-truth and generated directories.
3. Keep critical controls in permissions, hooks, or CI; AGENTS.md is instruction context, not a security boundary.

# Repository Instructions

## Commands
- Test: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Boundaries
- Do not edit generated output in `dist/`.
- Ask before migrations, deployments, or external writes.

## Definition of Done
- Relevant checks pass.
- The diff contains no unrelated changes.
- Report commands, results, and remaining risks.

Configuration 3

Add nested instructions only for real differences

A nested file should contain the delta for its subtree, such as a different language, test runner, ownership boundary, or release process.

1. Do not copy root safety and handoff rules into every package.
2. State which root command must still run after a package-specific check.
3. Resolve contradictions explicitly instead of relying on file order as hidden behavior.

AGENTS.md
apps/
  web/
    AGENTS.md
services/
  billing/
    AGENTS.override.md

Configuration 4

Share facts across tools without duplicating them

Use AGENTS.md as the shared repository contract when multiple agents support it. Tool-specific files should import or add only the behavior unique to that tool.

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`.

Important: Claude Code reads `CLAUDE.md`, not AGENTS.md directly. The import belongs in CLAUDE.md.

Validation checklist

• Start Codex at the repository root and ask it to summarize active instructions.
• Start a new run from a nested package and confirm both shared and package rules are present.
• Check that every command in the file exists and completes in the intended environment.
• Make one bounded test change and verify the required handoff evidence appears.
• Review global, root, nested, and override files together for contradictions.

Common configuration mistakes