How to Write AGENTS.md for Codex Project Rules and Team Workflows

Codex says a change is done, then pnpm test tells you it never ran the tests. Or, inside a monorepo, it runs the test command for the wrong package from the repo root. Repeating those instructions gets old fast: use npm run build, use pnpm test, do not edit generated files, run lint before you finish. AGENTS.md is where you put those rules so Codex does not need to ask again the next time.

If you have just finished the Codex getting-started guide and entry-point choice, the next step is not to ask it to refactor the whole codebase. First, write down the project rules you keep repeating.

Start with a 12-20 line seed file. Then understand the three loading layers, how to verify that Codex saw the file, what should stay out of it, how it coexists with CLAUDE.md or Cursor Rules, and when it is worth updating.

AGENTS.md is not README. It is Codex’s long-lived project instruction file

README.md is for humans. It explains what the project is, how to install it, and how to get started. AGENTS.md is for Codex. It tells the agent what it needs every time it starts work: how to build, how to test, which directories are off limits, and what checks matter before the task is done.

OpenAI’s documentation says Codex reads AGENTS.md before starting work and includes it as part of the active context. That is different from typing “npm run build” or “pnpm test” into every chat. AGENTS.md is persistent project guidance, so the instruction does not need to be repeated manually.

One boundary matters: AGENTS.md is not a long-term memory system and it does not learn automatically. It is a static instruction file loaded at startup. If you need cross-session knowledge or memory governance, the earlier AI agent memory guide covers the split between long-term memory and project rules.

How Codex finds your AGENTS.md: the three loading layers

Codex loads instructions through three layers: global, project, and merged order. Knowing the order helps you tell where a rule applies and why a rule may appear to be ignored.

Global layer: your personal defaults

Codex first checks your user-level ~/.codex directory. This layer is for personal defaults, such as response language, code style preferences, or common tool habits. The global layer reads at most one file, in this order: AGENTS.override.md -> AGENTS.md. It does not stack both.

Project layer: scan from the Git root to the current directory

For project instructions, Codex scans from the Git root or project root down to the current working directory. At each level it also reads at most one file, in this order: AGENTS.override.md -> AGENTS.md -> fallback filenames. Fallback names can be configured with project_doc_fallback_filenames, for example to include TEAM_GUIDE.md. Treat exact option names as versioned documentation, not as folklore.

Merge order: nearer directories appear later and are more specific

All discovered files are concatenated from root to current directory. The nearer a file is to the current directory, the later it appears in context. That makes the local rule easier for Codex to prioritize.

KiloClaw - Managed OpenClaw for enterprise, enabling AI Agent orchestration and smart model routing

Get Started →Ad

For example, the monorepo root may have an AGENTS.md that says “use pnpm test.” The apps/web/AGENTS.md file may say “use pnpm --filter web test.” If Codex starts in apps/web, it reads root rules first and apps/web rules later. The apps/web test command is the more specific one.

Summary table for the three layers

The root file should contain shared team rules. Subdirectories should contain local rules, such as a different test command for one package. AGENTS.override.md is useful for temporary or local overrides. Do not turn it into the team’s default, because it hides the normal rule file and makes collaboration harder.

Start with the smallest useful template: which 6 blocks matter?

OpenAI describes AGENTS.md as an “open-format README for agents.” The useful pattern is short, true, and verifiable. Do not start by copying a 300-line internet template. Start with six basic blocks and extend only when the project proves it needs more.

The seed file covers these six blocks:

1. repo layout: the stack and directory map, so Codex knows where frontend, backend, and tests live
2. Commands: exact build, test, and lint commands. Write pnpm test, not “run tests”
3. Constraints: directories and actions Codex should avoid, such as src/generated/
4. PR expectations: what should be checked before submitting and what review expects
5. Done when: verifiable completion criteria, such as pnpm test and pnpm build
6. Optional project conventions, such as package manager, code style, or naming rules

