Il Suo AGENTS.md È il Suo Vantaggio Competitivo: Cosa Inserire nei File di Produzione

Quando create-next-app ha incluso AGENTS.md come scaffolding predefinito tre giorni fa, la scelta del framework ha smesso di differenziare. Il contenuto di quel file è ora l'unica cosa che separa uno stack agente funzionante da uno non funzionante.

Per sei mesi, avere un AGENTS.md significava che il team era avanti. Dal 2026-04-28, ogni nuovo progetto Next.js ne include uno. Il segnale è scomparso. Ciò che si trova dentro il file è il nuovo segnale.

La maggior parte dei responsabili tecnici tratta AGENTS.md come documentazione. È un file di configurazione runtime che il modello carica a ogni chiamata. Questo articolo analizza lo studio empirico di Augment Code, la regola delle 100-150 righe che determina se il file aiuta o nuoce, e il pattern del template applicato nei repository clienti in produzione.

Cambiamenti nel contratto del file

• Next.js 16.2 include AGENTS.md come scaffolding predefinito (rilasciato il 2026-04-28). Ogni nuovo starter su Vercel lo eredita.
• Lo studio AuggieBench di Augment Code (2026-04-23): i file tra 100 e 150 righe ottengono i risultati migliori. Oltre 150 righe, i guadagni si invertono.
• Lo stesso file può aumentare la precisione nella correzione dei bug del 25% e ridurre la completezza delle funzionalità del 30% su compiti diversi. Il design delle sezioni conta più della lunghezza totale.
• AGENTS.md è l'unica superficie documentale con un tasso di scoperta del 100%. Le cartelle _docs/ abbandonate si attestano sotto il 10%.
• Il nuovo vantaggio sono i workflow procedurali, le tabelle decisionali e le regole reattive in una riga. Non panoramiche architetturali o avvisi sovrapposti.

Tre Giorni Fa, AGENTS.md Ha Smesso di Essere un Differenziatore

Next.js 16.2 è stato rilasciato il 2026-04-28 con AGENTS.md come file predefinito nel template create-next-app. Vercel distribuisce lo scaffolding a ogni nuovo progetto starter. Il file che un tempo indicava un team avanzato ora è incluso nella configurazione base.

Il cambiamento nella conversazione è il punto centrale. Sei mesi fa la domanda era se il suo team avesse un AGENTS.md. Questa settimana la domanda è diventata cosa ci fosse dentro. Chi valuta partner di sviluppo ha bisogno di un nuovo schema di valutazione, perché il segnale binario è sparito.

Due segnali paralleli rafforzano il cambiamento. Il repository mattpocock/skills di Matt Pocock ha raggiunto 41.000 stelle in 85 giorni, e il repository è la sua cartella .claude pubblicata integralmente. Le persone mettono stelle alle configurazioni agente altrui come facevano con i framework. Questo è l'aspetto della commoditizzazione.

Il repository gstack di Garry Tan, rilasciato la stessa settimana, ha superato 23.000 stelle in sette giorni. Tan lo ha usato per consegnare 600.000 righe di codice di produzione in 60 giorni. Il repository contiene 31 file markdown di skill. Non c'è alcun framework sottostante.

Se il team procurement ha bisogno di un sistema per valutare la maturità AI nelle selezioni di fornitori, webvise può illustrare il criterio applicato nei progetti clienti.

La Regola delle 100-150 Righe, con Misurazione

Augment Code ha pubblicato il primo studio empirico sulla qualità del contenuto di AGENTS.md il 2026-04-23. L'autore, Slava Zhenylenko, ha analizzato decine di file AGENTS.md dal monorepo di Augment. Ogni file è stato eseguito due volte attraverso la suite di valutazione AuggieBench: una volta con il file presente e una volta senza. L'output è stato confrontato con la PR definitiva approvata dagli sviluppatori.

