Cosa deve fare davvero
Il file non deve raccontare tutta la storia del progetto. Deve fornire le informazioni stabili che cambiano il modo in cui un agente analizza, modifica e verifica il codice.
La domanda utile è: quali regole dovrei ripetere in quasi ogni task? Quelle sono buone candidate per AGENTS.md.
- Descrivere in poche righe prodotto, stack e struttura del repository.
- Indicare i comandi affidabili per installazione, sviluppo, test e build.
- Dichiarare confini e aree che non devono essere modificate senza richiesta.
- Spiegare convenzioni tecniche che non sono evidenti dal codice.
- Definire quali controlli rendono una modifica realmente completata.
AGENTS.md per Codex: cosa indicare
Per Codex il file è utile quando trasforma conoscenza stabile del progetto in istruzioni operative. Non deve essere un secondo README: deve dire come lavorare, cosa verificare e quali limiti rispettare.
Scrivilo pensando a una sessione reale: l’agente entra nel repository, deve capire dove mettere le mani, quali comandi usare e quando può considerare finito il task.
- Stack e cartelle principali: solo ciò che orienta il lavoro.
- Comandi affidabili per installare, avviare, testare e fare build.
- Regole di sicurezza: niente segreti nel frontend, niente file locali committati.
- Vincoli di scope: niente refactor non richiesti e niente modifiche fuori area.
- Definition of done: build, test, verifica manuale e riepilogo finale.
- Preferenze di risposta: cosa deve riportare Codex alla fine del task.
Una struttura semplice che funziona
Mantieni titoli prevedibili e istruzioni verificabili. Le frasi operative funzionano meglio di descrizioni vaghe come “scrivi codice di qualità”.
# AGENTS.md
## Progetto
- Applicazione Angular pubblicata come sito statico.
- Il frontend non deve contenere API key o altri segreti.
## Prima di modificare
- Leggi routing, componente coinvolto e stili condivisi.
- Controlla le modifiche locali e non sovrascrivere lavoro non collegato.
- Mantieni il task entro lo scope richiesto.
## Convenzioni
- Riusa componenti e classi CSS esistenti.
- Evita nuove dipendenze quando basta una soluzione locale semplice.
- Mantieni testi e layout utilizzabili su mobile.
## Verifica
- Esegui npm run build.
- Prova il flusso modificato nel browser.
- Controlla errori console e regressioni responsive.
## Risposta finale
- Riassumi cosa è cambiato.
- Elenca i controlli eseguiti.
- Dichiara rischi o parti non verificate.Cosa non inserire
- API key, credenziali, URL privati o altri valori sensibili.
- Il task del giorno: appartiene al prompt, non alle istruzioni permanenti.
- Regole contraddittorie o impossibili da verificare.
- Documentazione enciclopedica già presente altrove nel repository.
- Comandi vecchi o non più eseguibili.
Quando servono istruzioni per cartella
Nei repository grandi possono esistere regole diverse per frontend, backend o documentazione. In quel caso conviene aggiungere file AGENTS.md più vicini alle relative aree, mantenendo nel file principale solo le regole comuni.
Le istruzioni locali devono aggiungere precisione, non duplicare tutto il file radice.
Errori comuni da evitare
- Scrivere istruzioni generiche come “fai codice pulito” senza dire come verificarlo.
- Duplicare tutto il README invece di indicare regole operative.
- Inserire task temporanei che andrebbero nel prompt della singola sessione.
- Aggiungere comandi non testati o vecchi, che faranno perdere tempo all’agente.
- Nascondere eccezioni importanti: cartelle da non toccare, file generati, configurazioni delicate.
- Creare un file troppo lungo: se l’agente deve leggerlo spesso, ogni riga deve servire.
FAQ su AGENTS.md
- AGENTS.md serve solo a Codex?
- No. Il nome è usato da diversi workflow per dare istruzioni agli agenti, ma il contenuto utile resta lo stesso: contesto stabile, comandi, vincoli e criteri di verifica.
- Che differenza c’è tra AGENTS.md e README?
- Il README spiega il progetto a persone e contributor. AGENTS.md spiega a un agente come lavorare nel repository senza uscire dallo scope.
- Devo mettere dentro ogni dettaglio del progetto?
- No. Inserisci solo le regole che cambiano il comportamento dell’agente. I dettagli temporanei vanno nel prompt del task.
- Posso avere più file AGENTS.md?
- Sì, nei repository grandi può avere senso aggiungere istruzioni locali per frontend, backend, documentazione o test, evitando duplicazioni inutili.
Come mantenerlo utile
- Quando l’agente ripete un errore, chiediti se manca una regola stabile.
- Quando un comando cambia, aggiorna subito la sezione di verifica.
- Ogni tanto elimina istruzioni duplicate, vaghe o non più applicabili.
- Prova il file con un task reale e controlla se riduce domande e correzioni.