Come scrivere AGENTS.md perché Codex capisca le regole del tuo progetto

Ogni volta che Codex modifica il codice e dice “fatto”, lanci pnpm test e scopri che i test non sono mai partiti. Oppure, nella radice di un monorepo, esegue i test del package sbagliato. Ripetere ogni volta queste istruzioni stanca: npm run build, pnpm test, non toccare generated, prima di chiudere esegui lint. AGENTS.md serve proprio a scrivere queste regole dentro il progetto, così la seconda volta Codex non deve chiedertele di nuovo.

Se hai appena completato la guida introduttiva a Codex e alla scelta dell’interfaccia, il passo successivo non è chiedergli di rifattorizzare tutto il progetto. Prima conviene fissare le istruzioni che ripeti a voce.

Partiamo da uno scheletro seme da 12-20 righe, poi vediamo il caricamento a tre livelli, come verificare che funzioni, cosa non va scritto, come convivere con CLAUDE.md o Cursor Rules e quando aggiornarlo.

AGENTS.md non è README: è il manuale di lavoro persistente di Codex

README.md è scritto per lettori umani: spiega cos’è il progetto, come installarlo e come iniziare. AGENTS.md è scritto per Codex e contiene le regole caricate a ogni avvio: come fare build, come testare, quali directory non toccare e cosa controllare prima di dire che il lavoro è finito.

Secondo la documentazione ufficiale OpenAI, Codex legge AGENTS.md prima di iniziare a lavorare e lo usa come parte del contesto. Non è come ripetere ogni volta in chat “npm run build” o “pnpm test”: AGENTS.md è una guida persistente del progetto.

C’è però un confine da chiarire: AGENTS.md non è un sistema di memoria a lungo termine e non è una knowledge base che impara da sola. È solo un file statico caricato a ogni avvio. Se vuoi accumulare conoscenza tra sessioni o gestire memoria di progetto, puoi leggere la guida precedente sulla memoria degli agenti IA, dove separo memoria a lungo termine e regole di progetto.

Come Codex trova il tuo AGENTS.md: caricamento a tre livelli

L’ordine di lettura di Codex si capisce in tre livelli: globale, progetto e merge. Capire questo meccanismo aiuta a capire dove una regola ha effetto e perché a volte sembra non funzionare.

Livello globale: le tue abitudini personali

Codex prima cerca file nella tua directory utente ~/.codex. Questo livello contiene abitudini personali, per esempio lingua di risposta, preferenze di stile o strumenti che usi spesso. Attenzione: il livello globale legge al massimo un file, nell’ordine AGENTS.override.md -> AGENTS.md, e non li somma.

Livello progetto: scansione dalla radice Git alla directory corrente

Il livello progetto scansiona dalla radice Git, o dalla radice del progetto, fino alla directory di lavoro corrente. Anche a ogni livello legge al massimo un file, nell’ordine AGENTS.override.md -> AGENTS.md -> fallback filenames. I nomi fallback si possono configurare con project_doc_fallback_filenames, per esempio aggiungendo TEAM_GUIDE.md; il nome esatto dell’opzione va trattato come parte della documentazione ufficiale.

Ordine di merge: più è vicino, più è specifico

Tutti i file trovati vengono concatenati dalla radice alla directory corrente. Più un file è vicino alla directory corrente, più tardi appare nel contesto; per Codex, la regola locale diventa più facile da privilegiare.

Vultr - Cloud server NVMe ad alte prestazioni, 32 location globali, deploy Docker con un clic

Vedi prezzi →Pubbl.

Esempio: nella radice di un monorepo c’è AGENTS.md con “il comando di test è pnpm test”; in apps/web/AGENTS.md c’è “il comando di test è pnpm --filter web test”. Se avvii Codex in apps/web, l’ordine letto è: regole di radice -> regole di apps/web. Il comando di apps/web è più specifico.

Riepilogo dei tre livelli

