Codex CLI e AGENTS.md: istruzioni persistenti per l'agente, dal globale al progetto

🧭 Cos'è AGENTS.md e perché Codex lo legge prima di lavorare

AGENTS.md è un semplice file Markdown che racconta all'agente come lavorare sul progetto: comandi di setup, come girano i test, convenzioni di stile, regole per le pull request, note di sicurezza. L'idea è tenerlo separato dal README.md: quest'ultimo parla agli umani, AGENTS.md parla agli agenti e raccoglie il contesto operativo che nel README sarebbe solo rumore.

La differenza pratica è che Codex lo legge prima di fare qualsiasi cosa: all'avvio costruisce una catena di istruzioni — una volta per esecuzione, e nella TUI una volta per sessione — e la mette davanti a ogni task. Non devo ricordarmi di allegarlo o citarlo: se il file c'è, entra nel contesto da solo.

Un dettaglio che apprezzo è che non è un formato chiuso: AGENTS.md è uno standard aperto, oggi gestito dalla Agentic AI Foundation, e lo stesso file funziona con molti agenti oltre a Codex. Scrivo le regole una volta e le riuso, senza legarmi a un singolo strumento.

# AGENTS.md

## Setup
- Installa le dipendenze: pnpm install
- Avvia i test: pnpm test

## Stile del codice
- TypeScript strict, single quote, niente semicolon

## Pull request
- Esegui pnpm lint e pnpm test prima del commit

🪜 La catena di discovery: dal globale al progetto

Il cuore di AGENTS.md è come Codex lo scopre. Parte dallo scope globale: nella home di Codex (di default ~/.codex, oppure quella indicata da CODEX_HOME) legge AGENTS.override.md se esiste, altrimenti AGENTS.md. A questo livello usa solo il primo file non vuoto.

Poi passa allo scope di progetto: dalla radice del repo (di solito la root Git) scende fino alla cartella in cui mi trovo. In ogni cartella lungo il percorso controlla, nell'ordine, AGENTS.override.md, poi AGENTS.md, poi eventuali nomi di fallback — ma include al massimo un file per cartella.

Infine li combina: concatena dalla radice verso il basso, separando i file con righe vuote. Conta la posizione, perché quelli più vicini alla mia cartella finiscono più in fondo nel prompt e quindi sovrascrivono le indicazioni più generali. È così che una regola del sottoprogetto batte quella globale senza che io debba cancellare nulla.

🛡️ AGENTS.override.md, fallback e i limiti da conoscere

AGENTS.override.md è la valvola di sfogo: quando in una cartella esiste, ha la precedenza assoluta sull'AGENTS.md dello stesso livello. Lo uso quando non voglio aggiungere regole ma sostituirle del tutto — per esempio in services/payments/, dove il team ha comandi di test diversi e vincoli di sicurezza propri.

Se un repo usa già un altro nome (tipo TEAM_GUIDE.md) non devo rinominare tutto: nel config.toml aggiungo project_doc_fallback_filenames e Codex li tratta come file di istruzioni. Con lo stesso file regolo project_doc_max_bytes, il tetto della dimensione combinata: di default sono 32 KiB, oltre i quali Codex smette di aggiungere contenuto.

Due cose che tengo a mente per non perdere tempo. I file vuoti vengono ignorati, quindi un AGENTS.md lasciato a metà semplicemente non fa nulla. E non c'è cache: Codex ricostruisce la catena a ogni esecuzione, così se ho appena modificato le istruzioni mi basta rilanciarlo nella cartella giusta perché le rilegga.

⚙️ config.toml: la configurazione di Codex, non le sue istruzioni

C'è un file che si confonde spesso con AGENTS.md ma fa un altro mestiere: config.toml, nella home di Codex (~/.codex). È scritto in TOML e non contiene istruzioni per l'agente, ma la sua configurazione: quale modello usare, la policy di approvazione, il sandboxing e — utile qui — le manopole della discovery viste sopra, project_doc_fallback_filenames e project_doc_max_bytes. In una riga: config.toml dice come gira Codex, AGENTS.md dice cosa deve sapere sul progetto.

Il parallelo con Claude Code aiuta a fissare la differenza. Anche lì la coppia è la stessa, con formati diversi: la configurazione sta in settings.json (versionato e condiviso col team) e in settings.local.json (personale, fuori dal versionamento), mentre le istruzioni discorsive vivono in CLAUDE.md — l'equivalente di AGENTS.md. Cambia la sintassi, TOML contro JSON, non il concetto: un file per la macchina, uno per l'agente.

# ~/.codex/config.toml — estratto
# come Codex tratta i file di istruzioni
project_doc_fallback_filenames = ['TEAM_GUIDE.md']
project_doc_max_bytes = 32768

🔗 Un solo file di regole per Codex, Claude Code e gli altri

Se lavoro con più agenti — Codex con AGENTS.md, Claude Code con CLAUDE.md, Gemini CLI con GEMINI.md, Copilot con .github/copilot-instructions.md — non ricopio le stesse regole in ogni file: le tengo in uno solo e faccio importare quello dagli altri. Così ho un'unica fonte di verità e le versioni non divergono quando aggiorno una convenzione.

In pratica Claude Code e Gemini CLI supportano un import con la sintassi @: lascio le regole in AGENTS.md e in CLAUDE.md scrivo solo la riga che lo include. La direzione è una scelta mia — conta avere un file sorgente e gli altri che puntano lì, invece di quattro copie da tenere allineate a mano.

# CLAUDE.md
@AGENTS.md

# GEMINI.md
@./AGENTS.md

⚖️ AGENTS.md o istruzioni nel prompt: come decido

La domanda pratica è una: questa regola vale sempre, o solo per il task di adesso? Se vale sempre — convenzioni, comandi, paletti di sicurezza — la scrivo in AGENTS.md, al livello giusto. Se è specifica di quel momento la dico nella chat: il prompt esplicito ha la precedenza su qualsiasi AGENTS.md, ed è normale che sia così.

Sul dove metterla, ragiono per raggio d'azione. Le preferenze che valgono ovunque (il gestore di pacchetti, il tono delle risposte) stanno nel file globale in ~/.codex; le regole del repo stanno nell'AGENTS.md di radice; le eccezioni di un modulo stanno in un override vicino al codice. Più la regola è specifica, più la tengo vicina ai file a cui si riferisce.

✅ Il flusso che seguo per scrivere un AGENTS.md utile

Non punto al file perfetto al primo colpo: parto dall'essenziale e lo tratto come documentazione viva, che aggiorno quando cambia qualcosa. L'obiettivo è che un agente — esattamente come un collega appena arrivato — capisca come lavorare senza doverlo chiedere a me.

Il mini-playbook che applico, in ordine:

• Comincio dalla radice con un AGENTS.md che copre setup, comandi di test e lint, stile e regole per le PR.
• Elenco i comandi che voglio far girare: se li scrivo, l'agente li esegue e prova a sistemare gli errori prima di chiudere il task.
• Uso file annidati nei monorepo: un AGENTS.md per pacchetto, così ogni sottoprogetto ha le sue regole e vince il più vicino.
• Sostituisco con un override solo quando devo rimpiazzare del tutto le regole di un livello, non per piccole aggiunte.
• Verifico cosa ha caricato lanciando Codex con un prompt tipo "riassumi le istruzioni attive": mi conferma i file letti e in che ordine.

Altri articoli del blog