Jude Gao di Vercel presenta i risultati di una valutazione comparativa tra due approcci per trasmettere conoscenze specifiche di un framework agli agenti IA: skills (recupero attivo) e AGENTS.md (contesto passivo). Il risultato è inequivocabile: il metodo più semplice supera nettamente quello più sofisticato.
Il problema: Next.js 16 introduce nuove API (use cache, connection(), forbidden()) assenti dai dati di addestramento dei modelli IA. Senza documentazione aggiornata, gli agenti generano codice errato nel 47% dei casi.
Skills: il fallimento del recupero attivo: Le skills, uno standard aperto per impacchettare conoscenza invocabile su richiesta, si rivelano fragili. Nel 56% dei casi di valutazione, l'agente non ha mai invocato la skill disponibile, producendo un tasso di successo identico al riferimento di base (53%). Anche aggiungendo istruzioni esplicite che forzano l'invocazione (tasso di invocazione superiore al 95%), il tasso di successo sale solo al 79%, e i risultati variano drasticamente a seconda della formulazione esatta delle istruzioni.
AGENTS.md: la vittoria del contesto passivo: Un file markdown statico iniettato nel system prompt a ogni turno raggiunge un tasso di successo del 100% (build, lint e test). Questo approccio elimina tre fonti di fragilità: il punto decisionale (l'agente non deve scegliere di invocare), i problemi di disponibilità (l'informazione è sempre presente) e le questioni di ordinamento (nessuna sequenza di azioni richiesta).
Compressione aggressiva: Il team Vercel è riuscito a comprimere 40 KB di documentazione in un indice di 8 KB (una riduzione dell'80%) utilizzando un formato delimitato da pipe, mantenendo il tasso di successo del 100%. Questa compressione è essenziale poiché AGENTS.md consuma finestra di contesto a ogni interazione.
Implicazioni per l'ecosistema: I risultati suggeriscono che, per la conoscenza generale di un framework, il contesto passivo (sempre disponibile) supera il recupero attivo (su richiesta). Le skills conservano comunque la loro utilità per i flussi di lavoro d'azione espliciti. Vercel fornisce un comando di installazione (npx @next/codemod@canary agents-md) che rileva automaticamente la versione di Next.js e genera l'AGENTS.md corrispondente.
Raccomandazioni: Non attendere che le skills migliorino, comprimere aggressivamente la documentazione in indici e costruire valutazioni che mirino specificamente alle API assenti dai dati di addestramento. Questi risultati hanno implicazioni dirette per tutti i maintainer di framework e librerie che cercano di ottimizzare la compatibilità con gli agenti di codifica IA.