# Instruction files in Codex

Codex reads AGENTS.md files layered from your Codex home down to the working directory, with AGENTS.override.md to replace a file in place.

Source: https://ai-sw-factory.mellicci.dev/fundamentals/instruction-files/codex

## At a glance

| | Codex |
|---|---|
| Term | `AGENTS.md`; `AGENTS.override.md` replaces it in the same directory |
| Configured in | `~/.codex/AGENTS.md` (global), `<repo>/AGENTS.md` and nested `AGENTS.md` files (project); `config.toml` for discovery settings |
| Loads / runs | When Codex starts: once per run, once per launched session in the TUI |
| Scope & precedence | Global first, then project root down to the working directory; later (closer) files win; 32 KiB combined cap by default |

## Build the scenario

| Step | What you write or run | Where |
|---|---|---|
| 1 | Project file with commands, layout, conventions, boundary (`/init` scaffolds one) | `AGENTS.md` at the repo root |
| 2 | Database rules | `src/db/AGENTS.md` |
| 3 | Start Codex in `src/db/` so the chain includes the directory file | `codex --cd src/db` |
| 4 | Ask which files loaded | prompt in the session |

`AGENTS.md` at the repo root:

```markdown
# ticket-service
Fastify + TypeScript API on PostgreSQL (Drizzle). Package manager: pnpm.
## Commands
- `pnpm install`, `pnpm dev`, `pnpm test` (Vitest), `pnpm lint`
- `pnpm db:generate` (new migration), `pnpm db:migrate` (apply)
## Layout
- `src/routes/` HTTP handlers · `src/db/` schema and migrations
- `test/` Vitest specs · `docs/` API notes
## Conventions
- Named exports only; every route change needs a test in `test/`.
- Never hand-edit `src/db/migrations/`; generate them with `pnpm db:generate`.
```

`src/db/AGENTS.md`:

```markdown
# Database code

- Change `schema.ts`, then run `pnpm db:generate` to create the migration.
- Review the generated SQL before running `pnpm db:migrate`.
- Never edit files in `migrations/` by hand or rename them.
```

Check the chain:

```bash
codex --cd src/db --ask-for-approval never "List the instruction sources you loaded."
```

Expected, per the documentation: the global file first (if you have one), the root `AGENTS.md` second, `src/db/AGENTS.md` last.

## Specifics

### File names and locations

| File | Location | Note |
|---|---|---|
| `AGENTS.md` | `~/.codex/` (or `$CODEX_HOME`) | Global, your habits across repositories |
| `AGENTS.override.md` | `~/.codex/` | Temporary global override; at global scope only the first non-empty file is used |
| `AGENTS.md` | Project root and any directory down to the working directory | Project and directory scope |
| `AGENTS.override.md` | Any of those directories | Replaces that directory's `AGENTS.md` without deleting it |
| Names in `project_doc_fallback_filenames` | Project directories | Tried after `AGENTS.md`, e.g. `["TEAM_GUIDE.md", ".agents.md"]`; other names are ignored |

The project root is usually the Git root; `project_root_markers` in `config.toml` changes the markers. Without a root, Codex checks only the current directory. The `rules/*.rules` files in the Codex docs are command-execution policy, not instructions.

### How files load and combine

| Stage | What Codex does |
|---|---|
| 1. Global | Reads `AGENTS.override.md` in Codex home, else `AGENTS.md`; first non-empty file only |
| 2. Project | Walks from the root to the working directory; per directory checks `AGENTS.override.md`, `AGENTS.md`, then fallback names; at most one file each |
| 3. Combine | Concatenates root-down, joined by blank lines; nothing is merged key by key |

Closer files appear later in the prompt, so they override earlier guidance in practice. Empty files are skipped.

### Scoping to paths

Scope comes from where the file sits, not from a glob. Discovery stops at the directory you launch from. `src/db/AGENTS.md` is in the chain when you start in `src/db/` or below (`--cd src/db`), not when you start at the root. The documentation doesn't specify whether Codex loads it later when it edits files in `src/db/`.

### Size and context cost

| Setting (`config.toml`) | Effect |
|---|---|
| `project_doc_max_bytes` | Limit on project guidance; 32 KiB by default. The docs say combined size in one place and per file in another |
| `project_doc_fallback_filenames` | Extra file names to treat as instruction files |
| `project_root_markers` | File names that mark the project root |

Codex stops adding files at the limit, so later (closer) files are dropped first. Raise the limit or split guidance into nested directories. The guide advises keeping the main file short and pointing to task-specific markdown files.

### See what loaded

| Method | Shows |
|---|---|
| Prompt: "List the instruction sources you loaded." | The files the model received, in order |
| `codex -c log_dir=./.codex-log` | A plaintext `codex-tui.log` you can inspect |
| `/status` | Model, approval policy, writable roots, token usage; the docs don't say it lists instruction files |
| `echo $CODEX_HOME` | Whether you edited the home Codex actually uses |

Codex rebuilds the chain on every run and at each TUI session start, so there is no cache to clear; restart to pick up edits.

## Gotchas

- **Launch directory decides what loads.** Started at the repo root, the chain stops there and `src/db/AGENTS.md` is not in it. Start in the subdirectory or use `--cd`.
- **One file per directory.** If `src/db/` has both `AGENTS.override.md` and `AGENTS.md`, only the override is read. A forgotten override higher up, or in Codex home, explains "wrong guidance".
- **The cap drops the closest files.** Past 32 KiB, later files are cut, which are the most specific ones. Keep the root file short.
- **A boundary is a request.** "Never hand-edit `migrations/`" is advice the model reads. To enforce it, use a [hook](https://ai-sw-factory.mellicci.dev/fundamentals/hooks/codex) or the sandbox; see the [security model](https://ai-sw-factory.mellicci.dev/fundamentals/security-model).