AGENTS.md Guide

AGENTS.md files are how you teach Codex about your project. They work like a README for your AI agent — telling it how to navigate your codebase, which commands to run, and how to follow your team's conventions.

Why AGENTS.md Matters#

Without AGENTS.md, Codex makes assumptions about your project. With it, Codex follows your exact conventions:

• Which test commands to run
• What linting rules to follow
• How to structure commits
• Which directories have special rules
• What to focus on during code review

## How Discovery Works

Codex builds an instruction chain when it starts (once per run):

1. Global Scope#

In your Codex home directory (~/.codex/):

1. First checks for AGENTS.override.md
2. Falls back to AGENTS.md
3. Uses only the first non-empty file found

2. Project Scope#

Starting at the project root (typically the Git root), Codex walks down to your current directory:

1. In each directory, checks AGENTS.override.md then AGENTS.md
2. Applies fallback filenames from project_doc_fallback_filenames config
3. Deeper files add to (or override) parent instructions

Global AGENTS.md#

Place at ~/.codex/AGENTS.md for defaults that apply to all your projects:

# Global Working Agreements

- Always run tests after modifying code
- Prefer pnpm when installing dependencies
- Ask for confirmation before adding new production dependencies
- Use conventional commit messages (feat:, fix:, chore:, etc.)
- Never commit .env files or API keys

Project-Level AGENTS.md#

Place at your repository root for project-specific conventions:

# Project: My App

## Setup
- Run `pnpm install` to install dependencies
- Run `pnpm dev` for development server
- Run `pnpm test` before opening a pull request

## Conventions
- Use TypeScript strict mode
- Components go in `src/components/`
- API routes go in `src/app/api/`
- Use Tailwind CSS for styling (no CSS modules)

## Review Guidelines
- Check for SQL injection in all database queries
- Verify authentication on all API endpoints
- Ensure new components have unit tests
- Flag hardcoded credentials as P0 issues

Directory-Level Overrides#

Add AGENTS.md files deeper in the tree for specific directories:

repo/
  AGENTS.md                         # General project rules
  services/
    payments/
      AGENTS.md                     # Payment-specific rules
    auth/
      AGENTS.override.md            # Auth overrides (takes priority)

Example: Payment Service Override#

# Payment Service Rules

- All financial calculations must use Decimal.js (never floating point)
- Log all payment state transitions
- Never log credit card numbers or CVVs
- All payment endpoints require rate limiting
- Run `pnpm test:payments` for payment-specific tests

Override Files#

AGENTS.override.md takes priority over AGENTS.md in the same directory. Use overrides for:

• Temporary rules — "During the migration, skip legacy tests"
• Personal preferences — Your own ~/.codex/AGENTS.override.md without changing the shared file
• Hotfixes — Quick rule changes that do not require team review

Remove the override file to restore the base instructions.

Testing Your Instructions#

Verify Codex reads your AGENTS.md correctly:

# Check what instructions are active
codex --ask-for-approval never "Summarize the current instructions."

# Check nested overrides
codex --cd services/payments --ask-for-approval never "Show active instructions."

Cross-Tool Compatibility#

AGENTS.md is an open standard supported by multiple tools:

| Tool | Support | |------|---------| | Codex | Full support (global + project + directory) | | Cursor | Reads AGENTS.md for context | | Aider | Reads AGENTS.md for conventions |

## Troubleshooting

• Empty files are ignored — Make sure your AGENTS.md has content
• Wrong guidance appearing — Check for an AGENTS.override.md higher in the tree
• Instructions truncated — Raise project_doc_max_bytes in config.toml or split across directories

Next Steps#

• Configuration Reference — Full config.toml settings
• Safety Modes — Approval and sandbox policies
• Code Review — How AGENTS.md affects reviews