Il risultato principale: i file migliori hanno prodotto un salto di qualità equivalente all'aggiornamento da Haiku a Opus. I file peggiori hanno generato output peggiore rispetto all'assenza totale di AGENTS.md. Lo stesso team di ingegneri, lo stesso modello, lo stesso compito. Il file ha determinato la differenza.

L'intervallo ottimale era preciso. I file tra 100 e 150 righe, abbinati a un piccolo insieme di documenti di riferimento caricati su richiesta, hanno prodotto guadagni del 10-15% su tutte le metriche in moduli di dimensione media con circa 100 file principali. Oltre 150 righe, i guadagni si sono invertiti.

La confessione di Tan ha confermato il risultato dal lato dei principi. Il suo CLAUDE.md aveva 20.000 righe, con ogni particolarità, ogni pattern e ogni lezione codificata in un unico file. Claude Code stesso ha segnalato il problema. La soluzione è stata circa 200 righe di puntatori, con il contenuto sostanziale spostato in skill caricate su richiesta.

Il template nei repository clienti webvise si mantiene all'interno dell'intervallo raccomandato da Augment. I nomi dei repository clienti non vengono pubblicati, perché conta il pattern operativo: un file di ingresso compatto con placeholder specifici per il progetto, e skill estratte solo dopo che il team ha risolto un problema ricorrente.

I tassi di scoperta dalle tracce di Augment su centinaia di sessioni spiegano perché il posizionamento conta quanto il contenuto:

AGENTS.md è l'unica superficie con scoperta affidabile. Se qualcosa deve essere visto, si trova lì o è referenziato da lì. Spostare il contenuto in una posizione referenziata produce più risultati che scrivere altra documentazione.

Cosa Inserire nel File e Cosa lo Danneggia

Le tracce di Augment sono state analizzate per tipo di contenuto. I pattern che hanno migliorato l'output e quelli che lo hanno compromesso non sono simmetrici.

Cosa funziona

• Workflow procedurali. I workflow numerati a più passi sono stati il singolo pattern più efficace. Un workflow in sei passi per il deploy di una nuova integrazione ha ridotto le PR con file di cablaggio mancanti dal 40% al 10%, aumentando la correttezza del 25% e la completezza del 20%.
• Tabelle decisionali quando esistono 2 o 3 opzioni ragionevoli. Una tabella decisionale React Query versus Zustand ha prodotto un aumento del 25% nelle best_practices sulle PR in quell'area. La tabella risolve l'ambiguità prima che l'agente scriva codice.
• Esempi reali del codebase, da 3 a 10 righe ciascuno. Migliorano il riutilizzo e l'aderenza ai pattern. Oltre questa lunghezza, l'agente fa pattern-matching sugli elementi sbagliati.
• Abbinare a ogni divieto un'indicazione positiva. La documentazione con soli avvisi ottiene risultati inferiori. Un divieto generico rende l'agente cauto ed esplorativo. Abbinarlo a una direttiva positiva che nomina il call site corretto fa procedere l'agente.
• File a livello di modulo rispetto a un unico file radice gigante. La banda delle 100-150 righe si adatta a un modulo di medie dimensioni con circa 100 file. I file radice trasversali oltre quella dimensione hanno perso su ogni metrica.

Cosa danneggia l'output

• Panoramiche architetturali. L'agente legge la panoramica, poi apre decine di documenti correlati per verificare il proprio approccio, carica da 10.000 a 100.000 token di contesto irrilevante e l'output degrada. Augment ha denominato questo la trappola della sovraesplorazione.
• Avvisi sovrapposti senza guida complementare. Con 30-50 divieti e nessuna indicazione positiva, l'agente verifica la propria soluzione contro ogni avviso singolarmente, anche quando nessuno si applica.
• Pattern non ancora presenti nel codebase. Se AGENTS.md descrive un'architettura che il codice non implementa, il file guida attivamente l'agente nella direzione sbagliata.
• Documentazione dispersa intorno al file. I peggiori performer analizzati da Augment erano file AGENTS.md posizionati sopra 500K-2MB di documenti architetturali. Rimuovere AGENTS.md modificava a malapena il comportamento: l'agente leggeva comunque la documentazione dispersa.

