AGENTS.md — Project Memory for Codex

Discovery, layering, and the override file

AGENTS.md is to Codex what CLAUDE.md is to Claude Code: a markdown file the agent reads automatically. Same idea, slightly different mechanics. Codex looks for AGENTS.md at every level from the Git root down to your CWD, plus the global ~/.codex/AGENTS.md. Files merge top-down; closer-to-CWD wins on conflicts.

The override file: AGENTS.override.md. When present at any level, it takes priority over the regular AGENTS.md at that level. Use it for temporary global overrides — sprint-specific rules, "this week, only test code," or to disable normal style preferences while running a migration.

project_doc_fallback_filenames in config.toml lets you reuse existing instruction files (TEAM_GUIDE.md, .agents.md, AI_GUIDE.md) instead of renaming. project_doc_max_bytes caps the size — useful when an over-eager teammate dumps the entire wiki into AGENTS.md.

Code

A real AGENTS.md·markdown

# AGENTS.md — Project Root

## What this is
TypeScript microservices API on Node 22 + Postgres 16, gRPC between
services, JWT RS256 auth.

## Setup
1. npm install
2. docker-compose up -d postgres
3. npm run migrate
4. npm run dev      # port 3000
5. npm test         # vitest

## Code standards
- Strict TS, no `any` (use `unknown`)
- Result<T, E> for error returns where possible
- Functions max 40 lines
- Files max 300 lines

## Important files
- src/config/env.ts — env vars (don't add new ones elsewhere)
- src/types/errors.ts — error types

## Do not
- Commit to main directly
- console.log in app code (use src/lib/logger.ts)
- Hardcode env vars outside config/env.ts

Override + nested layering·markdown

# ~/.codex/AGENTS.override.md
# Sprint override — week of 2026-05-04
All work this week is TEST ONLY. Do not modify production code.
Tests use Vitest. Branch coverage must be 100%.

# services/payments/AGENTS.md (nested, additive)
## Payments — additional rules
PCI-DSS regulated. NEVER log card numbers, CVVs, full PANs.
All encryption: src/lib/crypto.ts (AES-256-GCM).
Stripe calls: src/clients/stripe.ts only.

Exercise

In a real repo, write a layered AGENTS.md hierarchy: a root file with project standards, plus one nested AGENTS.md in a sensitive subdirectory (auth, payments, infra). Run codex --ask-for-approval never "summarize the active instructions" from both the root and the nested directory; verify the nested rules show up only when relevant.

AGENTS.md — Project Memory for Codex

Discovery, layering, and the override file

Code

External links

Exercise

Progress

Comments 0