CodeDNA: il protocollo che fa parlare gli agenti AI nel codice

Ogni volta che un agente AI apre un file di codice, parte da zero. Non sa chi lo ha scritto prima, quali funzioni esporta, quali vincoli rispettare, quali altri file dipendono da lui. È come entrare in un cantiere senza progetto, ogni singola volta. CodeDNA risolve questo problema alla radice: invece di costruire un database esterno o un sistema di retrieval, inserisce la conoscenza direttamente nel codice.

Il problema: la conoscenza muore tra una sessione e l'altra

Immagina tre agenti AI che lavorano sullo stesso progetto:

Agente A corregge un bug in utils.py. Scopre che la funzione get_invoices() restituisce TUTTI i tenant, e il chiamante deve filtrare quelli sospesi. Lo capisce, lo fa, ma non scrive da nessuna parte questa regola. Chiude la sessione.

Agente B apre lo stesso file una settimana dopo. Passa 20 minuti a ri-scoprire lo stesso vincolo — tempo e token buttati.

Agente C aggiunge una nuova feature. Chiama get_invoices() senza filtrare. Il bug rientra dalla finestra.

Questo è il problema che CodeDNA risolve: la conoscenza rimane nel file, non nella testa dell'agente che l'ha scoperta.

Come funziona: quattro livelli di annotazione

CodeDNA funziona come uno zoom: dal progetto intero fino al singolo blocco di codice. Ogni livello aggiunge contesto per l'agente successivo.

Ogni campo ha un ruolo preciso:

