Codex e AGENTS.md: leggere i file usati da Codex

Codex legge le istruzioni da file Markdown chiamati AGENTS.md. Quando glielo chiedi, può anche scrivere pianificazioni, specifiche e appunti come file .md nel tuo progetto. Questa pagina spiega dove Codex cerca AGENTS.md e come leggere comodamente tutti questi file.

Dove Codex cerca AGENTS.md

All'avvio, Codex costruisce un'unica catena di istruzioni: un file globale, poi i file del progetto lungo il percorso fino alla tua cartella di lavoro.

1. Il tuo file globale. Nella cartella home di Codex, ~/.codex (o la cartella impostata da CODEX_HOME). Codex usa AGENTS.override.md se esiste, altrimenti AGENTS.md. Qui viene usato un solo file.

2. Il tuo progetto. Codex parte dalla radice del progetto (per impostazione predefinita la radice Git; project_root_markers può cambiarla) e scende fino alla cartella in cui stai lavorando. In ogni cartella prende al massimo un file, controllando in quest'ordine:

  1. AGENTS.override.md
  2. AGENTS.md
  3. Qualsiasi nome che hai elencato in project_doc_fallback_filenames

Se non c'è una radice del progetto, Codex controlla solo la cartella corrente.

Come si combinano i file

Codex unisce i file dalla radice in giù, con righe vuote tra l'uno e l'altro. Un file più vicino alla tua cartella di lavoro viene dopo, quindi le sue istruzioni prevalgono su quelle precedenti. I file vuoti vengono saltati.

C'è un limite di dimensione: Codex smette di aggiungere file quando la loro dimensione combinata raggiunge project_doc_max_bytes, 32 KiB (32 768 byte) per impostazione predefinita. Se le tue istruzioni sono lunghe, alza il limite o dividile in file AGENTS.md nelle sottocartelle.

Entrambe le impostazioni si trovano in config.toml nella cartella home di Codex (per impostazione predefinita ~/.codex/config.toml):

project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536

Avvia una nuova esecuzione di Codex dopo averle cambiate.

Un semplice AGENTS.md

# AGENTS.md

## Commands
- Build: `npm run build`
- Test: `npm test`

## Rules
- Write plans to `docs/plans/<task>.md` before changing code.
- Keep each change small; explain it in the pull request.

Codex non salva le pianificazioni in file da solo. Per ottenere pianificazioni che puoi leggere più tardi, chiedigli di scriverne una in un file, in AGENTS.md (come la seconda regola) o nel tuo prompt.

Leggere ciò che scrive Codex

Con pochi file, va bene qualsiasi editor. Con molti (una pianificazione per attività, appunti, report), aiuta leggerli come pagine e vedere cosa è cambiato.

Su Mac, PilcrowMD (gratuita, beta):

PilcrowMD per Mac (beta) · Altro sulla lettura dei file degli agenti

Domande frequenti

AGENTS.md è solo per Codex? No. È una convenzione aperta che leggono diversi agenti di programmazione, non un formato esclusivo di Codex. Claude Code, per esempio, può leggere AGENTS.md quando un progetto non ha un CLAUDE.md (pagina su Claude Code).

Perché Codex ignora parte delle mie istruzioni? Controlla il limite di dimensione (32 KiB per impostazione predefinita) e se un AGENTS.override.md nella stessa cartella prende il posto del tuo AGENTS.md.

Posso leggere questi file sul telefono? Se la cartella del progetto si sincronizza con Google Drive, aggiungila in Le mie cartelle in PilcrowMD per Android. Apri una nota per vederne l'ultima versione; su Android non c'è il ricaricamento in tempo reale.

Anche su Mac: PilcrowMD per Mac (beta)