CODENS: Transforming Code Changes into Living, Accessible, and Queryable Documentation
CODENS è un sistema che trasforma le pull request in documentazione vivente e interrogabile costruendo incrementalmente un grafo della conoscenza del software tipizzato per abilitare il question answering a livello di repository guidato da agenti, come dimostrato dalla sua riuscita valutazione su un progetto Ruby on Rails in produzione.
Articolo originale sotto licenza CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). Questa è una spiegazione generata dall'IA dell'articolo qui sotto. Non è stata scritta né approvata dagli autori. Per precisione tecnica, consulta l'articolo originale. Leggi il disclaimer completo
Immagina di camminare attraverso una biblioteca enorme e antica dove i libri vengono costantemente riscitti. Ogni volta che viene aggiunto un nuovo capitolo, una nota viene scritta a margine o una pagina viene strappata e sostituita, la storia cambia. Nel mondo del software, questa biblioteca è il "codice sorgente" (codebase), e le note sono le "pull request"—i biglietti digitali che gli sviluppatori usano per proporre modifiche. Il problema è che la "storia" di come funziona il software (la sua documentazione) spesso si perde nel caos di questi cambiamenti. Gli sviluppatori finiscono per tirare a indovinare come le cose si incastrino perché le istruzioni sono sparse tra migliaia di file e vecchi log di chat.
Per risolvere questo problema, gli scienziati hanno iniziato a costruire dei "knowledge graph" (grafi della conoscenza). Immaginali non come un semplice elenco di fatti, ma come una mappa gigante e vivente dove ogni pezzo di codice è una città e le connessioni tra essi sono strade. Se cambi una città, la mappa aggiorna automaticamente le strade che portano a essa. Un'altra idea chiave è la "Retrieval-Augmented Generation" (RAG), che è come dare a un bibliotecario super intelligente un set specifico di libri da leggere prima di rispondere alla tua domanda, assicurandosi che non si limiti a indovinare, ma trovi effettivamente la verità nel testo. La grande domanda che i ricercatori si pongono è: possiamo costruire una mappa che non mostri solo la biblioteca così com'è oggi, ma che ricordi ogni singolo cambiamento mai effettuato, trasformando la storia degli aggiornamenti del codice in una guida viva e ricercabile?
Entra in scena CODENS, un nuovo sistema progettato per fare esattamente questo. Immagina CODENS come un archivista magico e iper-organizzato che sorveglia un progetto software come una piattaforma web Ruby on Rails. Invece di leggere solo la versione finale del codice, CODENS osserva il "film" della storia del progetto. Inizia scansionando l'intero codice sorgente per costruire una mappa scheletrica, identificando 1.739 diverse "stanze" (come controller, modelli e view) basandosi sulle regole standard del framework.
Poi, avviene la magia. CODENS riproduce la storia del progetto, una pull request alla volta, come se guardasse un video in time-lapse della costruzione di un edificio. Per ogni modifica, non si limita a guardare i nuovi mattoni; chiede a un'intelligenza artificiale potente (un LLM) di spiegare perché la modifica è stata fatta e come si inserisce con ciò che era già presente. Fondamentalmente, non si limita a sovrascrivere la vecchia storia; fonde i nuovi dettagli con quelli vecchi. Se uno sviluppatore aggiunge un nuovo pulsante a una pagina, CODENS aggiorna la mappa per mostrare che il pulsante esiste, ma conserva anche la storia di come appariva la pagina prima. Questo crea uno strato di "documentazione vivente" che diventa più intelligente e dettagliato con ogni singolo aggiornamento.
Una volta costruita questa mappa, CODENS offre tre modi per esplorarla, come diversi modi di viaggiare. Puoi effettuare una rapida "ricerca vettoriale", che è come chiedere al bibliotecario libri con parole simili. Puoi fare una "recupero multi-hop" (multi-hop retrieval), che è come seguire una scia di briciole di pane da una stanza all'altra per vedere come sono collegate. Ma la modalità più potente è la "navigazione guidata da agenti" (agent-guided traversal). Qui, un agente IA agisce come un detective con una torcia. Non segue un percorso fisso; decide quali porte aprire, quali strade prendere e scrive persino le proprie query personalizzate per trovare la risposta esatta. Utilizza strumenti per sbirciare dentro nodi specifici, controllare i loro vicini o eseguire ricerche complesse per comporre una risposta completa.
I ricercatori hanno testato questo sistema su un progetto reale, di livello industriale, con oltre 1.700 file e centinaia di pull request. Hanno posto al sistema 11 domande diverse che un vero sviluppatore potrebbe avere, come "Come funziona questa funzionalità?" o "Cosa succede quando clicco questo pulsante?". I risultati sono stati promettenti. Il sistema ha ottenuto punteggi molto alti in termini di accuratezza e "fedeltà" (faithfulness), il che significa che le risposte erano basate sul codice effettivo e non inventavano nulla. Su una scala da 1 a 5, gli esperti umani hanno valutato la rilevanza delle risposte con una media di 4,09 e la completezza con 4,45. Il sistema è stato inoltre in grado di tracciare il costo e il tempo di ogni query, mostrando che, sebbene la modalità detective (agente) richiedesse più tempo e token, forniva le risposte più approfondite.
Tuttove, il documento evidenzia anche un piccolo intoppo. Sebbene il sistema fosse eccellente nel trovare le informazioni giuste, il modo in cui presentava le risposte risultava talvolta un po' troppo tecnico. I revisori umani hanno notato che alcune risposte erano "troppo dettagliate" o "troppo incentrate sul codice", elencando citazioni riga per riga quando un riassunto più semplice sarebbe stato preferibile. È come se il bibliotecario vi avesse dato il numero esatto della pagina e del paragrafo di un libro, ma non vi avesse riassunto la storia. Gli autori suggeriscono che il passo successivo non sia necessariamente trovare informazioni migliori, ma insegnare al sistema come sintetizzare tali informazioni in spiegazioni più chiare e accessibili agli utenti.
In breve, CODENS suggerisce che possiamo trasformare la storia disordinata e frammentata dei cambiamenti del codice in una memoria strutturata e interrogabile per il software. Dimostra che, trattando le pull request come un flusso continuo di conoscenza piuttosto che come semplici correzioni temporanee, possiamo costruire un sistema che aiuti a comprendere basi di codice complesse molto più velocemente. Sebbene non sia ancora un problema risolto perfettamente — specialmente per quanto riguarda il rendere le risposte più simili a quelle di un essere umano utile e meno a quelle di un robot che legge un manuale — offre uno sguardo vivido su un futuro in cui la documentazione del software è viva, aggiornata e sempre pronta a rispondere alle vostre domande.
Sommerso dagli articoli nel tuo campo?
Ricevi digest giornalieri degli articoli più recenti corrispondenti alle tue parole chiave di ricerca — con riassunti tecnici, nella tua lingua.