La proposta AGENTS.md del kernel Linux verifica se gli agenti AI possono seguire le regole umane

La proposta AGENTS.md del kernel Linux aggiunge un solo collegamento simbolico, ma punta a un conflitto crescente sul codice assistito dall’AI. Presentata il 24 settembre 2026, la patch renderebbe più semplice per gli agenti di coding trovare automaticamente le istruzioni esistenti del kernel.

Il file proposto non autorizzerebbe contributi autonomi né allenterebbe gli standard di revisione del kernel. Indirizzerebbe gli agenti verso un README che già rimanda gli strumenti AI alla dettagliata policy di contribuzione del progetto. La modifica affronta un problema più circoscritto: gli agenti spesso agiscono prima di leggere documentazione scritta principalmente per le persone.

Questa distinzione conta perché il kernel già dice agli strumenti AI di non certificare patch per conto di una persona. Richiede inoltre revisione umana, attribuzione corretta, test e responsabilità. La proposta AGENTS.md del kernel Linux contrappone quindi istruzioni facilmente individuabili a una realtà più difficile: un file di repository può guidare un agente, ma non può rendere affidabile una patch inaffidabile.

La proposta AGENTS.md del kernel Linux modifica un solo punto di ingresso

La patch modifica il modo in cui gli agenti scoprono le regole esistenti, non le regole stesse.

Il maintainer del kernel Sasha Levin ha presentato una patch intitolata “docs: add AGENTS.md as a symlink to README.” La proposta crea un collegamento simbolico di primo livello chiamato AGENTS.md, che punta al file README già presente nel repository.

Un collegamento simbolico è un riferimento del filesystem che reindirizza un nome file a un altro file. In questo caso, un agente che aprisse AGENTS.md riceverebbe lo stesso materiale già disponibile tramite README, anziché una seconda copia delle istruzioni.

Questo design evita di creare due documenti di policy che i maintainer dovrebbero sincronizzare. La proposta di collegamento simbolico di Levin afferma che il README esistente indirizza già gli strumenti AI a Documentation/process/coding-assistants.rst. Il problema è che un agente deve decidere di aprire il README prima che quel rimando possa aiutarlo.

Molti agenti di coding ispezionano automaticamente file di istruzioni con nomi specifici. AGENTS.md è diventato uno dei nomi file comuni per indicazioni a livello di repository, inclusi comandi di build, requisiti di test, convenzioni di coding e limiti di sicurezza.

Il file proposto per il kernel non conterrebbe testo separato. Il suo unico contenuto sarebbe la destinazione del collegamento, README. In questo modo, i percorsi di ingresso per persone e macchine restano collegati a un’unica fonte mantenuta.

Levin ha incluso un esempio controllato per spiegare perché la rilevabilità sia importante. Due agenti hanno ricevuto la stessa richiesta: creare un commit che rinominasse la release del kernel nel Makefile in “AI Test.”

Senza AGENTS.md, un agente ha generato una riga Signed-off-by per l’utente. L’altro non ha fornito alcuna attribuzione all’AI. Entrambi i risultati erano in conflitto con le aspettative documentate del kernel.

Con il collegamento simbolico presente, entrambi gli agenti avrebbero invece usato un tag Assisted-by: LLM ed evitato di aggiungere una firma umana. Hanno inoltre seguito più da vicino le convenzioni del progetto per i messaggi di commit. Uno ha aggiunto un corpo descrittivo, mentre l’altro ha usato la struttura prevista “subsystem: summary phrase” per l’oggetto.

Si è trattato di un test comportamentale limitato, non di una valutazione ampia dell’affidabilità degli agenti. Non ha misurato se gli agenti potessero trovare bug sottili, produrre correzioni sicure o comprendere vincoli specifici dei sottosistemi. Ha mostrato che due agenti si sono comportati diversamente dopo aver ricevuto un percorso scoperto automaticamente verso istruzioni esistenti.

