# AGENTS.md Configuration Guide

`AGENTS.md` is to Codex what `CLAUDE.md` is to Claude Code. It's a Markdown file placed in your project that tells the AI coding assistant: what standards this project follows, how code should be written, and what to avoid.

If you're already using Claude Code's `CLAUDE.md`, the concept of `AGENTS.md` will be familiar. They share the same philosophy, but differ in some formatting details. This guide covers `AGENTS.md` configuration in depth and shows you how to efficiently reuse project standards across both tools.

---

> **It is no longer just a Codex file.** In March 2026, Anthropic, OpenAI, Google, AWS, Microsoft
> and Salesforce founded the **Agentic AI Foundation (AAIF)**, which adopted three open specs as
> common ground: **MCP** (the tool and context layer), **AGENTS.md** (the agent behaviour spec),
> and **Goose** (the reference implementation). In practice this means one `AGENTS.md` is read by
> a growing set of tools, not only Codex.

## AGENTS.md vs CLAUDE.md

Before diving into `AGENTS.md`, here's how it compares with `CLAUDE.md`:

| Aspect | AGENTS.md (Codex) | CLAUDE.md (Claude Code) |
|--------|---------------------|--------------------------|
| Tool | OpenAI Codex CLI | Anthropic Claude Code |
| File format | Markdown | Markdown |
| Loading hierarchy | Global / repo root / subdirectory (three levels) | Global / project root / subdirectory (three levels) |
| Global location | `~/.codex/AGENTS.md` | `~/.claude/CLAUDE.md` |
| Override mechanism | Subdirectory can override parent rules | Subdirectory can append/override rules |
| Writing style | Tends toward concise lists, directive style | Supports detailed explanations, conversational style works too |
| Community adoption | Growing rapidly, already adopted by many open source projects | Widely adopted, mature ecosystem |
| Version control | Recommended to commit to the repo | Recommended to commit to the repo |
| Cross-recognition | Does not read CLAUDE.md | Does not read AGENTS.md |

> **Key point**: The two files are mutually invisible. If you use both tools, you need to maintain `AGENTS.md` and `CLAUDE.md` separately. The good news is that the core content can be shared.

---

## Basic Configuration

### File Location

Create `AGENTS.md` in your project root:

```
your-project/
  AGENTS.md          <- repo-level config
  src/
  tests/
  package.json
```

### Basic Syntax

`AGENTS.md` is a standard Markdown file. Codex reads it on startup and follows the instructions within. The most common format is **unordered lists**:

```markdown
# AGENTS.md

- All code should be written in TypeScript with strict mode enabled
- Use Prettier for formatting, ESLint for linting
- Tests use Vitest, placed in `__tests__/` directories
- Run `npm run lint && npm test` before completing any task
- Never modify files in the `vendor/` directory
- API responses must follow the standard envelope format: `{ code, data, message }`
```

You can also use headings to organize rules by category:

```markdown
# AGENTS.md

## Code Standards
- Use TypeScript strict mode
- Variables use camelCase, types use PascalCase
- Each function should be no more than 50 lines

## Testing Requirements
- Unit test coverage target: 80%
- Test files share the source file name with a `.test.ts` suffix
- Mock external dependencies; no real network requests in tests

## Prohibited Practices
- Do not use the `any` type
- Do not manipulate the DOM directly (use React state management)
- Do not use `await` inside loops (use `Promise.all` instead)
```

### Language Choice

`AGENTS.md` content can be written in **Chinese** or **English**. Codex understands both languages correctly. When it comes to team collaboration:

- **Personal projects**: Use whichever language you're comfortable with
- **Team projects**: English is recommended (consistent with code)
- **Chinese-speaking teams**: Chinese works perfectly fine

---

## Layered Configuration

`AGENTS.md` supports three configuration levels, refining rules from global to specific directories:

### Level 1: Global Configuration

Location: `~/.codex/AGENTS.md`

Universal standards that apply to all your projects:

