AGENTS.md è lo standard aperto riconosciuto da quasi tutti gli agenti moderni — Copilot, Claude, Cursor, opencode e altri. Funziona come un contratto di repository: definisce le regole del gioco una volta, e ogni agente che lavora sul progetto le rispetta senza che tu le debba ripetere ogni sessione.

La differenza tra un repo “nudo” e uno con un AGENTS.md ben scritto è immediata: nel primo caso l’agente chiede, indovina e sbaglia; nel secondo caso opera con vincoli chiari e genera output coerenti con le tue convenzioni.

Un buon AGENTS.md non è un manuale: è un set di vincoli operativi che l’agente applica senza bisogno di istruzioni ripetute.

Lo standard AGENTS.md 📜

Un AGENTS.md efficace segue una struttura che può essere adattata a qualsiasi progetto, ma che ruota attorno a quattro aree:

1. Ambiente: linguaggi, framework, versioni, dipendenze principali. L’agente deve sapere con cosa lavora prima di toccare una riga di codice.
2. Convenzioni: stile, naming, pattern architetturali, formati dei commit. Le regole che rendono il codice coerente con il resto del progetto.
3. Test: come si eseguono, cosa si copre, quale framework. La fase di validazione dipende da queste informazioni.
4. Confini: cosa NON toccare, moduli deprecati, aree sensibili. Il vincolo negativo è spesso più importante di quello positivo.

La lunghezza ideale? Sotto le 1000 righe. Un file più lungo di così è un segnale che stai mettendo troppo: le regole troppo specifiche sono meglio in skill dedicate.

Il file va trattato come codice: versionato, revisionato, iterato. Ogni volta che l’agente fa una cosa che non avresti voluto, aggiungi o aggiorna una regola. Ogni volta che una regola non serve più, eliminala.

Gerarchia e monorepo 🏗️

In un progetto complesso, un singolo AGENTS.md nella root non basta. La soluzione è la gerarchia:

• Root AGENTS.md: regole generali del progetto — stack, convenzioni, confini globali.
• Subdirectory AGENTS.md: regole specifiche per modulo. Un AGENTS.md in src/api/ può definire le convenzioni REST, quello in src/auth/ le regole sulla gestione dei token.
• Cross-reference: i file nelle subdirectory possono riferirsi a quello root con @relative/path/AGENTS.md per ereditare le regole generali senza duplicarle.

In un monorepo la gerarchia diventa essenziale. Ogni package ha le sue regole, ma condivide un nucleo di convenzioni. La gerarchia permette di definire una volta sola ciò che è comune e di specializzare ciò che è specifico.

La gerarchia del contesto non è un lusso architetturale: è l’unico modo per mantenere la coerenza in progetti con più moduli e più squadre.

File .ignore 🔒

Il .ignore (o il corrispettivo del tuo strumento) controlla cosa l’agente non deve vedere. Questo è critico per tre motivi:

1. Sicurezza: file di configurazione con segreti, credenziali, chiavi API. L’agente non deve mai averne accesso.
2. Pulizia: dipendenze (node_modules/, vendor/), build artifacts, log. Questo materiale è puro rumore per il contesto.
3. Performance: più file l’agente deve processare, più lento e costoso diventa il ciclo di lavoro.

Cosa escludere tipicamente:

• Cartelle di dipendenze e build
• File di log e temporanei
• Snapshot e fixture di test (se non pertinente)
• File di configurazione con segreti
• Asset binari grandi

La sintassi segue quella di .gitignore, quindi non serve imparare un nuovo formato. La differenza è concettuale: .gitignore protegge il repository dall’ambiente; .ignore protegge l’agente dal rumore.

Istruzioni vs skill 🧩

Un punto che confonde spesso: qual è la differenza tra un AGENTS.md e una SKILL.md?

• AGENTS.md contiene regole sempre valide — convenzioni, vincoli, informazioni strutturali. È il contratto di base del progetto.
• SKILL.md contiene procedure specialistiche e attivabili on-demand — workflow specifici, pattern avanzati, istruzioni per casi d’uso particolari.

Un esempio concreto: AGENTS.md dice “i test si eseguono con npm test e devono passare tutti”. Una skill dice “quando fai TDD, segui questo ciclo specifico: scrivi il test, fallo fallire, implementa, refactoring”.

La regola pratica: se la regola si applica a ogni task, va in AGENTS.md. Se si applica a un tipo specifico di task, va in una skill. Le skill possono essere caricate solo quando servono, riducendo il contesto inutile.

AGENTS.md è la costituzione; le skill sono le leggi speciali. Le prime definiscono i principi, le seconde i procedimenti.

Quando NON usare l’agente ⛔

• Repository senza .ignore configurato: l’agente vede tutto, incluso ciò che non dovrebbe.
• AGENTS.md inesistente o vuoto: l’agente opera senza vincoli, generando output potenzialmente incoerente.
• Regole troppo numerose o contraddittorie: un AGENTS.md di 5000 righe con regole conflittuali è peggio di nessun file.

Checklist finale ✅

• Il AGENTS.md esiste nella root e definisce ambiente, convenzioni, test e confini?
• La lunghezza è sotto le 1000 righe?
• In un monorepo, le subdirectory hanno i loro file con cross-reference alla root?
• Il .ignore esclude dipendenze, segreti, log e build artifacts?
• Le regole sempre valide sono in AGENTS.md, le procedure specialistiche in skill dedicate?
• Il file è versionato e trattato come codice?

Approfondimenti 📚

• Blog: The collective mind — come il contesto condiviso costruisce una conoscenza collettiva.
• Blog: Maintain a rich context — mantenere il contesto denso nel tempo.
• Gestire il contesto come una risorsa — il livello precedente: come gestire il contesto durante il lavoro.