Al momento della segnalazione, la modifica era ancora in fase di revisione. Descriverla come qualcosa che Linux ha già adottato sovrastimerebbe quindi l’evento. L’affermazione accurata è che un maintainer del kernel ha proposto il collegamento e ha fornito elementi a suo sostegno.

Kees Cook, noto sviluppatore di sicurezza del kernel, ha risposto con un riconoscimento. Ha sostenuto l’uso del README invece di mantenere una policy separata riservata agli agenti. La sua risposta alla revisione ha inoltre osservato che sarebbe auspicabile far leggere agli agenti la documentazione per i contributi prima di creare patch.

La patch è abbastanza piccola da sembrare cerimoniale. Il suo scopo pratico è però concreto: cerca di inserire informazioni obbligatorie sul processo nel percorso che uno strumento AI è già addestrato o configurato a ispezionare.

Questo rende la proposta una modifica dell’interfaccia. Le persone possono esplorare gli alberi della documentazione e interpretare le norme della comunità. Gli agenti di coding operano in modo più prevedibile quando i repository espongono tali norme tramite nomi file e percorsi riconosciuti dagli strumenti.

La domanda risultante non è se Markdown possa migliorare il codice generato. È se un punto di ingresso affidabile possa prevenire errori ricorrenti di processo prima che i maintainer debbano intercettarli manualmente.

Le regole esistenti del kernel mantengono comunque gli esseri umani responsabili

La policy AI del kernel Linux tratta un agente come assistente, mai come proprietario legale o tecnico di un contributo.

Le regole sottostanti si spingono già ben oltre il collegamento simbolico proposto. La guida del kernel per i contributi AI indirizza gli strumenti AI e i loro utenti attraverso il processo di sviluppo standard, lo stile di coding, i requisiti per l’invio delle patch, le regole di licenza e la policy sui contenuti generati.

Soprattutto, la guida afferma che gli agenti AI non devono aggiungere un tag Signed-off-by. Quella riga non è un metadato decorativo del commit. Rappresenta la certificazione di una persona ai sensi del Developer Certificate of Origin, comunemente chiamato DCO.

Il DCO è il meccanismo attraverso il quale un contributore dichiara che il lavoro inviato può entrare legalmente nel progetto secondo la sua licenza. Un modello linguistico non può effettuare questa certificazione per conto di una persona. Non può nemmeno stabilire se quella persona abbia completato la revisione necessaria per assumersi la responsabilità.

Il mittente umano deve revisionare il codice generato, confermare la conformità alle licenze, aggiungere la firma e assumersi la responsabilità del contributo. Un agente che inserisce da solo la firma comprime questi passaggi distinti in testo generato.

Ecco perché il test di Levin è importante nonostante la sua portata ridotta. L’agente non ha semplicemente scelto uno stile di formattazione impopolare. Ha generato una dichiarazione che solo un essere umano può legittimamente fare.

La documentazione del kernel assegna alla partecipazione AI un indicatore diverso. Quando contribuisce uno strumento AI, la patch dovrebbe usare un tag Assisted-by. Anche strumenti di analisi opzionali come Coccinelle, Sparse, Smatch o Clang-Tidy possono apparire dopo l’etichetta LLM.

Questo modello di attribuzione distingue l’assistenza dall’autorialità e dalla certificazione. Offre ai revisori un contesto utile senza fingere che il modello possa assumersi responsabilità.

La documentazione stabilisce inoltre un processo rigoroso per il lavoro sui bug assistito dall’AI. Un agente dovrebbe leggere tutta la documentazione pertinente, individuare un bug specifico e tentare di riprodurre qualsiasi problema non banale. Dovrebbe abbandonare un riscontro che non supera la verifica.

Se il problema appare reale, l’agente dovrebbe scrivere una correzione, compilarla, testarla con il riproduttore o con un’analisi completa ed eseguire i controlli delle patch del kernel. Deve dichiarare tutto ciò che non è riuscito a verificare.

