InterviewLab

AI agents

Codex CLI

Codex CLI project instructions (AGENTS.md)

AGENTS.md is the project-instructions file Codex reads at startup — the place for build/test commands, code style, and repo-specific rules. Generate a scaffold with /init in the TUI.

Discovery order

Instructions are assembled once per run (per TUI session), in this order:

  1. Global scope — in $CODEX_HOME (default ~/.codex): reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file at this level is used.
  2. Project scope — starting at the project root (typically the Git root; configurable via project_root_markers), walking down to the current directory. In each directory Codex checks AGENTS.override.md, then AGENTS.md, then the names in project_doc_fallback_filenames. At most one file per directory. If no project root is found, only the cwd is checked.
  3. Merge — all files found are concatenated root-down, joined with blank lines. Files closer to the cwd appear later and therefore override earlier guidance.

Rules and limits

  • Empty files are skipped.
  • The combined size is capped at project_doc_max_bytes (default 32 KiB).
  • AGENTS.override.md takes precedence over AGENTS.md in the same directory — e.g. services/payments/AGENTS.override.md replaces that directory’s AGENTS.md (useful for local, uncommitted tweaks).
  • The model_instructions_file config key replaces Codex’s built-in instructions entirely — it is separate from (not a substitute for) AGENTS.md.
  • For Codex code review in GitHub, add a ## Code Review Rules section to the AGENTS.md closest to the code being reviewed.

Example AGENTS.md

# AGENTS.md — example-repo

## Project
Go 1.22 microservice. Entry point: cmd/server/main.go.
Internal packages live in internal/; nothing outside internal/ may import them.

## Build and test
- Build:        make build
- Unit tests:   make test
- Lint:         make lint   (run before every commit)
- Integration:  make test-integration   (requires Docker)

## Code style
- Use gofmt; keep functions under 60 lines.
- Errors: wrap with fmt.Errorf("context: %w", err).
- No new dependencies without discussing first.

## Conventions
- Migrations in db/migrations/ are append-only — never edit applied ones.
- API changes require updating docs/openapi.yaml in the same commit.

## Code Review Rules
- Flag any SQL string concatenation.
- Flag unbounded goroutines.

Keep it concrete: exact commands and hard rules work better than general advice. Subdirectory AGENTS.md files are a good fit for monorepos, where each package can carry its own instructions.

Last verified: 2026-09-07

Official sources:

AI coding tools evolve quickly. If you find outdated information, please open an issue or pull request.

View this doc on GitHub