Qualche tempo fa scrissi che, quando lavoriamo con i coding-agent Context is king. Alla base dei coding agents ci sono gli LLM, che hanno queste caratteristiche fondamentali:

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

Quando si tratta di lavorare professionalmente con i coding agent si tratta quindi di capire come rendere ciò che è non deterministico e con una conoscenza del mondo statica, in grado di lavorare in modo che possa avvicinarsi all’essere deterministico e con la conoscenza della nostra codebase. What could possibly go wrong? Tutto il marasma di blog post, video, talk, ricerca dell’ultimi 6 mesi o al massimo 1 anno si basa sta cercando di capire esattamente questo.

Se non hai vissuto sotto una roccia negli ultimi mesi, avrai sicuramente sentito parlare di AGENTS.md, un file che è diventato un punto di riferimento per chiunque voglia lavorare con i coding agent. Ma cosa dovrebbe contenere un buon AGENTS.md? E come possiamo scriverlo in modo efficace?

Ecco una ricerca da cui possiamo trarre alcune conclusioni interessanti.

  1. I modelli più avanzati riescono a esguire 150-200 istruzioni in modo soddisfacente. newplot. I modelli più piccoli possono gestire meno istruzioni rispetto ai modelli più grandi, e i modelli non pensanti (thinking) possono gestire ancora meno istruzioni rispetto ai modelli pensanti.

  2. I modelli più piccoli peggiorano MOLTO più rapidamente. In particolare, i modelli più piccoli tendono a mostrare un decadimento esponenziale nelle prestazioni di seguire le istruzioni man mano che il numero di istruzioni aumenta, mentre i modelli di pensiero di frontiera più grandi mostrano un decadimento lineare (vedi sotto). Per questo motivo, è sconsigliato l’uso di modelli più piccoli per compiti multi-step o piani di implementazione complicati.

  3. I modelli LLM tendono a dare priorità alle istruzioni che si trovano ai margini del prompt: all’inizio (il messaggio di sistema) e alla fine (i messaggi utente più recenti).

  4. Man mano che il numero di istruzioni aumenta, la qualità del seguire le istruzioni diminuisce uniformemente. Ciò significa che, man mano che si danno più istruzioni all’LLM, non ignora semplicemente le istruzioni più recenti (“più in basso nel file”), ma inizia a ignorarle tutte uniformemente.

Suggerimenti pratici

Lunghezza

Siccome il file AGENTS.md viene iniettato in ogni singola sessione, dobbiamo assicurarci che il suo contenuto sia generico e universalmente applicabile. Ad esempio, evita di includere specifiche sulle strategie di indicizzazione del database.

In termini di lunghezza, meglio mantenere il file sotto le 100 righe.

Progressive discolure

Scrivere un file AGENTS.md che comprenda le cose importanti è una sfida, soprattutto in progetti grandi e complessi. Per questo motivo, è consigliabile adottare un approccio di progressive disclosure, in cui si forniscono solo le informazioni essenziali e si rimanda a documentazione più dettagliata per ulteriori approfondimenti.

Gli agenti sono grandiosi nel seguire link tra file markdown quindi puoi pensare a una struttura tipo:

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

Poi, nel tuo file AGENTS.md, puoi includere solo le informazioni essenziali e rimandare a questi file per ulteriori dettagli. In questo modo, mantieni il file AGENTS.md snello e facile da seguire, ma fornisci comunque tutte le informazioni necessarie per lavorare efficacemente con i coding agent che caricheranno quando necessario senza sovraccaricare il contesto.

Automazione

Evita di far scrivere il file da strumenti di generazione oppure rivedilo in modo critico e accurato (es. /init).

Less-is more

Visto che AGENTS.md è incluso in ogni chiama all’LLM, ogni riga di AGENTS.md di fatto influenza ogni fase di ricerca, implementazione, revisione… Perciò se questa riga è fatta bene, influenza bene OGNI SINGOLO prompt e ogni singolo output. Se fatta male, può degradarne la qualità. Per questo motivo ha un “effetto leva” potentissimo e perciò il suo contenuto deve essere cesellato. E, come in molti casi della vita, anche qui vale perciò il less is more.

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 le tue best practice e i tuoi esempi di AGENTS.md con il tuo team!