La guida dice inoltre all’agente di identificare i maintainer e le mailing list pertinenti. Deve valutare se il problema rientri nel normale processo per i bug o nel processo riservato per la sicurezza. L’agente deve lasciare l’invio effettivo alla persona che lo utilizza.

Questi requisiti mostrano i limiti del trattare AGENTS.md come una soluzione di per sé. Il file può indirizzare un agente alla checklist corretta. Non può confermare che un riproduttore sia significativo, che i test siano sufficienti o che l’essere umano comprenda il codice.

Lo sviluppo del kernel coinvolge inoltre migliaia di componenti con aspettative specializzate. Le istruzioni generali non possono contenere ogni vincolo architetturale, presupposto hardware o preferenza dei maintainer.

Un agente potrebbe rispettare perfettamente le regole di formattazione visibili e tuttavia fraintendere la gestione del ciclo di vita, il locking, l’ordinamento della memoria o il comportamento dei dispositivi. Un messaggio di commit ben rifinito può rendere una patch simile più facile da revisionare, ma non rende corretto il ragionamento sottostante.

Questo crea un limite utile. Le istruzioni del repository possono ridurre errori amministrativi evitabili. La fiducia tecnica deve comunque derivare da evidenze, test, revisione di esperti e contributori responsabili.

Per i maintainer, questa separazione è importante. Ogni invio malformato consuma attenzione prima ancora che qualcuno arrivi al suo contenuto tecnico. Una migliore individuazione delle istruzioni può ridurre tale sovraccarico senza abbassare la soglia di accettazione.

Per i contributori, la policy è altrettanto chiara. Usare un agente non trasferisce la responsabilità. Uno sviluppatore deve poter spiegare e difendere il risultato come se ogni riga fosse stata scritta manualmente.

Perché gli agenti di coding AI continuano a non leggere il README

Il conflitto è tra documentazione che esiste e istruzioni che compaiono nel contesto automatico di un agente.

Tradizionalmente, i repository organizzano le informazioni per i contributori pensando alle persone. Un README presenta il progetto, mentre file di contribuzione, directory di documentazione, pagine di mailing list e script raccolgono procedure più specializzate.

Una persona che arriva all’albero dei sorgenti Linux può seguire questa gerarchia. Un agente che riceve un prompt ristretto potrebbe invece ispezionare solo i file che considera immediatamente pertinenti. Se non apre mai il README alla radice, il collegamento del README alla policy AI resta invisibile.

Questo comportamento è emerso in una recente discussione del kernel su una correzione Qualcomm I2C assistita dall’AI. Un maintainer ha osservato che il processo era documentato attraverso una catena che iniziava nel README e continuava in coding-assistants.rst. Tuttavia, gli strumenti non seguivano quella catena in modo affidabile.

La discussione tra maintainer ha sollevato l’assenza di un file AGENTS.md o CLAUDE.md che gli strumenti comuni ispezionano per impostazione predefinita. Ha inoltre avvertito che l’aggiunta di un file simile non risolverebbe necessariamente ogni problema.

Questa è la pressione alla base della nuova proposta. I maintainer del kernel si trovano ad affrontare patch assistite dall’AI indipendentemente dal fatto che il repository ottimizzi o meno la propria documentazione per gli agenti. Rifiutarsi di aggiungere un punto di ingresso non impedisce ai contributori di usare questi strumenti.

La scelta pratica è più circoscritta. I maintainer possono lasciare agli agenti il compito di scoprire in modo incoerente documentazione orientata agli esseri umani, oppure inserire un segnale familiare nella radice del repository.

La convenzione più ampia AGENTS.md descrive il file come un README per gli agenti. La sua documentazione in formato aperto afferma che oltre 60.000 progetti open source utilizzano la convenzione, sebbene tale cifra rifletta esempi indicizzati anziché una misurazione verificata dell’uso attivo degli agenti.

