Codex AGENTS.md Template — Project Context for OpenAI Codex

Why AGENTS.md is not CLAUDE.md

OpenAI Codex reads project context from a top-level AGENTS.md. Two facts about that file trip teams up immediately. First, Codex parses the document as plain Markdown — it does not strip a YAML frontmatter block the way Claude Code does. If you put --- and a key-value header at the top, Codex treats those lines as visible content and the heading hierarchy gets confused. Second, the line-count budget is real: Codex’s context window is healthier than people assume, but its attention falls off well before the file fills. Stay under 400 lines; the template below is comfortably under 80. Compare with the Vite CLAUDE.md template — the two files look superficially similar and behave very differently.

The template

# AGENTS.md

This file is read by OpenAI Codex on every task in this repository.
Keep it concise. Codex reads top-down; the highest-priority rules go first.

## Tech stack

- Vite 7, React 19, TypeScript 6
- Vitest 3 for unit and component tests
- Tailwind v4 utilities + daisyUI 5 components only
- pnpm 9 — npm and yarn are not used here

## Where things live

- src/components/ — one component per file, default export
- src/lib/ — framework-agnostic helpers, fully unit-tested
- src/pages/ — Astro pages or React Router routes
- src/content/ — MDX content collections
- scripts/ — Node CLI scripts; tsx-runnable

## Commands Codex may run

- pnpm install — refresh dependencies
- pnpm dev — start the local dev server
- pnpm test --run — run the full Vitest suite once
- pnpm build — produce the production dist/
- pnpm exec tsc --noEmit — type-check only

## Conventions Codex must follow

- TypeScript strict mode is on; do not introduce any-typed values.
- React components are function components only; no class components.
- Style with Tailwind utilities; do not introduce CSS Modules or styled-components.
- New runtime dependencies require an explicit human approval step — flag and stop.
- All async UI surfaces a visible loading state and a visible error state.

## Forbidden patterns

- Do not edit pnpm-lock.yaml directly; run pnpm install instead.
- Do not commit .env or .env.local; use .env.example as the canonical schema.
- Do not bypass the existing router; mount new pages on the existing one.
- Do not add a logging library to debug an issue; remove console.log before commit.

## Output format Codex must emit

1. One paragraph naming the files you will touch and why.
2. The diff per file (full file for new files; minimal diff otherwise).
3. The exact verification commands Codex ran and their truncated output.
4. One sentence flagging anything you intentionally left out of scope.

— lastVerified: 2026-05-08

Why each section earns its place

The Tech stack block is what stops Codex reaching for npm install on a pnpm project, and what stops it from suggesting a v3 daisyUI class on a v5 codebase. Naming Vitest 3 explicitly matters because the v2 → v3 API drift around vi.useFakeTimers is exactly the surface Codex will hallucinate on if you leave the version off. The Where things live block keeps the agent from scattering helpers across utils/, helpers/, and services/ directories that did not previously exist. The Commands block is the contract — Codex’s Run tool can only invoke commands you list, and listing extras (a non-existent pnpm e2e) gets surfaced as a “command failed” without the agent realising the command was made up. Forbidden patterns deserve their own header; folding them into Conventions makes them disappear in skim mode.

Variants by Codex strictness level

The agent-rules generator at /tools/ai-agent-rules-generator?agents=codex emits three flavours of this template; the table below shows what changes between them.

Pick conservative when you are onboarding the agent to a brittle codebase; pick aggressive when the team is mature and the file is already long. The middle row is the default the generator emits, which is the template above.

Common pitfalls when authoring AGENTS.md

The recurring failure modes are: emitting YAML frontmatter at the top — Codex treats the --- lines as content and the document heading order breaks; counter by deleting any frontmatter before saving. Exceeding 400 lines of body — the validator at scripts/validate-templates.ts enforces this in CI; counter by splitting per-feature notes into separate files referenced from a short top-level AGENTS.md. Reusing CLAUDE.md content verbatim — the two formats look the same but Codex parses headings differently than Claude Code does, and the locked-decisions trick that works in CLAUDE.md scatters across an AGENTS.md that has too many H2s. For the Cursor counterpart, see the Cursor rules template. For the Claude-side bug-fix prompt that pairs naturally with AGENTS.md projects, see the Claude Code bug fix prompt — the prompt structure ports cleanly across both agents.