AGENTS.md Setup

You asked Codex to add a feature and it used Express when your project runs on Fastify. You told it to run tests and it tried npm test when your project uses pnpm vitest. Codex is powerful, but without context about your specific project, it falls back to generic assumptions that waste your time undoing wrong choices.

AGENTS.md solves this. It is a markdown file that Codex reads before doing any work — your project’s instruction manual for the AI agent. Think of it as the equivalent of onboarding a new developer: here is how we structure code, here is how we test, here is what never to touch.

What You’ll Walk Away With

• A global ~/.codex/AGENTS.md with your personal working agreements
• A project-level AGENTS.md with repository-specific conventions
• Nested overrides for specific directories (monorepo support)
• Codex correctly following your conventions on the first try
• Review guidelines that Codex uses when reviewing PRs on GitHub

How Discovery Works

Codex builds an instruction chain at startup by walking the filesystem in a specific order:

1. Global scope: Codex reads ~/.codex/AGENTS.override.md if it exists. Otherwise, it reads ~/.codex/AGENTS.md. Only one file is used at this level.

2. Project scope: Starting at the project root (typically the Git root), Codex walks down to your current working directory. In each directory, it checks for AGENTS.override.md, then AGENTS.md, then any fallback filenames you configured. At most one file per directory is included.

3. Merge: Files are concatenated from root down, with blank lines between them. Files closer to your working directory appear later in the prompt, so they effectively override earlier guidance.

Codex skips empty files and stops adding files once the combined size reaches project_doc_max_bytes (32 KiB by default).

Create Global Guidance

Your global AGENTS.md applies to every repository you open with Codex. Use it for personal working agreements and tool preferences.

mkdir -p ~/.codex

Create ~/.codex/AGENTS.md:

# Global Working Agreements

## Development preferences
- Prefer pnpm over npm for package management.
- Always run tests after modifying source files.
- Ask for confirmation before adding new production dependencies.
- Use TypeScript strict mode in all new files.

## Git conventions
- Write conventional commit messages (feat:, fix:, chore:, etc.).
- Never force-push to main or master.
- Create feature branches for all changes.

## Code style
- Use single quotes for strings in JavaScript/TypeScript.
- Prefer async/await over raw promises.
- Add JSDoc comments to exported functions.

Tip

Prompt to verify global AGENTS.md is loaded:

Run this from any project directory:

codex "Summarize the current instructions you loaded"

Codex should quote items from your global AGENTS.md. If it does not mention them, check that the file is at ~/.codex/AGENTS.md and is not empty.

Create Project-Level Instructions

Repository-level files teach Codex your project’s specific norms while inheriting your global defaults.

Create AGENTS.md at your repository root:

# Project: E-Commerce API

## Architecture
- This is a Node.js API using Fastify (NOT Express).
- Database: PostgreSQL with Drizzle ORM.
- Auth: JWT tokens with 24-hour expiry, refresh tokens in HTTP-only cookies.
- All routes are in src/routes/ with one file per resource.

## Commands
- `pnpm dev` -- Start the development server.
- `pnpm test` -- Run Vitest test suite.
- `pnpm lint` -- Run ESLint and Prettier checks.
- `pnpm db:migrate` -- Run database migrations.
- `pnpm db:seed` -- Seed test data.

## Code conventions
- All new endpoints must have corresponding test files in tests/.
- Use Zod schemas for request validation (not manual checks).
- Error responses follow the RFC 7807 Problem Details format.
- Never use console.log in production code -- use the pino logger.

## Review guidelines
- Flag any API endpoint missing authentication middleware.
- Flag any database query that does not use parameterized inputs.
- Verify that new dependencies have more than 1000 weekly npm downloads.

Note

The “Review guidelines” section is special: when Codex reviews pull requests on GitHub (via @codex review), it applies these guidelines to flag issues. Place more specific instructions deeper in the directory tree when particular packages need extra scrutiny.

Nested Overrides for Monorepos