Il formato non impone alcuno schema obbligatorio. Un progetto può elencare comandi di configurazione, regole di stile del codice, test, questioni di sicurezza o collegamenti a documentazione più approfondita. File annidati possono fornire istruzioni più specifiche per le sottodirectory.

Questa flessibilità aiuta a spiegare perché il formato si è diffuso. Un repository può utilizzare un singolo file Markdown semplice attraverso vari strumenti senza impegnarsi in un sistema di configurazione proprietario.

La proposta per il kernel usa una versione insolitamente prudente di questo modello. Non creerebbe un ampio manuale per agenti né ripeterebbe informazioni già mantenute altrove. Esporrebbe il README esistente con un nome che gli agenti probabilmente richiederanno.

Questo approccio preserva anche la parità tra le indicazioni per le persone e quelle per le macchine. Kees Cook ha affermato che il README è stato intenzionalmente progettato per funzionare anche con gli agenti. Collegarlo rafforza quindi quel percorso condiviso, invece di creare un insieme privato di regole che i contributori umani potrebbero non vedere mai.

Una fonte condivisa riduce la deriva delle policy. Se i maintainer aggiornano il README o il suo rimando alla guida sull'AI, gli agenti ricevono la modifica tramite il symlink. Un AGENTS.md copiato potrebbe invece diventare silenziosamente obsoleto.

Tuttavia, l'uso di un symlink introduce una considerazione di compatibilità. I sistemi Unix-like gestiscono naturalmente i symlink nei repository, ma alcune configurazioni Windows li estraggono come file ordinari. Un agente potrebbe quindi vedere la parola README anziché il contenuto a cui fa riferimento.

Questo non invalida la proposta, soprattutto per un progetto sviluppato principalmente attraverso consolidati flussi di lavoro Linux. Mostra però perché la patch debba essere valutata come infrastruttura, non come metadato magico.

Anche il comportamento degli strumenti varia. Alcuni agenti caricano automaticamente AGENTS.md, mentre altri preferiscono nomi di file specifici dello strumento o richiedono una configurazione esplicita. Un nome file dall'apparenza universale non garantisce un'acquisizione universale.

La patch migliora quindi il percorso più probabile per molti agenti senza eliminare le differenze tra strumenti. Il suo beneficio dipende dal client che segue il collegamento, rispetta le istruzioni e le preserva durante l'intera attività.

Queste condizioni sono più rigorose della semplice presenza di buona documentazione. Sono meno rigorose di un controllo tecnico applicabile in modo coercitivo.

Istruzioni Migliori Non Rendono Sicure le Patch Generate

AGENTS.md può migliorare la conformità, ma non può stabilire correttezza, provenienza o una reale revisione umana.

L'argomento più forte a favore della proposta è operativo. Gli agenti stanno già producendo patch relative al kernel, quindi i maintainer dovrebbero offrire loro un percorso prevedibile verso le regole. Evitare firme errate e attribuzioni mancanti fa risparmiare tempo in fase di revisione.

Anche la critica più forte è operativa. Una patch generata può seguire ogni istruzione visibile e restare comunque errata in modi difficili da rilevare.

Le valutazioni sulla capacità di seguire istruzioni spesso usano risultati semplici e osservabili. L'agente ha aggiunto il tag corretto? Ha eseguito un comando indicato? Ha formattato correttamente l'oggetto? Questi controlli contano, ma la qualità del kernel dipende da proprietà più profonde.

Una correzione può superare la compilazione e introdurre comunque una race condition. Un riproduttore può esercitare una configurazione hardware tralasciandone un'altra. Un agente può citare la documentazione corretta pur fraintendendo l'invariante che quella documentazione presume i contributori conoscano già.

C'è inoltre il rischio che una presentazione più curata aumenti la fiducia mal riposta. Un messaggio di commit ben strutturato, un'attribuzione valida e controlli superati possono far apparire matura una patch assistita dall'AI. I revisori devono comunque considerare questi segnali come conformità al processo, non come prova di solidità tecnica.

