AGENTS.md

If you could learn just one file to sustainably improve Codex’s performance, start with AGENTS.md.

It’s not a conventional README meant for humans—it’s a project specification document written for coding agents. As stated in the official AGENTS.md guide, Codex reads these files before beginning work and merges global, project-level, and subdirectory-specific rules in order. Rules defined closer to the current working directory take precedence—overriding earlier ones.

Don’t keep project rules only in chat history. What truly works is embedding them directly into AGENTS.md, configuration files, or repository documentation—so Codex reads the same set of boundaries every time it enters the project.

I explicitly document high-risk directories, test commands, deployment procedures, and commit conventions. That way, when switching threads, models, or tasks later, those rules remain safely versioned in the repo—not left to human memory.

What Should Go in AGENTS.md?

A practical AGENTS.md can begin with these core sections:

When maintaining AGENTS.md and config files, prioritize clarity on:

• Project boundaries
• Required commands
• Code style expectations
• Security constraints
• Deployment protocols

# AGENTS.md

## Project
- This is a Next.js site.
- Content lives under `content/`.
- Public images live under `public/images/`.

![Codex Practice Reflection Card](/images/codex-zero/lesson-05-practice-review-card.svg)

After reading “`AGENTS.md` and `config.toml`: Entrusting Project Rules to Codex”, take one minute to reflect: Are key concepts clearly distinguished? Can the practice steps be reliably reproduced? Can you restate the conclusions in your own words?

## Commands
- Build: `npm run build`
- Dev: `npm run dev`
- Do *not* add dependencies unless explicitly requested.

## Working Rules
- Keep changes small and tightly scoped.
- Do *not* edit `.env`, certificates, private keys, or auto-generated folders.
- Before delivering the final response, summarize all modified files and verification outcomes.

## Content Rules
- Chinese tutorials must be practical and concrete.
- Avoid generic, AI-sounding language.
- Every tutorial article must include a cover image.

Be specific. Avoid vague directives like “be careful” or “write clean code.” Instead, write actionable rules: ✅ “Run npm test after modifying any JS file.” ✅ “Never modify .env.” ✅ “Place new content images in public/images/.”

Separate Global and Project-Level Rules

As noted in the official documentation, Codex first reads the global AGENTS.md located in your Codex home directory (typically ~/.codex), then overlays the project’s AGENTS.md.

We recommend this division:

• ~/.codex/AGENTS.md: Personal preferences—e.g., preferred response language, review depth, whether explanations should be prioritized.
• Project root AGENTS.md: Project-specific details—commands, directory structure, testing requirements, deployment red lines.
• Subdirectory AGENTS.md or AGENTS.override.md: Localized, granular rules—for example, for payment services, frontend pages, or content directories.

Team-wide rules belong in the project repo. Personal habits belong in your local ~/.codex.

Start with /init

Per official best practices, the CLI command /init generates a starter AGENTS.md in your current directory. It’s a great starting point—but must be customized afterward.

/init

I typically let Codex generate the initial version, then immediately add three critical items:

1. The actual build command used in the project
2. Files/folders that must never be modified
3. Mandatory verification steps to complete before finalizing output

config.toml Controls Behavior; AGENTS.md Defines Rules

• AGENTS.md defines what the agent should do—the project’s rules, constraints, and expectations.
• config.toml configures how Codex behaves—model selection, reasoning effort, sandbox settings, approval policies, MCP server endpoints, and feature flags.

Official best practices recommend:

• Place personal defaults in ~/.codex/config.toml.
• Store project-specific behavior in .codex/config.toml (at the project root).
• Override settings temporarily using CLI flags like -c key=value.

New users shouldn’t copy-paste large config templates upfront. Begin with default permissions—and only add configurations incrementally once you’ve identified precisely what a given project requires.

When to Update AGENTS.md

Update AGENTS.md whenever Codex repeatedly makes the same mistake. For example:

• It consistently uses npm instead of the project’s actual package manager (pnpm).
• It edits auto-generated files.
• It forgets to run build before deploying.

Turn each recurring issue into an explicit, unambiguous rule—and the next iteration will avoid that pitfall.

While practicing “AGENTS.md and config.toml: Entrusting Project Rules to Codex”, record input conditions, actions taken, and observable outcomes together—making future review fast and reliable.

When reviewing “AGENTS.md and config.toml: Entrusting Project Rules to Codex”, consolidate key concepts, procedural steps, and visible results onto a single page for efficient re-engagement.

References:

• Custom instructions with AGENTS.md
• Codex config basics
• Codex customization