AGENTS.md: Configure Your Repo Instructions — Codex: AI-Assisted Development

Lesson updated November 3, 2026 based on the Custom instructions with AGENTS.md page: Codex only reads AGENTS.md files located between the project root and the current working directory (plus the global file at ~/.codex). A file in a subdirectory outside this path is not loaded, contrary to what the previous version implied. Source: AGENTS.md.

Mastering the Codex Configuration File

You discovered AGENTS.md in Lesson 3. Here, we dive into advanced patterns—the difference between a decorative file (three lines written at startup and forgotten) and one that actually drives the agent’s behavior on a live project.

The AGENTS.md Hierarchy

Codex reads these files hierarchically, from general to specific: first the global file in your Codex folder (~/.codex/AGENTS.md, or AGENTS.override.md if it exists), then, starting from the project root, the files in the directories traversed down to the current working directory. On a structured project, the tree looks like this:

mon-projet/
  AGENTS.md                    → Global rules (low priority)
  src/
    AGENTS.md                  → Rules for all source code
    api/
      AGENTS.md                → Rules specific to APIs
      routes/
        AGENTS.md              → Rules for routes
    components/
      AGENTS.md                → Rules for React components
  tests/
    AGENTS.md                  → Rules for tests

Rules accumulate: Codex concatenates files from the root down to the current directory, and those closest to that directory, read last, override general instructions. One point is easily misunderstood: only directories on the path between the root and the current directory are read. If your root file forbids any while tests/AGENTS.md allows looser assertions in mocks, that tolerance applies only when Codex is working from tests/ or one of its subdirectories; launched from the root, it does not read tests/AGENTS.md. For a rule that must apply everywhere, place it at the root, even if you have to name the exception there. GitHub code review works differently: Codex searches the entire repository for AGENTS.md files there and applies the review rules (## Code Review Rules) from the file closest to the code in question. Concatenation stops at 32 KiB by default (project_doc_max_bytes): a file that is too long gets truncated.

The Sections That Make the File

Context comes first, because it shapes every decision that follows. A SaaS application subject to the GDPR (General Data Protection Regulation) isn’t coded like an internal tool for five people:

## Context
SaaS invoice management application for French SMEs.
GDPR compliance mandatory. Data hosted in France (OVH).
Stack: Astro 6, React, Strict TypeScript, Prisma, PostgreSQL.
Authentication: Better Auth with server sessions.

Knowing it handles data subject to the GDPR, Codex will add the expected protections without you having to specify them in every request. Next come the conventions, which answer one question: what does correct code look like here?

## Conventions
- Strict TypeScript (no any, no implicit any)
- Functional React components only
- Naming: kebab-case files, PascalCase components, 
  camelCase variables
- Imports: @/ for path aliases
- Validation: Zod for all user inputs
- Errors: custom error classes in src/lib/errors.ts
- Logging: use src/lib/logger.ts (no console.log)

The commands section is the most often omitted, and its absence is costly: without these commands, Codex cannot verify its own work and returns code it has never executed or tested.

## Commands
- `npm run dev` — Development server (port 4321)
- `npm run build` — Production build
- `npm run test` — Vitest tests
- `npm run test:e2e` — Playwright tests
- `npm run lint` — ESLint + Prettier
- `npm run db:migrate` — Prisma migrations
- `npm run db:seed` — Database seed

Strict rules form the guardrail. Phrased as “NEVER” and “ALWAYS,” they prevent errors that cost an entire evening to fix: a deleted Prisma migration you’ll have to reconstruct from production, a committed secret that needs revoking, or an innerHTML slipped into a component that opens an XSS vulnerability.

## Strict Rules (NEVER break these)
- NEVER modify the Prisma schema without creating a migration
- NEVER store secrets in code (use .env)
- NEVER use innerHTML (XSS risk)
- NEVER delete an existing Prisma migration
- NEVER expose internal IDs in public URLs
- ALWAYS validate user inputs with Zod
- ALWAYS use Prisma transactions for multi-table operations

Finally, architecture describes the permitted flow between layers. Without it, Codex produces code that works but short-circuits your structure—a route that queries Prisma directly, for example, because it was the shortest path.

## Architecture
Layers:
1. Routes (src/pages/) → receive requests
2. Services (src/services/) → business logic
3. Repositories (src/repositories/) → data access

Rule: Routes MUST NOT access Prisma directly.
Everything goes through a service, which goes through a repository.

Added to this, project by project, are instructions specific to each technology used:

## React
- Prefer Server Components by default
- Client Components only when necessary (interactivity)
- No useEffect for data fetching (use Server Actions)
- Local state with useState, global state with Zustand

## Prisma
- Relations: always include required fields explicitly
- Pagination: use cursor-based, not offset-based
- Soft delete: use deletedAt instead of DELETE

Two Patterns That Prevent Surprises

Declaring expected environment variables prevents Codex from inventing key names when writing a script, or accidentally logging a sensitive value in a debug trace:

## Required Environment Variables
- DATABASE_URL — PostgreSQL connection URL
- AUTH_SECRET — Secret for Better Auth (min 32 chars)
- SMTP_HOST — SMTP server for emails
- STRIPE_SECRET_KEY — Stripe API key (never log)

Naming your preferred libraries, and especially those you refuse, solves a recurring annoyance: the agent installs a dependency that is perfectly valid in itself, but that your team rejected two years ago after a bad experience.

## Dependencies
If you need:
- Validation → Zod (NOT Joi, NOT Yup)
- Dates → date-fns (NOT moment, NOT dayjs)
- HTTP client → ofetch (NOT axios)
- Tests → Vitest (NOT Jest)
- E2E → Playwright (NOT Cypress)

Keeping the File Alive

AGENTS.md evolves with your code, just like a test or a README. Update it as soon as you adopt a new convention, switch libraries or frameworks, and especially as soon as you identify a recurring Codex error: that last case always signals a missing instruction rather than a model failure. A fourth, more subtle trigger is worth watching for—when a new developer asks a question that AGENTS.md should have answered, that answer belongs in the file.

Key Takeaways

The hierarchy of AGENTS.md allows for increasingly specific instructions
Commands are critical for Codex to verify its work
NEVER rules are the most important for avoiding errors
Document preferred dependencies to prevent bad choices
Maintain AGENTS.md as living code