Here is a seed file for a SaaS admin project:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

That file is short enough to stay visible in context. Add more only after the project exposes a repeated problem. Do not put the product vision, every dependency, architecture diagrams, or API documentation indexes into the first version. A huge file buries the rules that actually matter.

How to verify that Codex really read AGENTS.md

After writing AGENTS.md, use a verification command instead of assuming it worked. OpenAI’s docs recommend:

codex --ask-for-approval never "Summarize the current instructions."

The response should mention your rules, such as the test command or forbidden directory. If it does not mention them, or it mentions a different rule set, debug the loading chain.

Troubleshooting checklist

If it still fails, check the OpenAI Custom instructions docs or upgrade Codex. Avoid treating AGENTS.md loading as magic. Path, version, config, and current directory all affect the result.

What should not go into AGENTS.md

AGENTS.md is not a universal project warehouse. Some content creates security risk, maintenance burden, or context noise. Keep these out.

1. Secrets, API keys, and production passwords

Any secret, production password, or API token should stay out of AGENTS.md. Codex reads the file into context, and the file may be visible to teammates or committed to Git. Use environment variables, uncommitted .env files, or a dedicated secrets system. If Codex needs secrets inside a sandboxed workflow, handle that as an execution-layer problem.

2. Large lists that go stale

Do not list every dependency, ecosystem number, price, quota, route, or database field. A list like “React 18.2, Vue 3.4, TypeScript 5.0…” goes stale quickly. Write the process for adding a dependency, not the entire current dependency inventory.

3. Abstract slogans

“Keep quality high,” “write elegant code,” and “make it maintainable” are not executable. Replace them with checks: pnpm test passes, pnpm lint has no errors, new features need tests, or Lighthouse Performance should not drop below the agreed threshold.

4. Vague commands

“Run the tests” and “check the build” are too vague. Write exact commands: pnpm test, pnpm build, or lighthouse --preset=desktop.

🔥 Stop wasting months on unwanted products! Validate your SaaS selling points with Adsterra on a tiny budget →

Test MVP Now →Ad

5. Requirements that cannot be verified

“Guarantee better performance” or “make the UX better” has no completion boundary. Use measurable checks instead, such as an API response under 200 ms or a Lighthouse score target.

6. Personal preferences in the repo root

“Reply in Chinese,” “keep answers under 100 words,” or “use VS Code by default” are personal tool preferences, not shared project rules. Put those in ~/.codex/AGENTS.md. Keep the repo root for team-wide standards.

The principle is simple: short, true, and verifiable. AGENTS.md reduces repeated instructions. It is not a place to paste every project document.

If you already have CLAUDE.md or Cursor Rules, do you still need AGENTS.md?

If you use Claude Code or Cursor, your repo may already contain CLAUDE.md or Cursor Rules. You do not need to maintain three duplicate rule sets. Use import or coexistence patterns.

AGENTS.md vs CLAUDE.md: import the shared rules

Claude Code reads CLAUDE.md, not AGENTS.md. If the repo already has AGENTS.md, create a small CLAUDE.md that imports it:

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md is the import syntax. Claude Code reads AGENTS.md first, then the Claude-specific section below it. The shared project rules stay in AGENTS.md, while tool-specific preferences stay in CLAUDE.md.

AGENTS.md vs Cursor Rules: Cursor has its own rule system

Cursor has its own Rules system, including project, team, and user rules. Cursor’s official docs and search summaries mention AGENTS.md support, but the loading details should be checked against Cursor’s current docs. If you use both Cursor and Codex, keep cross-tool project rules in AGENTS.md and leave Cursor-specific editor behavior in Cursor Rules.

AGENTS.md vs config.toml, Rules, Skills, and MCP

AGENTS.md is the instruction layer. It tells Codex how it should work. Execution controls live elsewhere: permissions, sandboxing, command policy, and tool integrations are separate mechanisms.