Consiglio: metti nella radice le regole condivise dal team e nelle sottodirectory i requisiti speciali, per esempio un package con un comando di test diverso. AGENTS.override.md è utile per override temporanei o locali; non trasformarlo nello standard del team, altrimenti le regole restano nascoste e collaborare diventa più fragile.

Template minimo: quali 6 blocchi scrivere per primi?

OpenAI consiglia di trattare AGENTS.md come un “open-format README for agents”. Il punto è scriverlo corto, reale e verificabile. Non copiare subito un template da 300 righe trovato online: parti da 6 blocchi base e aggiungi solo quando serve.

Lo scheletro seme contiene questi 6 blocchi:

1. repo layout: stack e struttura delle directory, così Codex sa dove stanno frontend, backend e test
2. Commands: comandi esatti di build, test e lint; scrivi pnpm test, non “esegui i test”
3. Constraints: directory o azioni da evitare, per esempio src/generated/
4. PR expectations: cosa controllare prima di aprire o chiudere una modifica
5. Done when: criteri verificabili di completamento, per esempio pnpm test e pnpm build
6. Eventuali convenzioni speciali, come package manager, stile di codice o naming

Per una dashboard SaaS, un seme può essere così:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Database: PostgreSQL
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review

## PR expectations
- Add tests for new features
- Run `pnpm test` before marking done

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Questo template è abbastanza corto da non sporcare il contesto. Parti da questi 6 blocchi e amplia quando emerge un problema ripetuto. Non infilare subito visione di prodotto, liste di dipendenze, diagrammi di architettura o indici delle API docs: un file enorme seppellisce le regole davvero importanti.

Come confermare che Codex abbia davvero letto AGENTS.md

Dopo aver scritto AGENTS.md, puoi usare un comando di verifica. Il comando consigliato dalla documentazione OpenAI è:

codex --ask-for-approval never "Summarize the current instructions."

Questo comando fa riassumere a Codex le istruzioni caricate. Se l’output contiene le tue regole, per esempio il comando di test o la directory da non toccare, allora sta funzionando. Se non compare nulla, o compaiono regole diverse, devi fare debug della catena di caricamento.

Checklist di diagnosi

Se dopo la diagnosi continua a non funzionare, consulta la documentazione OpenAI Custom instructions o aggiorna Codex. Non fidarti dell’idea che “funzioni per forza”: percorso, versione, configurazione e directory corrente contano.

Cosa non dovrebbe finire in AGENTS.md

AGENTS.md non è un magazzino universale. Alcune cose portano rischi di sicurezza, manutenzione o rumore nel contesto, quindi vanno tenute fuori.

1. Segreti, API key e password di produzione

Sono un rischio di sicurezza. Nessun segreto, password di produzione o API token dovrebbe stare in AGENTS.md. Codex legge il file nel contesto e il file può essere visto dal team o finire in Git. Usa variabili d’ambiente, file .env non committati o un sistema dedicato di secrets. Se ti serve che Codex usi secrets in una sandbox, quello è un problema di livello di esecuzione.

2. Liste grandi che invecchiano

Sono un rischio di manutenzione. Non scrivere liste di dipendenze, numeri di ecosistema, prezzi, quote o campi che cambiano spesso. Una lista tipo “React 18.2, Vue 3.4, TypeScript 5.0…” sarà vecchia in pochi mesi. Scrivi il processo per aggiungere una dipendenza, non l’inventario completo.

3. Slogan astratti

Non sono eseguibili. Frasi come “mantieni alta qualità”, “scrivi codice elegante” o “assicurati che il codice sia manutenibile” non danno a Codex un’azione concreta. Sostituiscile con criteri: pnpm test passa, pnpm lint non segnala errori, le nuove funzionalità hanno test, Lighthouse resta sopra la soglia concordata.

4. Comandi vaghi

Sono troppo imprecisi. “Esegui qualche test” o “controlla la build” non basta. Scrivi comandi esatti: pnpm test, pnpm build o lighthouse --preset=desktop.

🔥 Non sprecare mesi su prodotti senza domanda! Valida i punti di forza del tuo SaaS con Adsterra e un piccolo budget →

Testa ora →Pubbl.