• exports: — le funzioni pubbliche. L'agente sa cosa può usare senza leggere tutto il file.
• used_by: — chi dipende da questo file. Se cambi qualcosa, sai esattamente cosa potrebbe rompersi. Il tag [cascade] indica dipendenze da aggiornare obbligatoriamente.
• related: — dipendenze semantiche: file che condividono la stessa logica ma senza importarsi a vicenda. Su un bug cross-cutting Django (#11532, 5 file scollegati), il solo used_by trova 2 file su 5. Con related: si arriva a 5 su 5 — dal 40% al 100% di F1.
• rules: — vincoli rigidi. Non "gestisci gli errori", ma "amount è in centesimi, dividi per 100". Specifiche e azionabili.
• message: — chat tra agenti. Un'osservazione ancora incerta che il prossimo agente può confermare (promuovendola a rules) o smentire.

I benchmark: non è un'opinione

CodeDNA non è solo un'idea elegante. I risultati su SWE-bench, il benchmark standard per la risoluzione di bug via AI, sono solidi e riproducibili.

Il dato più impressionante non è solo la media più alta, ma la stabilità. Su 10 task DeepSeek, CodeDNA ha ridotto la varianza quasi a zero: su due task lo scarto quadratico medio è stato 0.00 (stesso risultato ogni volta), mentre senza annotazioni oscillava tra 0.20 e 0.25. L'agente con CodeDNA lavora per comprensione strutturale, non per fortuna.

I benchmark sono stati eseguiti su 5 modelli diversi (DeepSeek Chat, Gemini 2.5 Flash, Gemini 2.5 Pro, GPT-5.3 Codex, GPT-4o), con 4 su 5 che migliorano significativamente. La suite di test conta 204 test in CI e i risultati sono interamente riproducibili: 6 task su 10 sono stati replicati in modo indipendente da @fabioscialanga su una macchina diversa con lo stesso protocollo. I dati grezzi di benchmark sono convertibili in dataset di training SFT/DPO/PRM per addestrare modelli a seguire il protocollo.

"CodeDNA annotations are not just documentation — they are a coordination protocol. No orchestrator needed. No shared memory. The code is the channel." — dal paper del progetto

Multi-agente: il codice come unico canale di comunicazione

L'esperimento più affascinante è quello con 5 agenti DeepSeek R1 che costruiscono un'app SaaS completa in 83 minuti. Senza alcuna istruzione esplicita, gli agenti hanno iniziato spontaneamente a usare i campi message: in tre modi:

• Backlog — "ho costruito questo, ma manca ancora X"
• Risk flag — "funziona, ma non ho potuto verificare il refresh token"
• Architettura — "in produzione, usa una materialized view per i crediti"

Il team senza CodeDNA ha avuto un fallimento critico: un agente ha iniziato con Flask, l'altro è passato a FastAPI. Entrambi i framework sono finiti nel codice simultaneamente. Con CodeDNA, il campo rules: su main.py ("must register all routers before returning app") ha bloccato la scelta architetturale fin dal primo agente.

Git Trailers: audit e tracciabilità per agenti AI

CodeDNA introduce un sistema di audit completo basato su git trailer — lo stesso standard usato da GitHub per i Co-Authored-By. Ogni commit prodotto da una sessione AI include metadati strutturati:

Il campo AI-Visited è l'innovazione chiave: git traccia già i file modificati (il diff), ma AI-Visited aggiunge i file letti durante la sessione — la traccia di navigazione dell'agente. Con un semplice git log --grep="AI-Agent:" si può ricostruire l'intera cronologia di tutte le sessioni AI, filtrate per modello, provider o file.

L'architettura è a tre livelli: git log (trailer AI, autoritativo e immutabile) → .codedna (ultime N sessioni, sommario leggero per navigazione) → campo agent: nei file (one-liner per file, sliding-window). Tutti e tre sono collegati dallo stesso session_id. È in sviluppo un'estensione VSCode che mostrerà CodeLens inline con l'ultimo agente AI per ogni funzione, mappe di calore delle sessioni e una Agent Timeline completa.

L'ecosistema: 9 linguaggi, 7 template engine, plugin per ogni IDE

CodeDNA supporta nativamente Python, PHP, TypeScript, Go, Java, Kotlin, Ruby, Rust e C#, più 7 template engine (Blade, Jinja2, ERB, Handlebars, Razor, Vue SFC, Svelte). Il formato si adatta automaticamente al linguaggio: docstring in Python, commenti // in PHP/TS/Go, {{-- --}} in Blade.

L'installazione avviene con un solo comando:

Per chi usa Claude Code, Cursor, Copilot, Cline, OpenCode o Windsurf, esistono plugin e hook di integrazione che caricano automaticamente il protocollo. Il progetto è su GitHub con 144 stelle, 329 commit e 21 fork.

CodeDNA Wiki: la wiki semantica ispirata a Karpathy

Oltre alle annotazioni per-file, CodeDNA introduce un livello wiki semantico che colma il divario tra la verità strutturale di ogni singolo file e la visione d'insieme che nessun file può contenere da solo.

L'ispirazione arriva da Andrej Karpathy, ex Director of AI di Tesla e co-fondatore di OpenAI, e dal suo pattern LLM-wiki: una wiki generata e mantenuta da modelli linguistici che non è un dump automatico di tutti i file, ma un modello semantico — una mappa concettuale del progetto scritta per essere letta da altri LLM. Come dice Karpathy: "la wiki è un modello semantico, non un dump di file."

CodeDNA implementa questo concetto con il campo wiki: — un puntatore opzionale nel docstring che indica quali file meritano una pagina wiki dedicata:

Due comandi completano il sistema:

• codedna wiki bootstrap — genera un vault Obsidian per-file con [[wikilinks]] tracciati dai grafi used_by: e related:. Ogni file con una pagina wiki diventa un nodo navigabile in un grafo della conoscenza.
• codedna wiki sync — rigenera un documento narrativo di 7 sezioni (docs/codedna-wiki.md) che descrive l'architettura del progetto, i flussi operativi, gli hotspot e i rischi di deriva. Aggiornabile automaticamente via git post-commit hook.

La presenza del campo wiki: è essa stessa un segnale: quando un agente lo vede, sa che un agente precedente ha deciso che quel file merita un contesto esteso oltre al docstring — e leggere la pagina wiki prima di modificare il file è probabile che prevenga bug. L'assenza del campo è altrettanto informativa: il docstring è sufficiente, non serve cacciare una pagina che non esiste.

"CodeDNA fornisce la verità strutturale, per file; il pattern LLM-wiki di Karpathy fornisce la visione semantica dall'alto che nessun singolo file può contenere. Il campo wiki: li unisce come un ponte." — dalla specifica v0.9