In a monorepo, different packages often have different conventions. Use AGENTS.override.md in nested directories to replace broader rules for specific contexts.

myproject/
  AGENTS.md                        # Project-wide conventions
  packages/
    api/
      AGENTS.override.md           # API-specific rules (overrides project AGENTS.md for this dir)
    frontend/
      AGENTS.md                    # Frontend-specific additions
    shared/
      AGENTS.md                    # Shared library conventions

Example packages/api/AGENTS.override.md:

# API Service Overrides

## Testing
- Use `make test-api` instead of `pnpm test`.
- Integration tests require a running PostgreSQL container.
- Run `docker-compose up -d db` before running tests.

## Security
- Never rotate API keys without notifying the #security Slack channel.
- All new endpoints must be added to the OpenAPI spec before implementation.

When Codex starts from packages/api/, it loads: global AGENTS.md, then project root AGENTS.md, then packages/api/AGENTS.override.md. The override file replaces (not merges with) any AGENTS.md in the same directory.

Tip

Prompt to verify nested overrides work:

codex --cd packages/api "Show which instruction files are active"

Codex should report three files: the global file, the project root, and the API override — in that order.

Custom Fallback Filenames

If your team already uses a different filename (like TEAM_GUIDE.md or CONTRIBUTING.md), tell Codex to recognize it:

~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md", "CONTRIBUTING.md"]
project_doc_max_bytes = 65536

Codex checks each directory in this order: AGENTS.override.md, AGENTS.md, then each fallback filename in the order you listed them. Only the first match per directory is used.

Real-World AGENTS.md Patterns

For a Next.js App

# Next.js E-Commerce Frontend

## Stack
- Next.js 15 with App Router (NOT Pages Router).
- React Server Components by default. Use "use client" only when hooks are needed.
- Tailwind CSS with the project's design tokens in tailwind.config.ts.
- Zustand for client state. No Redux.

## Conventions
- Pages go in app/(routes)/ following the route group pattern.
- Shared components in components/ with .tsx extension.
- API routes in app/api/ -- each route in its own directory with route.ts.
- Use next/image for all images, never raw <img> tags.

## Testing
- `pnpm test` runs Vitest for unit tests.
- `pnpm test:e2e` runs Playwright for E2E tests.
- Every new page must have at least one Playwright test.

For a Python FastAPI Service

# FastAPI Authentication Service

## Stack
- Python 3.12 with FastAPI and Pydantic v2.
- SQLAlchemy 2.0 with async sessions.
- Alembic for migrations.
- Poetry for dependency management.

## Commands
- `poetry run pytest` -- Run test suite.
- `poetry run ruff check .` -- Lint.
- `poetry run mypy .` -- Type check.
- `alembic upgrade head` -- Run migrations.

## Conventions
- All endpoints return Pydantic models, never raw dicts.
- Use dependency injection for database sessions.
- Async everywhere -- no sync database calls.
- Type hints required on all function signatures.

When This Breaks

Nothing loads: Verify you are in the intended repository and that codex reports the workspace root you expect. Ensure instruction files contain content — Codex ignores empty files.

Wrong guidance appears: Look for an AGENTS.override.md higher in the directory tree. Rename or remove the override to fall back to the regular file.

Instructions truncated: Raise project_doc_max_bytes in your config or split large files across nested directories.

Profile confusion: Run echo $CODEX_HOME before launching Codex. A non-default value points Codex at a different home directory than the one you edited.

Codex ignores your AGENTS.md advice: The file may be loaded but the instructions may be too vague. Use imperative statements (“Always run tests after editing” not “Tests are nice to have”). Check the combined file size has not exceeded the byte limit.

Tip

Prompt to audit which instruction files Codex loaded:

codex "List the instruction sources you loaded, in order, with their file paths"

This confirms the exact files and their precedence. If a file is missing, it was either empty, not found, or exceeded the byte limit.

What’s Next

Set Up MCP Servers Connect Codex to third-party tools and documentation via Model Context Protocol