Hai mai avuto quella sensazione quando scopri che la soluzione più elegante è anche la più semplice? Bene, mettiti comodo, perché oggi parliamo di AGENTS.md, il file Markdown che ha mandato in pensione le skill AI più sofisticate.
Tutto è iniziato con un problema apparentemente banale: come far sì che gli agenti AI generino codice corretto per Next.js 16, soprattutto quando le loro conoscenze pre-addestrate sono ormai obsolete. Le skill AI, quelle che dovrebbero recuperare informazioni su richiesta, si sono rivelate inaffidabili. Ecco perché gli ingegneri di Next.js hanno deciso di provare un approccio radicalmente diverso: invece di affidarsi a decisioni complesse degli agenti, hanno imbottito un file AGENTS.md con un indice compresso della documentazione.
E indovina un po’? Ha funzionato alla grande. Con un semplice file di 8KB, hanno ottenuto un tasso di successo del 100% in build, lint e test. Niente decisioni complesse, niente problemi di sequenza: solo informazioni sempre disponibili.
Da smanettone, trovo questa soluzione affascinante. È come quando preferisci un buon vecchio file di configurazione ben scritto a un sistema di plugin complicato. Semplice, diretto, efficiente. E il fatto che sia basato su Markdown lo rende ancora più sexy: finalmente un formato che anche noi umani possiamo leggere e modificare senza bisogno di strumenti esoterici.
Ma cosa significa per noi che amiamo mettere le mani in pasta? Prima di tutto, è un promemoria che a volte la soluzione migliore è la più banale. Non dobbiamo sempre cercare sistemi complessi quando una semplice lista di riferimenti può fare il lavoro.
In secondo luogo, è un invito a ripensare come strutturiamo la nostra documentazione. Se vogliamo che gli agenti AI la utilizzino al meglio, dobbiamo organizzarla in modo che sia facilmente consultabile, con un indice chiaro e strutturato. E, ovviamente, compresso per non appesantire i contesti.
Certo, non è tutto rose e fiori. Affidarsi a un file statico significa che la documentazione deve essere sempre aggiornata. Ma per una volta, il problema è gestibile: basta un comando (npx @next/codemod@canary agents-md) per scaricare la documentazione corretta e iniettarla nel nostro progetto.
E per chi mantiene framework, è un’opportunità. Provate a immaginare se ogni framework avesse un snippet AGENTS.md pronto per l’uso. Potremmo finalmente dire addio alle discussioni infinite sui bug causati da versioni obsolete della documentazione.
In conclusione, questa storia è un bel promemoria che, a volte, la tecnologia più avanzata non è quella più complessa. E per noi smanettoni, è un altro strumento in più nel nostro arsenale. Ora, chi ha detto che i file Markdown sono noiosi?