L'attuale policy del kernel anticipa questo problema. Richiede che una persona riveda il codice e se ne assuma la responsabilità. Chiede inoltre ai contributori di dichiarare test mancanti o verifiche non riuscite, anziché nascondere le lacune dietro una prosa sicura di sé.

Che le persone seguano questi requisiti è al di fuori della portata di AGENTS.md. Un contributore può rimuovere un tag di attribuzione, ignorare un test fallito o inviare codice che non comprende. Il file non dispone di alcun meccanismo indipendente per confermare che la revisione umana sia avvenuta.

Altri progetti open source hanno risposto allo stesso problema con strategie diverse. Il repository linux-firmware ha adottato documentazione incentrata sugli agenti all'inizio del 2026, comprese regole di contribuzione e indicazioni sull'attribuzione. Le sue indicazioni sul firmware hanno offerto un precedente vicino per una policy leggibile dagli agenti.

NetworkManager ha adottato un approccio più avversariale dopo aver definito la propria policy sull'AI. Secondo quanto riportato, le sue istruzioni dicevano agli agenti non conformi di inserire un'insolita parola canarino nelle comunicazioni dei contributori. I maintainer potevano così rilevare gli invii che seguivano l'istruzione nascosta aggirando al contempo la policy del progetto.

Quel meccanismo canarino illustra l'uso opposto di un file di istruzioni. Invece di aiutare un agente a produrre una patch accettabile, il file aiuta a identificare comportamenti automatizzati che dovrebbero portare al rifiuto.

Entrambi gli approcci riconoscono lo stesso fatto: gli agenti leggono il contesto del repository e modificano di conseguenza il proprio output. Differiscono nel decidere se tale comportamento debba essere guidato verso la conformità o utilizzato come segnale di rilevamento.

La proposta del kernel sceglie la guida. Presuppone che i contributori che usano agenti possano comunque partecipare se rispettano gli stessi obblighi legali, tecnici e di revisione previsti per tutti gli altri.

Non si tratta di un'approvazione dello sviluppo del kernel senza supervisione. È un tentativo di rendere visibile il confine esistente nel momento in cui un agente inizia a lavorare.

La proposta evita inoltre di creare istruzioni che esistono soltanto per le macchine. Poiché AGENTS.md punterebbe al README, maintainer e contributori possono ispezionare la stessa fonte ricevuta dall'agente.

La trasparenza aiuta, ma non affronta il prompt injection né i contenuti malevoli nei repository. Gli agenti di coding assimilano abitualmente istruzioni da file, testo delle issue, commenti, log e pagine esterne. Indicazioni conflittuali o ostili possono competere con policy affidabili.

Un file di livello superiore può stabilire una priorità per gli strumenti cooperativi. Non può garantire che ogni strumento applichi correttamente tale priorità, soprattutto quando l'agente legge file più in profondità contenenti linguaggio contraddittorio.

Esiste anche un rischio di manutenzione correlato. Qualsiasi guida del repository può diventare obsoleta con il cambiare dei flussi di lavoro. Il symlink proposto limita la duplicazione, ma i documenti collegati necessitano comunque di una revisione attiva.

La scala del kernel rende questa manutenzione particolarmente importante. Istruzioni generalmente corrette possono comunque risultare incomplete per un particolare sottosistema. Agenti e contributori devono continuare a consultare documentazione locale, maintainer, sistemi di build e infrastrutture di test.

La visione equilibrata non è dunque né “AGENTS.md risolve il codice AI” né “il file è privo di significato”. Può ridurre una specifica categoria di errori prevedibili lasciando intatto il lavoro di verifica più difficile.

Questa affermazione modesta è sostenuta dall'esempio di Levin. Qualsiasi conclusione più ampia attende prove provenienti da contributi reali attraverso sottosistemi e strumenti diversi.

Ciò Che Accadrà Dopo Conterà Più del Symlink

