AGENTS.md: istruzioni di progetto utili per un agente AI
Neaptide · 6 settembre 2026 · 7 min di lettura
Cosa scrivere in AGENTS.md, dove lo cerca Codex e come verificare le regole applicate. Con esempio breve, file da adattare e schema.
In questo articolo
Se l’agente modifica sempre la cartella sbagliata o propone un comando inesistente, conviene salvare la regola. AGENTS.md è un file Markdown con gli accordi di lavoro del progetto. Serve soprattutto per il contesto che non si ricava facilmente dal codice.
Distribuire le informazioni
| Posizione | Contenuto |
|---|---|
| README | Installazione e orientamento per le persone |
| AGENTS.md | Accordi di lavoro permanenti |
| Skill | Procedura riutilizzabile di ricerca o revisione |
| Messaggio della richiesta | Compito attuale ed eventuali eccezioni |
Preferisci istruzioni verificabili a «scrivi buon codice»: indica dove modificare i contenuti e quale controllo eseguire. Rimanda alla documentazione esistente senza duplicarla.
Un esempio per un sito editoriale
Questi percorsi e il comando di build esistono nel nostro sito. Verificali prima di adattarli a un altro progetto. Il download è un .txt: salva la versione adattata come AGENTS.md nella cartella scelta.
# Lavorare in questo progetto
- Leggere package.json e i file vicini prima di modificare.
- Gli articoli sono in content/blog/articles, non nei dizionari dell’interfaccia.
- Conservare lo slug pubblicato salvo richiesta di cambiare URL.
- Eseguire npm run build dopo modifiche ai contenuti.
- Per nuova logica, eseguire i controlli pertinenti in scripts.
- Riportare i controlli eseguiti e i limiti rimasti.Non aggiungere npm test per abitudine se quel comando non è definito. Una correzione alla didascalia non deve imporre automaticamente un audit completo.
Come Codex trova le istruzioni
All’avvio, Codex legge le istruzioni globali, poi i file presenti lungo il percorso dalla radice del progetto alla cartella di lavoro corrente. In ogni cartella cerca prima AGENTS.override.md e poi AGENTS.md, selezionando al massimo uno dei due. Le istruzioni più vicine alla cartella di lavoro precisano quelle precedenti. Altri agenti possono caricarle in modo diverso: verifica la loro documentazione.
Aggiungi un AGENTS.md in una sottocartella quando quella parte del progetto usa comandi o convenzioni specifici. Mantieni le regole comuni alla radice, senza ricopiarle in ogni cartella.
Verificare il comportamento reale
- Controlla nome del file e cartella di lavoro.
- Dopo una modifica alle istruzioni, avvia una nuova esecuzione e chiedi quali file si applicano.
- Assegna una piccola modifica e controlla percorsi, comandi e risultato.
- Se una regola viene ignorata, cerca conflitti e file override, poi chiarisci la formulazione.
Ripetere correttamente le istruzioni non dimostra di averle rispettate. Guarda il lavoro effettivo. Codex prevede anche un limite complessivo alle istruzioni di progetto: un file molto lungo potrebbe non essere caricato interamente.
I controlli tecnici restano separati
Scrivere «non leggere le chiavi segrete» non limita i permessi di accesso. Chiedere all’agente di eseguire i test non configura controlli automatici. Imposta separatamente permessi, protezione dei branch e integrazione continua (CI). Non inserire credenziali reali negli esempi.
Aggiorna il file insieme al progetto. Aggiungi una regola per un problema concreto che si ripete, verificane l’effetto ed elimina ciò che non serve più. Lo scopo è ridurre le supposizioni, non conservare tutte le vecchie correzioni.