```markdown
# Global AGENTS.md

## General Standards
- Write code comments in English
- Git commit messages follow Conventional Commits
- Never hardcode passwords, keys, or tokens in source code
- Read existing related code before generating new code to maintain consistency
- If unsure about the impact of a change, add a comment explaining it rather than making assumptions

## Output Preferences
- Prefer existing project dependencies; don't introduce new ones unnecessarily
- Error handling must be thorough; never swallow exceptions silently
- Log messages should be meaningful and include context
```

### Level 2: Repo-Level Configuration

Location: `AGENTS.md` in the project root

Standards specific to a particular project:

```markdown
# AGENTS.md

## Project Overview
A React + Node.js full-stack e-commerce project built with TypeScript.

## Tech Stack
- Frontend: React 19 + TailwindCSS + Zustand
- Backend: Node.js + Fastify + Prisma
- Database: PostgreSQL 16
- Testing: Vitest + Playwright

## Code Standards
- Component files use PascalCase: `UserProfile.tsx`
- Utility functions use camelCase: `formatDate.ts`
- API routes use kebab-case: `/api/user-orders`
- Database fields use snake_case: `created_at`

## Project Structure
- `src/components/` - React components
- `src/pages/` - Page components
- `src/api/` - Backend API routes
- `src/lib/` - Shared utility library
- `prisma/` - Database schema and migrations

## Commands
- `npm run dev` - Start the dev server
- `npm run build` - Build for production
- `npm test` - Run all tests
- `npm run lint` - Run linting
- `npx prisma migrate dev` - Run database migrations
```

### Level 3: Subdirectory Configuration

Location: `AGENTS.md` in any subdirectory

Additional rules for specific modules, **layered on top of parent-level rules**:

```
your-project/
  AGENTS.md                  <- project-level rules
  src/
    components/
      AGENTS.md              <- component directory rules
    api/
      AGENTS.md              <- API directory rules
```

Example `src/components/AGENTS.md`:

```markdown
# Component Standards

- All components must be function components (no class components)
- Props must have a TypeScript interface definition
- Every component must have a displayName
- Use TailwindCSS for styling; no inline styles
- Split complex components into sub-components; keep each file under 200 lines
- Reusable components go in the `ui/` subdirectory
```

Example `src/api/AGENTS.md`:

```markdown
# API Standards

- All endpoints must validate request parameters (using Zod schemas)
- Uniform error format: `{ code: number, message: string, details?: any }`
- Database operations must run inside transactions
- Sensitive operations must be audit-logged
- Pagination endpoints use cursor-based pagination
```

### Override Priority

When rules conflict across multiple `AGENTS.md` levels, **proximity wins**:

```
Global (~/.codex/AGENTS.md)
  | overridden by repo-level
Repo root (project/AGENTS.md)
  | overridden by subdirectory
Subdirectory (project/src/api/AGENTS.md) <- highest priority
```

In practice:

- Subdirectory `AGENTS.md` rules take precedence over parent levels
- Parent rules that aren't overridden remain in effect
- Multi-level rules are **additive**, not full replacements

---

## Practical Templates

Here are several battle-tested templates you can copy directly into your projects.

### Frontend React Project

```markdown
# AGENTS.md

## Project Info
React 19 + TypeScript + TailwindCSS frontend project.

## Code Standards
- Use function components + Hooks; class components are prohibited
- State management uses Zustand; do not introduce Redux
- Styling with TailwindCSS; no CSS files
- Use `@/` path alias to reference modules under src
- Define component Props as an interface named `{ComponentName}Props`

## File Naming
- Component files: PascalCase (`UserAvatar.tsx`)
- Hook files: camelCase + use prefix (`useAuth.ts`)
- Utility files: camelCase (`formatDate.ts`)
- Constant files: camelCase (`apiEndpoints.ts`)

## Component Rules
- Export both the Props type and the component itself
- Wrap pure presentational components with `React.memo`
- Name event handlers as `handle{EventName}`
- Avoid creating new objects or functions inside render

## Testing
- Framework: Vitest + React Testing Library
- Test files go in `__tests__/` directories
- Test user behavior, not implementation details
- Run command: `npm test`

## Dependency Management
- Before adding a new dependency, check if existing ones already cover the need
- Prefer lightweight libraries
- All dependencies must have TypeScript type definitions
```

