Skip to content

AGENTS.md — Teaching Codex Your Project

AGENTS.md is a text file that tells Codex how your project works. Put it in your repo root. Codex reads it before doing anything.

Think of it as onboarding docs for an AI teammate.

Where to Put It

Codex looks for instruction files in this order:

  1. Global (~/.codex/AGENTS.md) — Your personal defaults
  2. Repo root — Project-wide rules
  3. Subdirectories — Team or module-specific overrides

Codex concatenates all discovered files from root down to your working directory. Files closer to CWD appear later in the combined prompt and can effectively override earlier ones. A services/payments/AGENTS.md is appended after the root one.

Override Files

AGENTS.override.md supersedes AGENTS.md at the same directory level. Use it for:

  • Temporary rules during a migration
  • Personal preferences that shouldn’t be committed

Remove the override file to restore shared defaults.

Size Limit

Default combined limit is 32KB (project_doc_max_bytes = 32768). Codex stops adding files once the combined size of all discovered AGENTS.md files reaches this limit.

Don’t write a novel. Context window space is precious.

Increase if needed:

project_doc_max_bytes = 65536

Better approach: split instructions across nested directories.

What Every AGENTS.md Needs

Four sections minimum:

Build and Test Commands

## Build

npm run build

## Test

npm test
npm run test:e2e -- --headed  # for debugging

Codex will run these. Don’t assume it knows your stack.

Conventions

## Conventions

- Use TypeScript strict mode
- Prefer named exports over default exports
- Error messages go to stderr, not stdout
- No console.log in production code — use the logger

Architecture

## Architecture

- /src/api — Express routes, one file per resource
- /src/services — Business logic, no HTTP concerns
- /src/db — Drizzle ORM models and migrations
- /src/jobs — Background workers (BullMQ)

Escalation Rules

## Don't Touch

- /src/auth — Security-critical, requires human review
- /migrations — Always ask before creating migrations
- .env files — Never commit, never read secrets

Real Examples

Next.js Project

# AGENTS.md

## Stack
Next.js 15, App Router, TypeScript, Tailwind, Prisma

## Commands
- `npm run dev` — Start dev server (port 3000)
- `npm run build` — Production build
- `npm run db:push` — Push schema changes
- `npm run db:studio` — Open Prisma Studio

## Conventions
- Server Components by default, 'use client' only when needed
- API routes in /app/api, use Route Handlers
- Zod for all input validation
- Never use any type

## Structure
- /app — Routes and layouts
- /components — Shared UI (no business logic)
- /lib — Utilities and API clients
- /prisma — Schema and migrations

## Sensitive
- /app/api/auth — Auth.js config, don't modify
- prisma/schema.prisma — Ask before schema changes

Python/FastAPI Project

# AGENTS.md

## Stack
Python 3.12, FastAPI, SQLAlchemy 2.0, Alembic, Poetry

## Commands
- `poetry run uvicorn app.main:app --reload`
- `poetry run pytest`
- `poetry run alembic upgrade head`

## Conventions
- Type hints everywhere, no Any
- Pydantic models for all request/response
- Dependency injection via FastAPI Depends
- Async by default

## Structure
- /app/api/v1 — Versioned endpoints
- /app/models — SQLAlchemy models
- /app/schemas — Pydantic schemas
- /app/services — Business logic

## Rules
- Never raw SQL, always ORM
- All endpoints need OpenAPI docs
- Tests must use fixtures, not mocks

Monorepo

# AGENTS.md (root)

## Structure
This is a Turborepo monorepo.

- /apps/web — Next.js frontend
- /apps/api — Node.js backend
- /packages/ui — Shared components
- /packages/db — Database client

## Commands
- `pnpm dev` — Start all apps
- `pnpm build` — Build everything
- `pnpm test` — Run all tests

## Rules
- Changes to /packages require testing in all apps
- Use workspace protocol for internal deps: "workspace:*"
- Each app has its own AGENTS.md with specific rules

Then add /apps/web/AGENTS.md and /apps/api/AGENTS.md with app-specific rules.

Anti-Patterns

Too long — Codex loads AGENTS.md into context. 10KB of instructions means 10KB less for your actual code. Be concise.

Too vague — “Write good code” tells Codex nothing. “Use early returns, max 20 lines per function” is actionable.

Outdated — Old build commands or wrong file paths confuse Codex. Update AGENTS.md when your project changes.

Duplicating docs — Don’t copy your README into AGENTS.md. Link to it or summarize the parts Codex needs.

Cross-Tool Compatibility

AGENTS.md works with other AI tools too:

  • Windsurf supports AGENTS.md natively
  • Cursor supports AGENTS.md natively
  • Amp recognizes AGENTS.md
  • Google Jules, Gemini CLI, Devin, Zed, Warp, and others also support it

AGENTS.md is now under the Linux Foundation’s Agentic AI Foundation (AAIF). Same format, multiple tools. Worth maintaining even if you switch later.

Custom File Names

Some teams use different names. Configure fallbacks:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md", "CODEX.md"]

Codex checks these in order if AGENTS.md doesn’t exist.

Verify Your Setup

Check what Codex sees:

codex --ask-for-approval never "Summarize your current instructions"

Logs are at ~/.codex/log/ if you need to debug what files loaded.