AGENTS.md Template for Codex and Claude Code

How Codex loads AGENTS.md

Run /init inside Codex and it creates an AGENTS.md with instructions for your project. Codex builds its instructions from these files each time it starts.

1. Global: your Codex home folder (~/.codex by default). It checks AGENTS.override.md first, then AGENTS.md, and uses the first non-empty one.
2. Project: it starts at the project root (usually the git root) and walks down to the folder you're working in, taking at most one file per folder.
3. Closest wins: files nearer your current folder come later, so their rules override the general ones.
4. Size: it stops adding files once they reach 32 KiB combined (the default project_doc_max_bytes). Keep each file short.
5. Changes: restart Codex after editing, because the instructions are built once per run.

The templates

Root AGENTS.md (whole project)

# AGENTS.md

## Project
[Marketing site + booking for a small business]. Main users are on phones.

## Stack
- [Next.js + TypeScript + Tailwind]
- Package manager: [npm] (never switch it)

## Commands
- Install: `[npm install]`
- Dev: `[npm run dev]`
- Check before finishing: `[npm run lint && npm run build]`

## Code style
- Small components in `[components/]`. Reuse before creating.
- Tailwind classes only. No new CSS files.
- Every image has alt text. Every button has a clear label.

## Rules
- Make the smallest change that solves the task.
- Don't edit `.env`, lock files or `[content/legal/]`.
- Ask before adding dependencies.
- When done, list changed files and how to test them.

Subfolder api/AGENTS.md (extra rules for that part only)

# API rules
- Validate every request body before using it.
- Never log emails, phone numbers or payment details.
- Return clear error messages with the right status code.

Use it in Claude Code too, and check it loaded

• Claude Code reads AGENTS.md as your project instructions when there's no CLAUDE.md in your folder or above it. This needs Claude Code v2.1.277 or later.
• Already have a CLAUDE.md? Add a line @AGENTS.md to it, so Claude imports the same rules and you keep one source of truth.
• Check in Codex: from the repo root run codex --ask-for-approval never "Summarize the current instructions.". It should repeat your rules back.

Checked against the official docs (Nov 2026): Codex docs: AGENTS.md · Codex CLI · Claude Code docs: AGENTS.md