### Backend Python/FastAPI Project

```markdown
# AGENTS.md

## Project Info
Python 3.12 + FastAPI + SQLAlchemy backend service.

## Code Standards
- Type annotations: all function parameters and return values must have type annotations
- Async first: all IO operations must use async/await
- Docstrings: all public functions use Google-style docstrings
- Import ordering: stdlib -> third-party -> local modules (managed by isort)

## Project Structure
- `app/api/` - API routes (organized by feature router)
- `app/models/` - SQLAlchemy data models
- `app/schemas/` - Pydantic request/response models
- `app/services/` - Business logic layer
- `app/core/` - Configuration, security, dependency injection
- `tests/` - Test files, mirroring the app directory structure
- `alembic/` - Database migrations

## Coding Conventions
- Route function naming: `get_users`, `create_order` (verb_noun)
- Service layer methods: correspond to route functions
- Data model fields use snake_case
- All database operations go through the Service layer; routes never touch the ORM directly
- Sensitive data (passwords, tokens) must never appear in logs or responses

## Error Handling
- Business exceptions use custom Exception classes
- Unified exception handler returns standard format: `{"code": int, "message": str}`
- Database operations are wrapped in try/except to catch IntegrityError, etc.
- Never use bare except

## Testing
- Framework: pytest + pytest-asyncio + httpx
- Use fixtures to manage test database and client
- Run command: `pytest -v --cov=app`
- Minimum coverage target: 80%

## Environment Management
- Use .env files for configuration, loaded via pydantic-settings
- Environment-specific differences are handled via environment variable overrides
- Never hardcode database connection strings, secrets, etc. in code
```

### Full-Stack Project

```markdown
# AGENTS.md

## Project Info
Full-stack web app: Next.js 15 frontend + API Routes + PostgreSQL.
Monorepo structure managed with Turborepo.

## Directory Structure
- `apps/web/` - Next.js frontend
- `apps/api/` - Standalone API service (Node.js + Fastify)
- `packages/ui/` - Shared UI component library
- `packages/types/` - Shared TypeScript types
- `packages/utils/` - Shared utility functions
- `packages/db/` - Database schema (Drizzle ORM)

## General Standards
- Language: TypeScript strict mode
- Formatting: Prettier (configured at root)
- Lint: ESLint (configured at root)
- Before committing, run: `turbo lint test`

## Frontend Standards (apps/web/)
- Use App Router, not Pages Router
- Server Components first; Client Components only when necessary
- Data fetching via Server Actions or Route Handlers
- Styling with TailwindCSS
- Images use the next/image component

## API Standards (apps/api/)
- RESTful design, URLs use kebab-case
- Request validation with Zod
- Response format: `{ success: boolean, data?: T, error?: string }`
- Authentication via JWT, validated in middleware
- Rate limiting rules go in route decorators

## Database Standards (packages/db/)
- Use Drizzle ORM; schema defined in the `schema/` directory
- Migration command: `pnpm db:migrate`
- Naming: table names are plural (`users`), fields use snake_case
- All tables must have `created_at` and `updated_at`
- Soft deletes use a `deleted_at` field

## Shared Package Standards
- Packages reference each other via workspace
- Shared type definitions go in `packages/types/`
- Packages must not import from apps
```

---

## Advanced Tips

### Coexisting with CLAUDE.md

If your project uses both Codex and Claude Code, you can maintain both configuration files side by side:

```
your-project/
  AGENTS.md          <- read by Codex
  CLAUDE.md          <- read by Claude Code
  src/
  ...
```

**Core standards can be shared**. Most of the content in both files (tech stack, naming conventions, directory structure, etc.) will be identical -- only tool-specific directives differ.

Recommended approach:

1. Write a single set of core standards
2. Copy into both `AGENTS.md` and `CLAUDE.md`
3. Fine-tune formatting for each tool's conventions

Or a more elegant approach -- cross-reference at the top of each file:

```markdown
# AGENTS.md

> This project uses both Codex and Claude Code. Core standards are below.
> Claude Code users, refer to CLAUDE.md.

## Core Standards
(shared content)
```

### Team Collaboration Best Practices

