AGENTS.md Deep Dive

AGENTS.md is to Codex what CLAUDE.md is to Claude Code — a markdown file that gives the AI persistent context about your project, conventions, and rules. It is the single most impactful file you can create for improving Codex output quality. Without it, Codex starts every session with zero knowledge of your project's architecture, patterns, and preferences.

Codex supports a hierarchy of AGENTS.md files that merge together. Global files apply to all projects. Repo-level files apply to the entire repository. Directory-scoped files apply only when working within that directory. This hierarchy lets you set personal defaults globally while keeping project-specific rules in the repo.

# AGENTS.md file hierarchy (highest to lowest priority)

~/.codex/AGENTS.md           # Global — your personal defaults
./AGENTS.md                   # Repo root — team-shared rules
./src/AGENTS.md               # Directory-scoped — module-specific rules
./src/api/AGENTS.md           # Deeper scoping — API-specific conventions

# Override files (higher priority than same-level AGENTS.md)
./AGENTS.override.md          # Local overrides, typically gitignored

# Fallback filenames (Codex also recognizes these)
./CLAUDE.md                   # Recognized as a fallback
./COPILOT.md                  # Recognized as a fallback

The /init command analyzes your codebase and generates a starter AGENTS.md. It scans your directory structure, detects frameworks, identifies test patterns, and creates a reasonable baseline configuration. Always run /init on a new project, then refine the output manually.

The project_doc_max_bytes setting controls how large AGENTS.md can be before Codex truncates it. The default is generous, but if your file grows beyond a few hundred lines, consider splitting into directory-scoped files instead.

# Project: E-Commerce API

## Architecture
- Node.js 22 + Express + TypeScript
- PostgreSQL via Prisma ORM
- Redis for session caching
- Jest for testing, Supertest for API tests

## Conventions
- All API routes in src/routes/, one file per resource
- Business logic in src/services/, never in route handlers
- Validate all inputs with Zod schemas in src/schemas/
- Use kebab-case for file names, PascalCase for types

## Commands
- `npm test` — run all tests
- `npm run lint` — ESLint + Prettier check
- `npx prisma migrate dev` — apply pending migrations

## Rules
- Never modify migration files after they are committed
- Always add a test when adding a new endpoint
- Use transactions for multi-table writes