AGENTS.md solves repeated project-rule explanations. Rules, config, sandbox, and permissions handle enforcement. Skills handle reusable workflows. MCP handles external tools. Treat those boundaries clearly.

When should you update AGENTS.md?

AGENTS.md does not need to change every time the project changes. Update it when the same friction repeats.

Update triggers

OpenAI’s docs recommend updating AGENTS.md in these situations:

1. Codex repeats the same mistake: it edits the wrong directory twice, or keeps running the wrong package test command. Add one concrete constraint, such as “Do NOT edit src/generated/” or “Use pnpm --filter web test for web changes.”

2. PR review repeats the same feedback: reviewers keep saying “this change needs tests,” “do not edit generated code,” or “avoid default exports.” Put that pattern into PR expectations.

3. Codex reads too many files before finding the answer: if it has to dig through several docs to discover the right test command or build flow, add the core path or command near the top.

Update the nearest useful directory

Put the rule where the mistake happens. Do not put every new rule into the repo root. In a monorepo, different packages can have different rules, so each package can own a local AGENTS.md.

If Codex runs the wrong test while working in apps/web, add the rule to apps/web/AGENTS.md. Do not add a root-level rule that accidentally applies to every package.

Vultr - High-performance NVMe VPS with 32 global locations, one-click Docker deploy

View Pricing →Ad

How this differs from long-term memory

AGENTS.md is a static instruction file loaded at startup. It is not an automatically learning memory store. Codex will not update it from your corrections unless you explicitly ask it to.

If you need cross-session project knowledge or memory governance, use the AI agent memory guide as the next reference point.

Growing the template: from seed file to expanded file

Do not start with a 300-line template. Start with a 12-20 line seed file, then extend it only when a repeatable trigger appears.

Seed version: only the 6 core blocks

The seed version covers repo layout, common commands, constraints, PR expectations, and done/verify. It can be this small:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Expansion triggers: when to add another block

After a few runs, expand only for concrete problems:

1. The first time Codex edits the wrong directory: if it touches migrations/ or generated/, add a Constraints rule such as “Do NOT commit migrations/ without team review” or “Do NOT edit any file in src/generated/.”

2. The first repeated PR review note: if reviewers keep asking for tests or named exports, add “Add tests for new features” or “Use named exports, not default exports” to PR expectations.

3. The first package-manager mistake: if a pnpm project gets npm commands, add “Always use pnpm, not npm or yarn” to Commands.

4. The first missed lint check: if Codex finishes without lint, add “pnpm lint passes with no errors” under Done when.

Expanded version: 30-50 lines

An expanded file may add constraints, PR expectations, package manager rules, and lint requirements:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

The core rule is to grow by trigger, not by prediction. AGENTS.md earns its keep by reducing repeated instructions, not by displaying every project document.

Conclusion

AGENTS.md is persistent project guidance. It is not a universal warehouse and it is not a long-term memory system. It solves one concrete problem: you should not have to repeat the same project rules every time Codex starts work.

Practical next steps:

1. Start with a 12-20 line seed file: repo layout, commands, constraints, PR expectations, and done/verify. Do not begin with a giant template.

2. Verify that Codex loaded it: run codex --ask-for-approval never "Summarize the current instructions." and look for your rules in the response.

3. Extend it by repeated triggers: add a rule when Codex repeats a mistake, PR review repeats the same note, or Codex has to dig too far to find the answer.

4. Keep unsafe and stale content out: no secrets, stale inventories, slogans, vague commands, unverifiable goals, or personal preferences in the repo root.

5. Use import or coexistence when you already have CLAUDE.md or Cursor Rules: keep shared project rules in AGENTS.md and tool-specific behavior in each tool’s own file.

AGENTS.md gives Codex stable project context. Later articles in this Codex series can move repeated workflows into Skills, cover permission and secret boundaries, and make done/verify more reliable through failure review and PR checks.