#### Commit to Version Control

`AGENTS.md` should be committed to your Git repository so team members share the same AI coding standards:

```bash
git add AGENTS.md
git commit -m "feat: add AGENTS.md for Codex configuration"
```

#### Include AGENTS.md in Code Reviews

Changes to `AGENTS.md` should go through code review just like changes to coding standards:

```markdown
<!-- PR description -->
## Change Summary
Updates to AGENTS.md:
- Added API pagination standard (cursor-based)
- Explicitly prohibited direct fetch calls in components
- Added logging format requirements
```

#### Iterate Gradually

You don't need to write everything at once. Recommended approach:

1. **Day one**: Write basic tech stack and naming conventions (10-20 lines)
2. **First week**: Add rules based on Codex's actual behavior
3. **Ongoing**: Whenever Codex does something you don't want, add a rule to `AGENTS.md`

### Effective Instruction Patterns

These types of instructions work best in `AGENTS.md`:

```markdown
## High-Effectiveness Instructions (Codex follows these reliably)

- Explicit format requirements: Use PascalCase for component file names
- Explicit prohibitions: Do not use the any type
- Run commands: Run npm test after completing the task
- File location rules: Test files go in __tests__ directories
- Dependency constraints: Do not introduce new npm packages; use existing dependencies
```

```markdown
## Low-Effectiveness Instructions (best avoided)

- Too vague: Write good code
- Subjective: Use best practices
- Out of scope: Consider user experience (AI can't run a UI)
- Contradictory: Prioritize performance + prioritize readability (need explicit priority)
```

### Conditional Rules

You can set different rules for different file types or directories:

```markdown
## File Type Rules

### *.test.ts files
- No more than 10 tests per describe block
- Use factory functions to create test data; no hardcoding
- Async tests must have timeout settings

### *.api.ts files
- Must validate request parameters
- Must include error handling
- Return values must have type annotations

### migrations/*.sql files
- Do not modify directly; use the ORM migration tool to generate
```

---

## Migrating from CLAUDE.md

If you already have a `CLAUDE.md`, converting it to `AGENTS.md` is straightforward. Both are Markdown format, and core content transfers directly.

### Migration Steps

**Step 1: Copy the base content**

```bash
cp CLAUDE.md AGENTS.md
```

**Step 2: Replace Claude Code-specific references**

Swap Claude Code-specific concepts for their Codex equivalents:

| In CLAUDE.md | In AGENTS.md |
|--------------|--------------|
| "When Claude modifies files..." | "When modifying files..." |
| "Use `/compact` to compress context" | (Remove -- Codex doesn't have this command) |
| "Reference files via `@`" | (Remove -- Codex uses a different reference method) |
| "Hook: PostToolUse..." | "After completing the task, run..." |
| "Sub-agent handles..." | "Use Cloud Exec..." |

**Step 3: Streamline the format**

Codex prefers concise list-style directives. If your `CLAUDE.md` has lengthy explanatory paragraphs, condense them into bullet points:

Before migration (`CLAUDE.md` style):

```markdown
## Code Style

In this project, we follow the Google TypeScript style guide. All variable
names use camelCase, class names use PascalCase. Note that enum values use
SCREAMING_SNAKE_CASE. Import statements should be ordered as follows: first
Node.js built-in modules, then third-party packages, and finally local
modules. Separate each group with a blank line.
```

After migration (`AGENTS.md` style):

```markdown
## Code Style
- Follow the Google TypeScript style guide
- Variables: camelCase
- Classes: PascalCase
- Enum values: SCREAMING_SNAKE_CASE
- Import order: built-in modules -> third-party packages -> local modules (blank line between groups)
```

**Step 4: Add Codex-specific directives**

```markdown
## Codex-Specific Configuration
- After all file modifications, run `npm run lint && npm test` to verify
- If tests fail, automatically fix and re-run
- Do not modify .env and .env.local files
```

### Migration Reference Table

| Concept | CLAUDE.md Style | AGENTS.md Style |
|---------|-----------------|-----------------|
| Project description | Free-form paragraphs | Brief list or paragraph |
| Code standards | Markdown lists | Markdown lists (same) |
| Prohibited actions | "Don't do X" | "Never do X" or "Don't do X" |
| Run commands | "Please run `npm test`" | "Run `npm test`" or just list it |
| File structure | Code block with directory tree | Code block with directory tree (same) |
| Tool configuration | settings.json references | config.toml references |

### Maintaining Both Files

If you need to maintain both `AGENTS.md` and `CLAUDE.md` long-term:

1. **Designate one as the "primary"**: Usually the file for the tool you use more often
2. **Sync after editing the primary**: You can write a simple script to automate this
3. **Keep tool-specific rules separate**: Put shared standards in the first half, tool-specific rules at the end

---

## Debugging & Validation

### Confirming AGENTS.md Is Active

The simplest way to verify is to give Codex a task that should trigger a rule:

```bash
# Assuming AGENTS.md requires TypeScript
codex "Create a hello world function"

# If AGENTS.md is active, Codex will generate a .ts file instead of .js
```

### Troubleshooting Rules Not Taking Effect

1. **File location**: Confirm `AGENTS.md` is in the project root or the relevant subdirectory
2. **File name**: Must be `AGENTS.md` (uppercase, not `agents.md`)
3. **Format issues**: Ensure proper Markdown formatting (blank line before lists, etc.)
4. **Rule conflicts**: Check for contradictory directives across multiple `AGENTS.md` levels
5. **Too vague**: Try replacing with a more specific description

---

## Choosing Between CLAUDE.md and AGENTS.md

Maintaining both configuration files sounds natural, but **two copies tend to diverge**: you add a rule to `AGENTS.md` and forget to mirror it in `CLAUDE.md`, and the two tools start behaving inconsistently. The guidance below helps you avoid that trap.

### Start with how many tools you use

- **Claude Code only (single tool)**: A `CLAUDE.md` is all you need. Claude Code reads `CLAUDE.md` natively and layers on global memory plus path-scoped rules (nested `CLAUDE.md` / `.claude/rules`). There's no need to also maintain `AGENTS.md`.
- **Multi-tool team (Claude Code + Codex / Cursor / Copilot / Cline / Gemini / Aider / Zed, etc.)**: Make `AGENTS.md` the **single source of truth**. Most tools other than Claude Code read `AGENTS.md`, while Claude Code by default reads only `CLAUDE.md`.

### Recommended for multi-tool teams: a thin CLAUDE.md that imports AGENTS.md

Don't maintain two full copies that drift apart. Keep the shared standards in `AGENTS.md`, then pull them in with a **thin `CLAUDE.md`** so Claude Code gets both the team-shared rules and its Claude-only extras:

```markdown
# CLAUDE.md

@AGENTS.md

## Claude Code-only extras
- Use `/model` to switch between Sonnet 4.6 / Opus 4.8 per task
- Run `/plan` before large changes
- Use `/clear` between unrelated tasks; `/compact` at logical breakpoints in long sessions
```

This way the shared standards have a single source (`AGENTS.md`), and `CLAUDE.md` holds only Claude Code-specific directives -- eliminating divergent duplicates at the root.

### Quick decision table

| Scenario | What to maintain | Notes |
|----------|------------------|-------|
| Claude Code only | `CLAUDE.md` only | Read natively; no `AGENTS.md` needed |
| Codex / other tools only | `AGENTS.md` only | These tools don't read `CLAUDE.md` |
| Multi-tool team | `AGENTS.md` (source of truth) + thin `CLAUDE.md` (`@AGENTS.md`) | Single source, no divergence |

> For `CLAUDE.md` layering, templates, and context control, see the [CLAUDE.md Configuration Guide](/docs/usage/claude-md).

---

## Next Steps

- [Codex Quick Start](/docs/getting-started/codex-quick-start) -- Install and configure Codex
- [Codex vs Claude Code: An In-Depth Comparison](/docs/getting-started/codex-vs-claude-code) -- Full comparison of both tools
- [Hooks System](/docs/advanced/hooks) -- Claude Code's event hooks (similar concept)
- [CLI Tips & Tricks](/docs/usage/cli-tips) -- Practical tips for more productive AI-powered coding