5. Requisiti non verificabili

Non hanno una chiusura chiara. “Garantire prestazioni migliori” o “migliorare la UX” non definisce un criterio di accettazione. Usa controlli misurabili, per esempio una API sotto 200 ms o un obiettivo Lighthouse.

6. Preferenze personali nella radice del repo

“Rispondi in cinese”, “risposte sotto 100 parole” o “usa VSCode di default” sono preferenze personali, non regole condivise del progetto. Metterle in ~/.codex/AGENTS.md va bene; la radice del repo dovrebbe contenere standard del team.

Principio: corto, reale, verificabile. AGENTS.md serve a ridurre le spiegazioni ripetute, non a incollare tutta la documentazione del progetto.

Se hai già CLAUDE.md o Cursor Rules, serve AGENTS.md?

Se usi Claude Code o Cursor, nel repository potresti già avere CLAUDE.md o Cursor Rules. Non serve mantenere tre copie della stessa cosa: usa import o coesistenza.

AGENTS.md vs CLAUDE.md: strategia di import

Claude Code legge CLAUDE.md, non AGENTS.md. Se il repo ha già AGENTS.md, puoi creare un CLAUDE.md minimale che lo importa:

@AGENTS.md

## Claude-specific
- Prefer Chinese responses
- Keep responses concise (under 100 words unless requested)

@AGENTS.md è la sintassi di import. Claude Code legge prima AGENTS.md e poi la sezione Claude-specific. Così le regole di progetto restano in AGENTS.md, mentre le preferenze specifiche di Claude restano in CLAUDE.md.

AGENTS.md vs Cursor Rules: Cursor ha il suo sistema

Cursor ha un sistema di Rules proprio: Project, Team e User Rules. La documentazione ufficiale di Cursor e alcuni riassunti citano il supporto ad AGENTS.md, ma i dettagli di caricamento vanno verificati nella documentazione attuale di Cursor. Se usi sia Cursor sia Codex, metti le regole comuni in AGENTS.md e lascia configurazioni o workflow specifici di Cursor nelle Cursor Rules.

AGENTS.md vs config.toml, Rules, Skills e MCP

AGENTS.md è il livello di istruzioni: dice a Codex “come dovrebbe lavorare”. Il livello di esecuzione, cioè permessi, sandbox, policy dei comandi e integrazioni degli strumenti, vive altrove.

In sintesi: AGENTS.md risolve il problema delle regole ripetute del progetto; Rules, config, sandbox e permessi controllano l’esecuzione; Skills incapsula workflow riutilizzabili; MCP collega strumenti esterni. Tenere chiari questi confini evita confusione.

Quando aggiornare AGENTS.md

AGENTS.md non va modificato a ogni cambiamento del progetto. Aggiornalo per scenari ricorrenti, così non diventa un file da mantenere continuamente.

Trigger di aggiornamento

La documentazione OpenAI consiglia di aggiornarlo in questi casi:

1. Codex ripete lo stesso errore: per esempio modifica due volte la directory sbagliata, oppure lancia sempre i test del package sbagliato. Aggiungi una constraint concreta: “Do NOT edit src/generated/” oppure “usa pnpm --filter web test”.

2. La PR review ripete lo stesso commento: il team continua a chiedere “questa modifica richiede test”, “non modificare generated code”, “evita default export”. Metti quel pattern nelle PR expectations.

3. Codex deve leggere troppi documenti per trovare la risposta: se ogni volta deve scavare in più livelli per trovare il comando di test o il flusso di build, aggiungi repo layout o Commands e porta le informazioni essenziali più in alto.

Principio della directory più vicina

Metti la regola nel livello in cui nasce l’errore. Non modificare sempre la radice; in un monorepo package diversi hanno regole diverse e possono mantenere AGENTS.md locali.

Se Codex lancia il test sbagliato lavorando in apps/web, aggiungi la regola in apps/web/AGENTS.md. Una regola in radice rischia di applicarsi troppo ampiamente.

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

Differenza rispetto alla memoria a lungo termine