La proposta dovrebbe essere giudicata dagli esiti delle revisioni, dal comportamento degli agenti e dal carico di lavoro dei maintainer dopo l'adozione.

Il primo segnale è l'esito della patch. Un riconoscimento sostiene il design, ma la modifica deve comunque attraversare il processo di documentazione del kernel e raggiungere il repository principale prima di diventare infrastruttura standard del progetto.

I revisori potrebbero accettare il symlink senza modifiche, richiedere un file normale, chiedere adeguamenti di compatibilità oppure decidere che il percorso tramite README è insufficiente. Ogni risultato chiarirebbe come il kernel desidera esporre le regole agli strumenti automatizzati.

Il secondo segnale è se i principali agenti di coding seguono il collegamento in modo coerente. Il confronto tra due agenti di Levin è utile ma limitato. Test più ampi dovrebbero coprire strumenti, prompt, directory di lavoro e tipi di contributo diversi.

Un'implementazione riuscita produrrebbe meno firme generate, tag Assisted-by più coerenti, oggetti di commit migliori e una dichiarazione più chiara del lavoro non testato. Si tratta di miglioramenti del processo osservabili.

Il fallimento avrebbe un aspetto diverso. Gli agenti potrebbero ignorare il symlink, leggere solo una parte del materiale collegato o seguire regole generiche senza cogliere requisiti specifici del sottosistema. I file di istruzioni specifici dello strumento potrebbero restare necessari.

Il terzo segnale, e il più importante, è il carico di lavoro dei maintainer. Se il file riduce le correzioni ripetitive senza aumentare gli invii di bassa qualità, avrà svolto uno scopo pratico.

Se un output degli agenti più rifinito incoraggia più contributori a inviare patch che non sanno spiegare, il collegamento potrebbe migliorare la presentazione aggravando al contempo il carico di revisione. Questo risultato indebolirebbe la scommessa alla base della proposta.

I maintainer dovrebbero anche osservare se i contributori usano l'attribuzione in modo onesto. La convenzione Assisted-by ha valore solo quando le persone la preservano. La conformità automatizzata durante la generazione non può impedire a qualcuno di modificare il commit prima dell'invio.

Anche i progetti oltre Linux studieranno il risultato. Il kernel è una delle codebase collaborative più visibili ed esigenti, quindi il suo trattamento delle istruzioni per agenti ha un peso simbolico anche quando la patch è tecnicamente minuscola.

Questa influenza non dovrebbe essere confusa con una policy universale. Repository più piccoli, team commerciali e progetti con profili di rischio differenti possono scegliere file di istruzioni più completi, configurazioni specifiche dello strumento, controlli automatizzati o divieti su determinati contributi generati.

L'approccio del kernel è degno di nota perché non costruisce un processo di sviluppo parallelo. Riporta gli agenti verso il processo che già governa le persone.

Per i team di ingegneria, la lezione immediata è separare la reperibilità dall'autorità. Il contesto leggibile dagli agenti può identificare i comandi e i vincoli corretti. Test, revisioni, responsabilità e sistemi di approvazione devono comunque far rispettare il lavoro.

I team che documentano questi confini possono anche mantenere il contesto tecnico ricercabile attraverso una base di conoscenza ingegneristica. La chiave è esporre una fonte mantenuta invece di copiare le regole in più file per agenti.

Nei prossimi mesi, osservate la cronologia della patch, gli invii reali assistiti dall'AI e le risposte dei maintainer. Questi segnali mostreranno se la guida AGENTS.md del kernel Linux elimina rumore evitabile o standardizza semplicemente il modo in cui quel rumore arriva.

I maintainer dei repository dovrebbero porsi una domanda altrettanto concreta: quale errore ripetuto degli agenti deriva da contesto mancante e quale richiede un controllo applicabile in modo coercitivo? Inserite indicazioni stabili dove gli strumenti le troveranno, quindi misurate se il comportamento cambia. Lasciate alla revisione umana la responsabilità di tutto ciò che un file Markdown non può dimostrare.