Reattivo, Non Prescritto

Elie Steinbock ha pubblicato un articolo separato il 2026-04-20 con una disciplina che risolve la maggior parte dei file AGENTS.md aziendali analizzati. Non si devono scrivere decine di regole prima che qualcosa sia andato storto. La sovrastrutturazione preventiva crea bloat che il modello analizza a ogni esecuzione.

Le regole si aggiungono in modo reattivo, quando si è verificata una correzione reale, limitando le aggiunte a una riga. Per qualsiasi contenuto più pesante, il materiale va spostato in una skill a caricamento progressivo. AGENTS.md rimane compatto. Il livello delle skill assorbe il peso.

La regola parallela di Tan, la disciplina del twice-you-failed, dice la stessa cosa dall'altra prospettiva. Se si deve chiedere all'agente la stessa cosa due volte, la seconda richiesta non dovrebbe esistere. Il pattern va nel livello delle skill o in AGENTS.md come una riga. Il sistema si consolida.

Nella pratica webvise: AGENTS.md viene incluso come file di ingresso compatto basato su placeholder. La directory .claude/skills contiene un insieme ridotto di file di skill specifici per la consegna, ciascuno una procedura che il team ha effettivamente eseguito durante il build. Il file non anticipa i problemi. Registra quelli risolti.

Cinque Domande che il Procurement Dovrebbe Porre a Ogni Fornitore

La qualità del contenuto di AGENTS.md è ora un indicatore misurabile di esecuzione AI-native. Le cinque domande seguenti consentono a un team di procurement non tecnico di valutare rapidamente se un fornitore sta sviluppando per lo stack del 2026 o per quello del 2024.

Se un fornitore non riesce a rispondere a tre delle cinque domande, sta ancora usando il template del 2024. La maggior parte dei team aziendali si scontra con questo limite a livello di documentazione. Quell'audit è la prima fase di ogni engagement di migrazione webvise.

Il Risultato Più Profondo: Correggere l'Ambiente, Non Solo il Punto di Ingresso

Il risultato più scomodo di Augment è emerso dai file AGENTS.md con le prestazioni peggiori. Si trovavano sopra 500K-2MB di documentazione architetturale circostante. Rimuovendo solo AGENTS.md dall'esecuzione, il comportamento è cambiato appena. L'agente leggeva comunque la documentazione dispersa, indipendentemente da quanto dicesse il file di ingresso.

Le implicazioni sono difficili per i team aziendali con sistemi legacy. La maggior parte degli ambienti documentali costruiti prima del 2024 contiene anni di architecture decision record, design doc e runbook. L'agente ne carica abbastanza da sovrastare un AGENTS.md pulito. Scrivere un file di ingresso migliore è necessario, ma non sufficiente.

Il lavoro è impegnativo. Occorre analizzare i documenti che l'agente effettivamente carica, archiviare quelli obsoleti, modularizzare quelli attivi in riferimenti a livello di modulo, e mantenere AGENTS.md puntato solo su ciò che l'agente dovrebbe leggere nel percorso verso la modifica. Vale il framing di Tan: il brain è un repository git, l'orchestratore è un conduttore snello che legge file. Se il repository git è pieno di pagine morte, nessun file di ingresso lo risolve.

Checklist di Commissioning del Build

La guerra dei framework è finita. Next.js, Astro, SvelteKit e Nuxt includono tutti scaffolding AGENTS.md per impostazione predefinita, o lo faranno entro il trimestre. Il differenziatore si è spostato di un livello. Il contenuto del file, la struttura della directory delle skill e la disciplina che li sostiene determinano se lo stack agente aiuta o nuoce.

I build web moderni nel 2026 sono agent-readable fin dal primo giorno. È il contratto che webvise scrive per impostazione predefinita in ogni progetto, da un sito landing a pagina singola a un SaaS multi-tenant. Il template compatto, il livello .claude/skills e la disciplina delle regole reattive fanno parte del build.