AGENTS.md è un file statico caricato all’avvio. Non è una memoria che apprende automaticamente. Codex non aggiorna AGENTS.md a partire dalle tue correzioni, a meno che tu non glielo chieda esplicitamente.

Se ti serve conoscenza tra sessioni o governance della memoria, la guida sulla memoria degli agenti IA è il riferimento successivo.

Percorso di crescita del template: dal seme alla versione estesa

Non partire con un template da 300 righe. Inizia con 12-20 righe e amplia solo quando compare un trigger concreto.

Versione seme: solo i 6 blocchi essenziali

La versione seme copre repo layout, comandi comuni, constraints, PR expectations e done/verify. Può essere così piccola:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint

## Constraints
- Do NOT edit src/generated/ (auto-generated code)

## PR expectations
- Add tests for new features

## Done when
- `pnpm test` passes
- `pnpm build` succeeds

Trigger di espansione: quando aggiungere un blocco?

Dopo qualche esecuzione, amplia solo per problemi concreti:

1. La prima volta che Codex modifica la directory sbagliata: se tocca migrations/ o generated/, aggiungi in Constraints “Do NOT commit migrations/ without team review” oppure “Do NOT edit any file in src/generated/”.

2. La prima nota ripetuta in PR review: se i reviewer chiedono spesso test o named exports, aggiungi “Add tests for new features” oppure “Use named exports, not default exports”.

3. Il primo errore con il package manager: se in un progetto pnpm arrivano comandi npm, aggiungi “Always use pnpm, not npm or yarn”.

4. La prima dimenticanza del lint: se Codex chiude senza lint, aggiungi “pnpm lint passes with no errors” sotto Done when.

Versione estesa: 30-50 righe

Una versione estesa può aggiungere constraints, PR expectations, regole sul package manager e requisiti di lint:

# AGENTS.md

## Repo layout
- Frontend: React + TypeScript + Vite (src/)
- Backend: Node.js + NestJS (server/)
- Package manager: pnpm

## Commands
- Install: pnpm install
- Dev: pnpm dev
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint
- Always use pnpm, not npm or yarn

## Constraints
- Do NOT edit src/generated/ (auto-generated code)
- Do NOT commit migrations/ without team review
- Do NOT modify .env files (use .env.example as template)

## PR expectations
- Add tests for new features
- Run `pnpm test` and `pnpm lint` before marking done
- Use named exports, not default exports
- Keep components under 200 lines; split if larger

## Done when
- `pnpm test` passes
- `pnpm build` succeeds
- `pnpm lint` passes with no errors
- New features have corresponding tests

Il principio è questo: crescere per trigger, non per anticipazione. AGENTS.md vale perché riduce istruzioni ripetute, non perché mostra tutta la documentazione del progetto.

Conclusione

AGENTS.md è una guida persistente del progetto, non un magazzino universale e non un sistema di memoria a lungo termine. Risolve il problema del “devo ripetere sempre le stesse regole” quando Codex inizia a lavorare.

Passi pratici:

1. Parti da un seme di 12-20 righe: repo layout, comandi, constraints, PR expectations e done/verify. Non iniziare con un template enorme.

2. Verifica che Codex lo abbia caricato: esegui codex --ask-for-approval never "Summarize the current instructions." e controlla che la risposta contenga le tue regole.

3. Amplia per trigger ripetuti: Codex ripete un errore, la PR review ripete una nota o Codex deve leggere troppi documenti per trovare l’informazione.

4. Tieni fuori ciò che è pericoloso o deperibile: niente segreti, inventari che invecchiano, slogan, comandi vaghi, obiettivi non verificabili o preferenze personali nella radice.

5. Usa import e coesistenza con CLAUDE.md o Cursor Rules: regole condivise in AGENTS.md, comportamenti specifici nei file di ciascuno strumento.

AGENTS.md dà a Codex un contesto di progetto stabile. I prossimi articoli della serie Codex possono spostare workflow ripetibili in Skills, trattare limiti di permessi e segreti, e rendere done/verify più affidabile con failure review e PR checks.