Se lavori con i coding agent, AGENTS.md è uno dei modi più efficaci per dargli contesto utile senza ripeterti a ogni sessione.

Ne ho parlato anche in Context is king: la qualità dell’output dipende molto dal contesto che fornisci al modello. Un buon file AGENTS.md serve proprio a questo. Aiuta l’agente a capire regole, convenzioni e punti delicati della codebase senza appesantire inutilmente il prompt.

Alla base dei coding agent ci sono gli LLM, che hanno alcune caratteristiche fondamentali:

  • Sono non-deterministici / probabilistici
  • Hanno una finestra di contesto limitata
  • Hanno una conoscenza finita e fissa data dal loro training
  • Ogni chiamata a un LLM è una funzione stateless

Quando lavoriamo professionalmente con questi strumenti, il punto è proprio questo: prendere un sistema probabilistico, con conoscenza statica del mondo, e portarlo a lavorare in modo più affidabile dentro la nostra codebase.

Negli ultimi mesi AGENTS.md è diventato un riferimento per chi usa coding agent in modo serio. La domanda quindi è: cosa deve contenere un buon AGENTS.md e come lo si scrive senza trasformarlo in un mattone?

Una ricerca recente ci dà alcune indicazioni molto utili.

Cosa ci dice la ricerca su AGENTS.md

  1. I modelli più avanzati riescono a seguire molte più istruzioni. I modelli di frontiera possono gestire anche 150-200 istruzioni in modo soddisfacente. I modelli più piccoli, invece, reggono molto meno.

  2. I modelli più piccoli degradano molto più in fretta. Quando il numero di istruzioni cresce, la loro capacità di seguirle cala rapidamente. Per task multi-step o piani di implementazione complessi, questa differenza pesa parecchio.

  3. Gli LLM prestano più attenzione ai margini del prompt. In pratica, pesano molto il messaggio di sistema e i messaggi utente più recenti.

  4. Aumentare le istruzioni peggiora la fedeltà complessiva. Non è solo una questione di “le ultime righe vengono ignorate”. Quando si esagera, il modello inizia a seguire peggio tutto il set di istruzioni.

Il punto pratico è semplice: se AGENTS.md cresce troppo, non stai aiutando il modello. Lo stai distraendo.

Come scrivere un AGENTS.md utile

Lunghezza

Siccome AGENTS.md viene iniettato in ogni singola sessione, il suo contenuto deve essere riusabile e universalmente applicabile. Evita quindi dettagli troppo specifici, come regole valide solo per un database o per una singola feature.

In termini di lunghezza, stare sotto le 100 righe è una buona regola pratica.

Progressive disclosure

Scrivere un file AGENTS.md che contenga le cose davvero importanti non è banale, soprattutto in progetti grandi. Per questo conviene usare la progressive disclosure: nel file principale metti solo l’essenziale e rimandi a documentazione più specifica per gli approfondimenti.

Gli agenti sono molto bravi a seguire link tra file markdown, quindi puoi impostare una struttura del genere:

docs/
  | - running-tests.md
  | - database.md
  | - api.md
AGENTS.md

Poi, nel file principale, includi solo le regole essenziali e rimanda ai documenti di dettaglio. Se il tema ti interessa, qui c’è un’altra riflessione utile su documentazione nell’era dell’agentic coding.

In questo modo mantieni AGENTS.md snello e facile da seguire, ma dai comunque ai coding agent tutto ciò che serve al momento giusto, senza sovraccaricare il contesto.

Automazione

Evita di far scrivere AGENTS.md in modo completamente automatico oppure, se parti da uno strumento di generazione, rivedilo in modo critico e accurato. Vale per /init come per qualunque altro bootstrap iniziale.

Less is more

Visto che AGENTS.md è incluso in ogni chiamata all’LLM, ogni riga influenza ricerca, implementazione e revisione. Se una regola è scritta bene, migliora molti prompt. Se è scritta male, può peggiorare molti output.

Per questo il file ha un effetto leva enorme e va trattato con cura. Qui si collega bene anche il principio di plan due volte implementa una: prima chiarisci il contesto, poi chiedi esecuzione.

Checklist finale per il tuo AGENTS.md

  • Spiega solo regole davvero riusabili
  • Rimanda a file dedicati per test, database, API e procedure operative
  • Tiene fuori i dettagli di feature temporanee
  • Resta corto abbastanza da non diventare rumore
  • Viene rivisto da umani, non pubblicato alla cieca
  • Aiuta l’agente a capire come lavorare, non a conoscere tutto il progetto

Azione

Detto tutto ciò, ecco cosa puoi fare da subito:

  • Rivedi il tuo AGENTS.md e assicurati che sia snello, chiaro e ben strutturato.
  • Se non hai un AGENTS.md, inizia a scriverlo seguendo i principi di cui abbiamo parlato.
  • Condividi con il team gli esempi che funzionano davvero, così costruite uno standard utile e non un file cerimoniale.