Practical Guide to AGENTS.md: Custom Project Specs for Codex

What is AGENTS.md

AGENTS.md is a plain‑markdown instruction file placed in the project root. Codex reads it automatically at the start of every new conversation. The official definition calls it “a simple, open format for guiding coding agents”.

Three key attributes: Simple (just a markdown file), Open (managed by the Agentic AI Foundation, supported by over 25 tools such as OpenAI Codex, Google Jules, GitHub Copilot, Cursor, Aider, Zed, JetBrains Junie), and Guiding (provides project context, not code or documentation).

The only criterion for adding a rule is whether the AI must know it every time a conversation starts.

Minimal 12‑line template

Place an AGENTS.md in the project root and paste the following minimal version, replacing the placeholder commands with the real ones for your project.

# AGENTS.md

## Development commands
- `pnpm install` — install dependencies
- `pnpm test` — run tests (must all pass to be “done”)
- `pnpm lint` — lint code

## Project structure
- `src/` — source code
- `tests/` — test files
- `src/generated/` — auto‑generated code, never edit manually

## Boundaries
- Never push `main` branch or `.env` files containing secrets

With this file Codex stops making three common mistakes: running the wrong command, changing the wrong directory, and pushing directly to main.

Growing the file

Detailing project structure

Replace the generic src/ and tests/ entries with the actual directories that must not be altered, e.g.

## Project structure
- `src/app/` — Next.js App Router
- `src/lib/db.ts` — Prisma client entry
- `src/components/ui/` — shadcn/ui component library (do not edit)
- `prisma/` — database models and migrations
- `tests/` — test cases
- `src/generated/` — auto‑generated code, never edit

Mark “dangerous” directories so the AI knows not to modify them.

Three‑tier boundaries

The boundary section is expanded into three explicit categories: Always do, Ask first, Never do.

## Boundaries
### Always do
- Run `pnpm test` and `pnpm lint` before each commit
- Use Conventional Commits for commit messages

### Ask first
- Add new npm dependencies
- Change `prisma/schema.prisma`, `next.config.js`, or CI configuration

### Never do
- Push directly to `main` (use PRs)
- Commit `.env` or any secret files
- Edit `src/generated/` directory

Explicit imperative language is preferred because AI follows concrete commands more reliably than vague suggestions.

Code‑style rules

Never send an LLM to do a linter's job.

Only include style rules that linters cannot enforce, such as project‑specific conventions:

## Code style
- Use zustand for state management; do not introduce Redux
- Database access must go through the singleton `src/lib/db.ts`; never instantiate a new PrismaClient
- Business errors should use the custom `ApiError` class; system errors may use `throw`

Test conventions

Define what “finished” means for the AI:

## Test conventions
- Test files are named `*.test.ts` and sit next to source files
- After any code change, all related tests must pass; never submit before fixing failing tests
- End‑to‑end tests use Playwright with configuration in `playwright.config.ts`
- Never delete or skip failing tests without asking

Analysis of >2500 agents files showed that silently deleting failing tests is a frequent source of hidden bugs.

Multi‑directory projects

In monorepos, a single root AGENTS.md is insufficient. Place additional files in sub‑directories (e.g., frontend/AGENTS.md, backend/AGENTS.md) so each tool reads the most relevant rules without interference.

Codex merges files in three layers: global (~/.codex/), project (from repository root down to the current working directory), and per‑directory overrides. The later a file appears in the merge order, the higher its priority.

Example hierarchy:

my-saas/
├── AGENTS.md               ← repository‑wide rules
├── frontend/
│   └── AGENTS.md           ← frontend‑specific rules
└── backend/
    └── AGENTS.md           ← backend‑specific rules

When running Codex inside backend/, the files are read in the order: ~/.codex/AGENTS.md, my-saas/AGENTS.md, my-saas/backend/AGENTS.md. The last file’s rules overwrite earlier ones for the same keys.

Override and fallback filenames

AGENTS.override.md

replaces the regular file only for its own directory; higher‑level files are still merged. This allows a subdirectory to swap a rule set without discarding the rest of the chain.

Projects that already use a different filename (e.g., TEAM_GUIDE.md) can add it to the fallback list in ~/.codex/config.toml:

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

Size limits and maintenance

Codex discards merged content that exceeds project_doc_max_bytes (default 32 KiB). In practice a few dozen lines are far below this limit. When the limit is approached, the recommended action is to prune and restructure rather than increase the limit.

Treat AGENTS.md as a living document. Add a rule whenever the AI repeats a mistake, delete obsolete rules, and move ignored rules into the “Never do” section to make them more visible.

Interaction with CLAUDE.md

Claude Code reads only CLAUDE.md, not AGENTS.md. To use both Codex and Claude Code, either import AGENTS.md inside CLAUDE.md with @AGENTS.md or create a symbolic link:

ln -s AGENTS.md CLAUDE.md

This keeps a single source of truth while satisfying each tool’s filename expectations.

Full template

The article ends with a complete 50‑line template that can be copied and adapted to any project. It includes sections for project overview, commands, structure, tech stack, code style, test conventions, boundaries, and references.