Blog di Maguyva

Un contesto che ti segue

Mon, 07 Sep 2026 00:00:00 GMT

L’indexer di Cursor è eccellente dentro Cursor. Il completamento automatico, la modifica inline, la chat, e l’agente in quella finestra si appoggiano già su un indice di progetto che Cursor gestisce per lo spazio di lavoro aperto. Se Cursor è l’unica superficie in cui scrivi, e quell’indice trova già i file giusti, resta lì. È il caso onesto del ‘resta dove sei’, e giustamente apre questo articolo.

Questo articolo parla dell’altra metà di una settimana comune. Lo stesso repository viene anche aperto in Claude Code, interrogato da Codex CLI, revisionato su una seconda macchina, o interrogato da un agente in esecuzione in CI. La domanda non è ‘quale indexer è migliore’. La domanda è se la mappa di cui l’agente si fida in una finestra è la stessa mappa di cui si fida nella successiva.

Maguyva è quella mappa che ti segue. È un livello di contesto della codebase MCP remoto. L’agente lo interroga nello stesso modo in cui interroga qualsiasi altro strumento MCP. I risultati tornano come percorsi classificati con numeri di riga. Cursor resta l’editor. È il contesto a muoversi.

A cosa serve l’indexer di Cursor

L’indicizzazione integrata di Cursor esiste affinché chat, agente e ricerca dentro l’editor possano recuperare codice pertinente invece di affidarsi solo a ciò che entra nella finestra di contesto grezza del modello. È il design giusto per un IDE. Questo indice è nativo di Cursor. Non è un server MCP e non è raggiungibile da nessun altro client.

Ecco come funziona, come descritto nella documentazione pubblica di Cursor e nel racconto dello stesso Cursor al momento della stesura: il percorso di ricerca principale non è più un indice di embedding nel cloud. Il team di Cursor ha dichiarato sul proprio forum della community che la ricerca semantica/basata su embedding dedicata viene progressivamente ridotta a favore di un recupero basato su grep, perché i modelli attuali esplorano già abbastanza bene un albero vivo da soli. Al suo posto c’è Instant Grep, un indice di ricerca locale costruito con n-grammi, liste invertite e filtri di Bloom, mantenuto in una tabella di lookup mappata in memoria, così le query vengono risolte sulla macchina stessa dello sviluppatore invece che su un server.

L’indice stesso vive dentro la directory .git/cursor/ propria del repository, ancorato a un commit git specifico; le modifiche successive a quel commit si sovrappongono ad esso invece di innescare una nuova scansione, e l’indice viene ricostruito solo quando lo stato locale si è discostato molto da ciò su cui è stato costruito. Poiché si trova dentro .git, non viene mai tracciato né pushato — cancella la cartella, e l’indice sparisce. .gitignore viene rispettato per costruzione, dato che solo il contenuto tracciato da git è idoneo, e .cursorignore viene fatto rispettare sul percorso di lettura. Non c’è più alcun passaggio di embedding lato server né un database vettoriale remoto su quel percorso. La documentazione precedente descriveva un design assistito dal cloud — cifratura dei chunk, sincronizzazione tramite albero di Merkle, riutilizzo dell’indice tra membri del team — e lo stesso team di Cursor ha da allora dichiarato che quel design viene ridotto, quindi questo testo non lo descrive più come attuale.

Un punto di forza notevole dentro l’editor è il subagente Explore di Cursor. Può avviare più ricerche parallele nella propria finestra di contesto su un modello più veloce e restituire solo i risultati rilevanti, così la conversazione principale non si gonfia di risultati di ricerca. È un vero punto di forza interno all’editor. Mantienilo.

Gli spazi di lavoro multi-root sono supportati: il contesto di ogni cartella aperta è disponibile per l’Agent. Alcune funzionalità dipendenti da git, come i worktree, sono disabilitate nelle configurazioni multi-root, e i Cloud Agents non supportano affatto gli spazi di lavoro multi-root.

Niente di tutto questo è un motivo per lasciare Cursor. È una descrizione precisa di una mappa che è eccellente là dove vive.

Cosa significa davvero ‘seguirti’

Una mappa ti segue quando le stesse domande restituiscono lo stesso tipo di risposta, con citazioni che puoi aprire, da più di un client.

In Cursor: ‘Dove è definito parseConfig, e chi lo chiama?’
In Claude Code, sullo stesso repository: la stessa domanda.
In Codex CLI, su una macchina di revisione che non ha mai aperto la finestra di Cursor: la stessa domanda.
In un agente CI che parla MCP: la stessa domanda, contro lo stesso snapshot ospitato.

Se ogni superficie costruisce il proprio indice privato, non hai una mappa. Hai diverse cache che divergono. L’indice dell’editor può essere aggiornato per l’albero su disco. La sessione CLI può essere indietro di un giorno. Il job CI può guardare un checkout diverso. E l’agente continuerà comunque a suonare sicuro di sé.

L’indexer di Cursor non deve risolvere questo. Poiché vive dentro l’editor, il contesto che costruisce è per quell’editor. Un lettore che ha bisogno anche di una CLI, di una pipeline CI, o di un editor diverso, ha bisogno di uno strumento separato per quelle superfici. È un fatto di ambito, non un difetto. Maguyva è quello strumento separato.

Un numero di lingue pubblicato per l’indexer di Cursor non è indicato nei materiali che questo testo può usare. Maguyva pubblica supporto per oltre 279 lingue e tecnologie basate su testo. Anche i prezzi di Cursor non vengono riportati qui; vedi la loro pagina prezzi. Maguyva addebita per spazio di lavoro, non per posto, con piani pubblicati a $0, $19, $49 e $149 a seconda dell’estensione indicizzata e della dimensione dello spazio di lavoro.

Una mappa ospitata, ogni client MCP

Maguyva è un server MCP remoto. Colleghi GitHub, scegli i repository, e la pipeline cloud costruisce simboli, archi del grafo e una mappa classificata. Aggiungi una chiave API alla configurazione MCP del client che già usi. Maguyva ha guide di configurazione per 24 client MCP documentati — incluso Cursor — e può connettersi ad altri client compatibili con MCP che supportano la configurazione standard.

La pagina di configurazione di Cursor è il percorso specifico per l’editor se è lì che lavori. Lo stesso server risponde a Claude Code, VS Code, Windsurf, Codex CLI e agli altri. Non cambi editor. Dai a ogni agente la stessa superficie di strumenti: 11 strumenti MCP rivolti al cliente per ricerca, simboli, analisi delle dipendenze, recupero file, contesto del repository e workflow di utilità deterministici. Ricerca semantica, strutturale, a grafo e testuale vengono fuse in risultati classificati.

Questo è il vantaggio della portabilità. Le citazioni che hai verificato in Cursor stamattina hanno la stessa forma delle citazioni che Codex CLI restituirà stasera. Percorso del file e numero di riga. Aprili. Se sono sbagliate, lo vedi. Se sono corrette, la modifica successiva ha dove atterrare. L’affermazione approvata è meno modifiche allucinate, non la promessa che ogni modifica sia corretta.

L’aggiornamento è pubblicato. Gli snapshot hanno un timestamp, così l’agente sa quale versione dell’albero sta leggendo. La cadenza di ricostruzione è giornaliera nel piano gratuito e oraria nei piani a pagamento. Il limite onesto è il lavoro locale non sincronizzato: una modifica che esiste solo in un working tree non è ancora nella mappa ospitata. Questo limite è lo stesso indipendentemente dal client da cui interroghi, ed è proprio questo il punto. La deriva tra client non è più un secondo limite nascosto.

La documentazione fornisce il ciclo di attivazione che si applica a ogni client: indicizza un repository che già conosci, collega il client, fai una domanda che puoi verificare. Fallo una volta in Cursor. Rifallo dalla CLI che usi davvero nei giorni di revisione. Se entrambe le risposte citano lo stesso handler, la mappa ti ha davvero seguito.

Come le due mappe convivono

Usale entrambe. Non sono alternative nel senso di una pagina di confronto.

Tieni acceso l’indexer di Cursor per il progetto su disco. Lascia che Explore, Instant Grep e l’agente dentro l’editor lo usino. Quel ciclo è nativo e veloce.
Aggiungi Maguyva come server MCP in Cursor, così la stessa sessione può anche interrogare la mappa ospitata dello spazio di lavoro. Cursor è un client Maguyva documentato. Non stai scegliendo un indice cancellando l’altro.
Aggiungi lo stesso server Maguyva a Claude Code, Codex CLI, o qualsiasi altro client MCP che tocca il repository. Un’unica forma di chiave API. Un unico spazio di lavoro.
Se un agente CI è compatibile con MCP, puntalo allo stesso server. Leggerà lo stesso snapshot con timestamp che ha letto il laptop.

L’indice dell’editor resta lo strumento migliore per ‘cosa c’è su disco in questa finestra, proprio ora’. La mappa ospitata è lo strumento migliore per ‘come appare questo spazio di lavoro a ogni agente che lo toccherà oggi’. Queste frasi non competono.

Le quote dello spazio di lavoro sono pubblicate sulla pagina prezzi: repository, righe indicizzate e utenti, fatturati per spazio di lavoro. Agenti e umani condividono lo stesso conteggio di utenti. Inizia gratis con un repository che sai già valutare. Aumenta lo spazio di lavoro solo dopo che le citazioni sopravvivono al contatto con l’albero.

Cosa non afferma questa pagina

Non afferma che l’indexer di Cursor sia debole, incompleto, o un motivo per cambiare editor. La prima frase di questo testo dice il contrario.

Non afferma che Maguyva sostituisca Instant Grep o il subagente Explore. Sono funzionalità di Cursor. Restano in Cursor.

Non inventa un numero di lingue, una cifra di latenza, o un risparmio di token per nessuno dei due prodotti. I numeri sconosciuti restano non pubblicati.

Non finge che il lavoro locale non pushato sia nella mappa ospitata. Gli snapshot con timestamp rendono visibile quel limite. Non lo rimuovono.

Il test è ordinario. Indicizza un repository che già conosci. Fai una domanda che puoi verificare, prima in Cursor, poi in un secondo client MCP. Un contesto che ti segue è la stessa citazione in entrambi i luoghi.

// same map, wherever you opened it.

Prima la mappa, poi la revisione

Mon, 07 Sep 2026 00:00:00 GMT

Due lavori diversi si trovano ai due lati di una pull request. Prima che l’agente scriva, ha bisogno di una mappa dell’albero che sta per cambiare. Dopo che l’agente apre una PR, qualcosa dovrebbe leggere quella modifica contro il resto del sistema e lasciare commenti su cui un umano può agire.

Questi lavori sembrano simili da lontano perché entrambi coinvolgono ‘capire la codebase’. Non sono lo stesso prodotto. Uno risponde a ‘dove dovrebbe atterrare questa modifica?’. L’altro risponde a ‘cosa ha rotto questo diff che un linter riga per riga si perderà?’. Confonderli produce una prima bozza peggiore e una revisione più rumorosa.

Questo articolo è una guida a un workflow congiunto. Maguyva è la mappa che l’agente interroga per primo. Greptile è l’agente di revisione che commenta la PR dopo. La coppia è complementare per costruzione: Maguyva non revisiona pull request, e Greptile non sostituisce il livello di contesto che l’agente ha usato per scriverle.

Perché questa suddivisione è utile

Un agente di coding che parte da priori di addestramento più qualche file incollato inventerà un percorso plausibile e lo modificherà. Questo è il fallimento del ‘file sbagliato’, ed è un problema di recupero. Maguyva è un livello di contesto della codebase MCP remoto: recupero semantico, strutturale (AST), a grafo/dipendenze e testuale fuso in risultati classificati, più ricerca di simboli e recupero di file. Le risposte fondate tornano come path/file.ext:line, così puoi rifiutare un errore prima che esista una patch. L’affermazione resta modesta: meno modifiche allucinate. Il modello può ancora indovinare. È solo che il primo passo smette di essere un’indovinello.

Greptile è un agente di revisione del codice basato su AI. Nelle loro stesse parole, revisiona automaticamente ogni pull request con comprensione completa della codebase, e lo contrappone ai linter tradizionali che controllano i file isolatamente invece che l’intero sistema. La configurazione consiste nell’installare l’app GitHub o GitLab e selezionare i repository. Non c’è nessun indice locale da gestire. L’hosting è Greptile Cloud (dichiarano conformità SOC 2 Type II, con un report disponibile su richiesta), con un’opzione self-hosted offerta alle aziende.

Il loro flusso numerato è: connettersi e costruire un grafo delle dipendenze di ogni funzione, classe e dipendenza; a ogni pull request, analizzare la modifica usando quel grafo completo del repository e pubblicare i risultati come commenti PR con correzioni suggerite, in circa tre minuti; ogni commento può passare il problema a un agente di coding che il team già usa. Dichiarano anche di leggere nel tempo i commenti umani precedenti sulle PR, per imparare gli standard di codice di un team e ridurre i suggerimenti rumorosi. Il loro sistema di apprendimento, secondo quanto dichiarano, ha bisogno di 2-3 settimane per adattarsi.

Questa è revisione, non stesura. Il punto di forza di Greptile è il contesto del grafo completo del repository sulla modifica già atterrata in una PR, seguito da un ciclo chiuso che invia il risultato a Claude Code, Codex, Conductor, Cursor, o Devin. Il punto di forza di Maguyva è la mappa classificata che l’agente ha interrogato prima che quella modifica venisse scritta. Usali entrambi. Non chiedere a nessuno dei due di fare il lavoro dell’altro.

Un’integrazione di prodotto di prima parte tra Maguyva e Greptile non è dichiarata. Non ti serve neanche. Maguyva parla con l’agente via MCP. Greptile parla con GitHub o GitLab tramite la propria app. Si incontrano alla pull request. Nessuno script collante, nessun cron che collega uno strumento all’altro. La coppia fa a meno di bash perché ogni prodotto sta già sulla superficie che gli appartiene.

Cosa non è questo

Questa non è una demolizione di Greptile. Non è una pagina ‘cambia revisore’. Greptile è stato lanciato su Hacker News il 5 marzo 2024 come azienda Y Combinator W24, e quel thread è come molte persone hanno conosciuto per la prima volta il prodotto. Se è così che li hai trovati, continua a usarli. Questa pagina è la metà anteriore mancante di quel ciclo: fondare l’agente in anticipo, così che la PR vista da Greptile miri già ai file giusti.

I materiali di marketing di Greptile guidano con affermazioni su velocità di revisione e cattura di bug. Trattale come affermazioni proprie di Greptile, non come numeri verificati in modo indipendente. Questo testo non le ripete come fatti.

La copertura linguistica è lo stesso tipo di onestà. Greptile inquadra il supporto come copertura di tutti i linguaggi di programmazione invece che come un elenco enumerato; un numero preciso non è indicato. Maguyva pubblica supporto per oltre 279 lingue e tecnologie basate su testo, con una suddivisione tecnica (AST supportato da parser contro solo testo) sul sito quando la domanda è tecnica. Sono prodotti diversi che fanno affermazioni diverse. Non mescolarle.

I prezzi di Greptile non sono indicati nei materiali che questo testo può usare. I piani a pagamento esistono; vedi la loro pagina prezzi. Maguyva addebita per spazio di lavoro, non per posto. I piani iniziano gratis. La pagina prezzi elenca i livelli pubblicati se ti servono i numeri dello spazio di lavoro.

Workflow

Tre fasi con un nome. Eseguile in questo ordine. Non saltarne nessuna la prima volta che provi la coppia.

1. Contesto Maguyva

Indicizza un repository che già conosci. Collega il client MCP in cui già scrivi — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, o un altro client compatibile con MCP. Maguyva ha guide di configurazione per 24 client MCP documentati e può connettersi ad altri client che supportano la configurazione MCP standard.

Fai una domanda che puoi valutare prima che chiunque scriva una riga. ‘Dove viene gestita la scadenza della sessione, e cosa la chiama?’ è una prima mossa migliore di ‘sistema l’autenticazione’. Esigi citazioni. Apri i risultati file.ext:line. Segui il simbolo. Conferma la dipendenza che stai per toccare.

Maguyva espone 11 strumenti MCP rivolti al cliente per ricerca, simboli, analisi delle dipendenze, recupero file, contesto del repository e workflow di utilità deterministici. Quattro modalità di recupero vengono fuse in risultati classificati; find_symbol è uno strumento separato quando già conosci il nome. La documentazione descrive il percorso più breve: iniziare gratis, indicizzare un repository che già conosci, collegare il client, poi fare una domanda che puoi verificare.

Gli snapshot hanno un timestamp, così l’agente può dire quale versione dell’albero sta leggendo. Il limite onesto è il lavoro locale non sincronizzato. Se la modifica esiste solo in un working tree e non è stata pushata, la mappa ospitata ancora non la contiene. I file di istruzioni (CLAUDE.md, AGENTS.md) trovano ancora posto qui, per convenzioni e per ciò che non va toccato. Non sono una mappa viva. Usali per il comportamento. Usa Maguyva per i fatti.

Non lasciare che l’agente apra una PR prima che le citazioni sopravvivano al contatto con il repository. Quel cancello è tutto il senso di questa fase.

2. PR dell’agente

Lo stesso agente ora scrive la modifica nel client per cui già paghi. Maguyva non è un editor né un revisore. L’agente continua a produrre il diff. Tu continui ad aprire la pull request su GitHub o GitLab come già fai.

Ciò che dovrebbe essere diverso è il primo file. La PR dovrebbe nominare l’handler che implementa davvero il comportamento, il chiamante che si romperà, e il test che fallirà se la modifica è sbagliata. Se la fase 1 è stata saltata, la fase 3 spenderà i suoi commenti su una modifica atterrata nel pacchetto sbagliato. Greptile può comunque trovare problemi sistemici. Non dovrebbe anche doversi riprendere da un percorso allucinato.

Tieni la PR circoscritta. Un primo file fondato non è una licenza per riscrivere il modulo. Questa coppia complementare funziona quando l’agente ha fatto un lavoro con una mappa, e poi ha chiesto a un revisore di fare un altro lavoro su un diff delimitato.

3. Revisione Greptile

Greptile è già connesso al repository tramite l’app GitHub o GitLab. Sulla nuova pull request analizza la modifica usando il grafo completo del repository che ha costruito, e pubblica i risultati come commenti con correzioni suggerite. I loro materiali collocano questo passaggio a circa tre minuti.

Leggi i commenti come leggeresti un collega attento: apri la posizione citata, decidi se il risultato è reale, poi agisci. Dove Greptile offre ‘Fix with your Agent’, invia il problema — percorsi di file, numeri di riga, codice suggerito — a Claude Code, Codex, Conductor, Cursor, o Devin. ‘Fix All’ invia tutti i problemi della revisione in una volta. Forniscono anche un Greptile MCP e un plugin per Claude Code per quel passaggio. Maguyva non è su quella lista di destinazioni nominate; quell’assenza non è un problema. Maguyva ha già fatto il suo lavoro nella fase 1. L’agente di coding che ha scritto la PR è quello che dovrebbe ricevere il payload di correzione.

Aspettati rumore nelle prime 2-3 settimane mentre il sistema di apprendimento di Greptile si adatta ai commenti che il tuo team lascia davvero. Questo è il loro programma dichiarato, non un difetto della coppia. La revisione umana resta nel ciclo. Greptile è il primo passaggio automatizzato, non il pulsante di merge.

Se un commento di Greptile punta a un file che l’agente non ha mai interrogato nella fase 1, è un segnale utile. O la mappa ha perso un chiamante, o l’agente ha saltato una citazione. Correggi la bozza in base al commento. Non disattivare il revisore.

Come mantenere onesto questo complemento

Maguyva sempre prima. Una revisione di una PR con il file sbagliato resta comunque una revisione del file sbagliato.
Greptile sempre dopo. Una bozza ben citata ha comunque bisogno di una lettura del diff a livello dell’intero sistema.
Non chiedere a Maguyva di pubblicare commenti sulle PR. Non lo fa.
Non chiedere a Greptile di essere il primo livello di recupero dell’agente mentre sta ancora scegliendo un percorso. Non è il lavoro per cui è collegata la loro app GitHub o GitLab.
Non inventare una pipeline bash che li ‘sincronizza’. La PR è l’interfaccia.
Verifica entrambi i lati in modo indipendente. Indicizza un repository che già conosci. Fai una domanda che puoi verificare. Poi apri una piccola PR e leggi cosa commenta davvero Greptile.

Il ciclo è ordinario una volta che gli si dà un nome. Prima la mappa. Poi la PR dell’agente. Poi la revisione. Ogni prodotto resta sul lato della pull request in cui è bravo.

// map first. review second. in that order.

Dare a un agente AI il contesto di un repository grande senza un indexer locale

Fri, 14 Aug 2026 00:00:00 GMT

Un repository grande non entra in una finestra di contesto, e se hai mai puntato un indexer da laptop su un vero monorepo, sai che non entra comodamente nemmeno lì — la RAM schizza, la prima indicizzazione richiede un’ora, e il tuo agente inizia comunque la sessione successiva indovinando quali file contano.

La risposta abituale è eseguire un indexer accanto all’editor, e per un repository che entra comodamente in una macchina, è una buona risposta. Se il tuo monorepo si indicizza già velocemente in Cursor e quello è l’unico posto in cui ti serve la mappa, questo articolo non ha nulla da aggiungere — saltalo.

Questo articolo parla dell’altro caso — quando un agente ha bisogno di una mappa interrogabile di un repository grande, e non vuoi eseguire un indexer locale per ottenerla.

Quando un indexer locale è lo strumento sbagliato

Un indice locale presume che il codice viva sulla macchina che lo interroga, e alla scala di un vero monorepo questa presunzione si tende anche dentro un singolo editor. Il repository è semplicemente più grande di quanto tu voglia tenere ‘caldo’ su un laptop: lavori in un pacchetto mentre il raggio d’impatto si trova tre directory più in là, e una prima indicizzazione a freddo di un albero da due milioni di righe non è qualcosa che vuoi affrontare due volte — né sulla tua macchina, né su un runner CI che non ha mai clonato prima quell’albero. Oppure un collega dovrebbe poter interrogare la stessa mappa che usi tu, senza aspettare che la propria macchina si faccia strada attraverso lo stesso indice.

Niente di tutto questo è un motivo per buttare via un buon indexer dell’editor. È un motivo per avere anche una mappa ospitata che qualsiasi tuo agente può interrogare via MCP.

E il problema di scala va più a fondo di ‘troppi file da incollare’. Su un albero grande, la domanda interessante non è quasi mai ‘mostrami questo file’ — è quale file, quale simbolo, quali chiamanti, quali test. Un agente che inizia elencando src/ e leggendo i primi tre risultati mancherà allegramente l’handler in apps/api e il client generato in packages/sdk. Ciò di cui hai bisogno è un recupero costruito dall’intero albero, poi classificato, poi citato.

Cosa significa davvero ‘contesto di un repository grande’

Riversare file nel prompt non è contesto — è una copia più piccola e peggiore dell’albero. Ciò di cui il tuo agente ha davvero bisogno è porre domande e ricevere risposte citate: dove è definito questo simbolo e chi lo chiama, cosa dipende dal modulo che sto per cambiare, quale file di test copre questo comportamento, e come appare l’albero adesso, non lo scorso trimestre.

Queste risposte devono provenire da un indice costruito sul tuo repository, non dalla memoria del modello sui repository altrui, e l’indice deve vivere da qualche parte al di fuori della finestra di contesto dell’agente. Per questo problema, dovrebbe vivere anche da qualche parte al di fuori del tuo laptop.

Un’altra cosa che i file di istruzioni non possono fare per te: CLAUDE.md e AGENTS.md sono il posto giusto per convenzioni e comportamento, ma non sono una mappa viva, classificata, interrogabile di un albero da due milioni di righe. Usa le regole per il comportamento; usa l’intelligenza del repository per i fatti.

Costruiamo la mappa nel cloud, la interroghiamo da qualsiasi client

Maguyva è un livello di contesto della codebase MCP remoto. Colleghi GitHub, scegli i tuoi repository, e puoi andartene mentre le pipeline cloud analizzano l’albero, costruiscono simboli e archi del grafo, e mantengono una mappa classificata — mai un indexer locale.

Quando fai push del codice, i file modificati vengono analizzati in modo incrementale, e i livelli di grafo e ranking vengono ricostruiti secondo una pianificazione: giornaliera nel piano gratuito, oraria in quelli a pagamento. Ogni snapshot ha un timestamp, così il tuo agente può dire quale versione dell’albero sta leggendo. Il limite onesto qui è il lavoro locale non sincronizzato — una modifica che esiste solo nel tuo working tree, mai pushata, non è ancora nella mappa ospitata.

Poi colleghi qualsiasi client tu già usi aggiungendo una chiave API alla sua configurazione MCP. Esistono guide di configurazione per 24 client MCP documentati, e qualsiasi altro client compatibile con MCP che supporta la configurazione standard può connettersi anch’esso. Se Cursor è casa tua, la pagina Cursor percorre quella strada; lo stesso server risponde a Claude Code, VS Code, Windsurf, Codex CLI e agli altri.

Non cambi editor. Dai al tuo agente una superficie di strumenti — 11 strumenti MCP per ricerca, simboli, analisi delle dipendenze, recupero file e contesto del repository — con copertura di oltre 279 lingue e tecnologie basate su testo, il che conta più di quanto pensi su un monorepo che ha smesso di essere una sola lingua anni fa.

Le risposte tornano fondate, come percorsi di file con numeri di riga. Ricerca semantica, strutturale, a grafo e testuale vengono fuse in risultati classificati, così una domanda come ‘cosa dipende da parseConfig’ non ti dà né un dump grep né un singolo frammento semantico, ma la manciata di posti che davvero contano.

Una guida concreta

Non iniziare indicizzando l’intera azienda. Ecco il percorso che funziona:

Scegli un repository che già conosci bene — un pacchetto che puoi valutare a mano vale più del più grande albero che hai.
Inizia gratis: 3 repository, 50mila righe indicizzate, tutti gli 11 strumenti, nessuna quota mensile di query. Se il tuo repository rappresentativo è più grande, la pagina prezzi elenca i livelli di spazio di lavoro ($0, $19, $49, $149) per estensione indicizzata — non per numero di posti.
Collega GitHub e attendi che la prima indicizzazione finisca. Non stai compilando nulla localmente.
Collega il client MCP — poche righe di configurazione. Maguyva è un server MCP remoto, quindi non ci sono plugin, né estensioni, né un secondo editor da adottare.
Fai una domanda che puoi verificare. ‘Cosa dipende da parseConfig?’ oppure ‘Dove viene gestita la scadenza della sessione di login?’ Poi apri i risultati citati file.ext:line e confrontali con l’albero di fronte a te.
Solo dopo che le citazioni sopravvivono a quel contatto lasci che l’agente modifichi.

Se il primo repository si adatta bene e il tuo albero è grande, aumenta lo spazio di lavoro per adattarlo alle righe indicizzate e alla cadenza di ricostruzione. Umani e agenti condividono lo stesso conteggio di utenti — Maguyva addebita per spazio di lavoro, non per posto — quindi aggiungere un terzo agente al ciclo non ti costa nulla.

Il test di attivazione è lo stesso che la documentazione raccomanda per qualsiasi prima esecuzione: indicizza un repository che già conosci, fai una domanda che puoi verificare. Un repository grande non cambia il test; rende solo più costoso un primo file sbagliato.

Cosa osservare dopo il collegamento

Tieni d’occhio tre cose. Aggiornamento: i piani a pagamento si ricostruiscono ogni ora, quelli gratuiti ogni giorno, e il lavoro locale non pushato non sarà nella mappa — è il compromesso che accetti. Ambito: indicizza un insieme rappresentativo di repository, non ogni fork archiviato; il livello gratuito è dimensionato apposta per scoprire se le risposte valgono la pena di essere mantenute. E verifica: una mappa di un repository grande che non può citare percorsi e numeri di riga è solo un motore di indovinelli più lento, quindi fai mostrare al tuo agente il posto prima che consegni la patch.

Poi esegui lo stesso test che eseguiresti su un repository piccolo. Indicizza un repository che già conosci. Fai una domanda che puoi verificare. Se la mappa è reale, il tuo agente smette di partire da un albero freddo.

// no laptop got hot building this map.

Perché il tuo agente di coding AI allucina i percorsi dei file

Fri, 14 Aug 2026 00:00:00 GMT

Il segnale non è un corpo di funzione sbagliato. È una modifica sicura di sé a un file che non esiste, o a un file che esiste ma non è quello che implementa il comportamento.

Hai chiesto una correzione della scadenza di sessione. L’agente ha aperto src/auth/session.ts. Quel percorso è plausibile. È anche sbagliato. L’handler vero vive in apps/api/src/middleware/expiry.ts, rinominato due refactoring fa. L’agente non ti ha mentito. Ha completato una stringa a forma di percorso a partire da priori di addestramento più qualsiasi cosa fosse già nella finestra di contesto.

Questo è il modello di fallimento comune su un repository reale. Il modello sa scrivere codice. L’errore sta nello scegliere il posto sbagliato in cui scriverlo.

Perché gli agenti inventano percorsi

Un agente di coding è un modello di previsione del token successivo dotato di strumenti. Quando dici ‘sistema la scadenza di sessione’, deve nominare un file prima di poter leggere o applicare una patch a qualsiasi cosa. Se non ha già una mappa fondata, costruisce un percorso a partire da:

Convenzioni di denominazione che ha visto in altri repository. src/auth/session.ts è una forma frequente.
File già presenti nella conversazione, che potrebbero essere quelli che hai incollato la settimana scorsa, non quelli che contano ora.
Elenchi di directory che ha eseguito per caso, incompleti su un albero grande.
File di istruzioni. CLAUDE.md e AGENTS.md dicono all’agente come comportarsi. Non sono un indice vivo di simboli, chiamanti, o percorsi attuali.

Nessuna di queste fonti è una mappa di questo repository, oggi. Il modello riempie il vuoto nello stesso modo in cui riempie qualsiasi vuoto: con una continuazione ad alta probabilità. Quella continuazione spesso sembra un percorso reale. A volte il file esiste ed è vicino a quello giusto. A volte esisteva su un branch unito il mese scorso. A volte non è mai esistito.

Grep non ti salva qui se l’agente non cerca affatto la stringa giusta. L’agente ha indovinato un percorso, poi ha letto ciò che quel percorso restituiva, poi lo ha modificato. Il primo passo sbagliato è stato il percorso, non la patch.

Leggere i file non è nemmeno lo stesso che trovare quelli giusti. Claude Code, Cursor, Codex, e strumenti simili possono aprire qualsiasi cosa tu indichi loro. La domanda è se trovano in modo affidabile i file giusti, i simboli importanti, le dipendenze, i test, e il raggio d’impatto prima di modificare. L’accesso ai file senza una mappa inizia comunque con un’indovinello.

La modifica del file sbagliato è un problema di recupero

Tratta il percorso inventato come un errore di recupero, non come un difetto di personalità.

Se l’agente dovesse restituire path/file.ext:line prima di poter modificare, accadrebbero due cose. Primo, potresti aprire la citazione e rifiutare il lavoro in dieci secondi. Secondo, l’agente dovrebbe interrogare qualcosa che conosce davvero l’albero.

Questo è il lavoro di un livello di contesto della codebase. La sola ricerca semantica non basta. Un frammento che ‘suona come scadenza di sessione’ può comunque atterrare in un pacchetto deprecato. Ti serve anche testo esatto quando conosci la stringa, ricerca di simboli quando conosci il nome, ricerca strutturale quando conosci la forma, e un grafo delle dipendenze quando ti servono i chiamanti e il raggio d’impatto.

Maguyva è quel livello per gli agenti di coding compatibili con MCP. Non è un editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, e altri client MCP restano dove sono. L’agente interroga una mappa classificata prima di toccare una riga.

L’affermazione è deliberatamente modesta: meno modifiche allucinate. Maguyva non toglie al modello la capacità di indovinare. Cambia il primo passo predefinito da ‘inventare un percorso plausibile’ a ‘chiedere posizioni classificate e citate’.

Come appare una risposta fondata

Una risposta utile a ‘dove viene gestita la scadenza di sessione’ non è un paragrafo. È un breve elenco di posizioni:

apps/api/src/middleware/expiry.ts:48 - l’handler
apps/web/src/lib/auth-client.ts:112 - il chiamante
apps/api/tests/expiry.test.ts:20 - il test che fallirà se la modifica è sbagliata

Puoi aprire queste righe. Se sono sbagliate, ti fermi. Se sono corrette, l’agente può modificare. La verifica è il punto, non uno slogan.

Maguyva espone 11 strumenti MCP rivolti al cliente per ricerca, simboli, analisi delle dipendenze, recupero file, contesto del repository e workflow di utilità deterministici. Quattro modalità di recupero (semantica, strutturale, a grafo/dipendenze e testuale) vengono fuse in risultati classificati; la ricerca di simboli è uno strumento MCP separato (find_symbol). Le risposte fondate tornano con percorsi di file e numeri di riga, così puoi valutarle rispetto all’albero di fronte a te.

La documentazione descrive il percorso più breve: iniziare gratis, indicizzare un repository che già conosci, collegare il client, poi fare una domanda che puoi verificare.

Un ciclo che cambia la prima modifica

Non ti serve una nuova religione del workflow. Ti serve un passo in più prima della prima scrittura.

Fai una domanda che già puoi valutare. ‘Quale codice gestisce il login e la scadenza di sessione?’ è meglio di ‘sistema l’autenticazione’.
Esigi citazioni. Percorso del file e numero di riga, non un riassunto del ‘modulo di autenticazione’.
Apri i file citati. Segui il simbolo. Conferma la dipendenza che stai per toccare.
Solo allora lascia che l’agente applichi la patch.

Se il passo 2 non restituisce nulla di utile, l’agente non ha il diritto di improvvisare un percorso. Cerca di nuovo, oppure glielo indichi tu. Proprio questo unico cancello produce meno modifiche allucinate. Il modello è lo stesso modello. È la mappa che è cambiata.

I file di istruzioni contano ancora. Mantienili. Usali per convenzioni, regole di revisione, e per ciò che non va toccato. Non chiedere loro di essere l’indice. Un CLAUDE.md che elenca tre directory importanti sarà obsoleto la settimana dopo una divisione di pacchetto. Una mappa interrogabile si aggiorna quando si aggiorna il repository.

Un fallimento correlato è il file quasi giusto: l’agente apre auth.ts quando il comportamento vive in auth-client.ts, oppure applica una patch a un file generato invece che alla sorgente, oppure modifica la copia in packages/legacy perché il nome corrispondeva. Le citazioni non rendono impossibili questi errori. Li rendono visibili prima che il diff atterri.

Cosa non ti risolverà una mappa

Sii lucido su cosa ottieni. Una mappa fondata non renderà corretta ogni modifica — il tuo agente può comunque scrivere una patch sbagliata esattamente nel file giusto. Se la tua codebase si affida a dispatch dinamico, reflection, o monkey-patching, alcune ricerche di simboli torneranno più magre di quanto vorresti, perché è quello che l’indirezione a runtime fa a qualsiasi indice statico. E se speri in una percentuale — ‘percorsi allucinati ridotti del X%’ — non la troverai qui, perché nessuno può misurare onestamente quel numero per il tuo repository tranne te.

Ciò che puoi aspettarti è più stretto e più utile: l’agente smette di aprire le sue modifiche con un percorso indovinato. Quel primo passo diventa fondato in una mappa reale, ed è da lì che vengono le modifiche meno allucinate. Tutto ciò che viene dopo la citazione — leggere il diff, giudicare la patch — resta comunque il tuo lavoro, come è sempre stato.

Il test non ti costa quasi nulla: indicizza un repository che già conosci e fai una domanda che puoi verificare. Inizia con un percorso da cui sei già stato scottato. Se le citazioni sono sbagliate, lo vedrai subito. Se sono corrette, la prossima modifica del tuo agente avrà un posto migliore dove atterrare.

// it doesn't know the file. it knows how to find it.

Perché abbiamo aggiornato la ricerca sul codice a voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

I numeri di benchmark in questo articolo riflettono le classifiche RTEB al momento della pubblicazione (giugno 2026). Le classifiche si muovono; considera i ranking come uno scatto istantaneo, non un fatto permanente.

La ricerca semantica vale solo quanto gli embedding che ha sotto.

Quando un agente chiede a Maguyva “dove gestiamo i retry”, non sta facendo grep della parola “retry”. Sta chiedendo il significato - il loop di backoff, il circuit breaker, la cosa che avvolge una chiamata instabile. A quella domanda risponde un modello vettoriale che trasforma il codice in un punto nello spazio e trova i vicini. Scegli un modello migliore e ogni query semantica nel prodotto diventa silenziosamente più precisa.

Quindi abbiamo cambiato il nostro. A partire da giugno 2026, gli embedding del codice di Maguyva girano su voyage-4-large, sostituendo voyage-code-3.

Il benchmark

Non abbiamo preso questa decisione a sensazione. Il pubblico Retrieval Embedding Benchmark (RTEB) classifica i modelli di embedding su task di retrieval reali, e sulla sua classifica Code voyage-4-large si trova al #1 assoluto (90,86) - davanti a gemini-embedding-2-preview (90,26) e, in modo significativo, davanti al modello che stavamo già usando, voyage-code-3 (89,73, #3).

È un piccolo divario assoluto. Ma è un divario nella direzione giusta, su un benchmark pubblico, esattamente sul task a cui teniamo: recuperare codice per significato.

Il compromesso che accettiamo: quantizzazione binaria

Ecco la parte che la maggior parte degli articoli “abbiamo aggiornato il nostro modello” tralascia.

Maguyva non archivia vettori a piena precisione. Archiviamo embedding quantizzati binariamente: ogni vettore a 2048 dimensioni collassa in una firma a 2048 bit - 256 byte per vettore. Quelle firme vengono cercate con la distanza di Hamming, indicizzate e partizionate per tenant.

È un compromesso deliberato. La quantizzazione binaria rinuncia a un po’ di precisione di retrieval in cambio di uno storage drasticamente più piccolo e di calcoli di distanza veloci ed economici senza dover gestire un database vettoriale separato. Per un prodotto che indicizza interi repository per workspace, quell’economia conta più che spremere l’ultima frazione di punto di benchmark.

voyage-4-large si adatta a questo design senza forzare una migrazione del layer di storage: produce un output a 2048 dimensioni, come voyage-code-3, quindi le nostre colonne bit(2048) e il percorso di ricerca Hamming non sono cambiati. Il modello è migliorato; lo schema è rimasto fermo.

Il codice era solo l’inizio

Maguyva è uno strumento di intelligenza del codice. Ma siamo anche il cliente zero, e lo puntiamo anche su qualcos’altro: il markdown che vive nei nostri repository accanto al codice. Record di decisioni architetturali, runbook, contratti, documenti di finanza e policy - tutto versionato in Git, tutto dietro lo stesso server MCP, un indice semantico sui documenti, non solo sul codice sorgente.

Ecco esattamente perché conta l’ampiezza di voyage-4-large. Sulla stessa famiglia di classifiche RTEB è #1 in finanza, #1 in sanità, e #1 nel retrieval testuale complessivo - davanti a Gemini Embedding di Google, Embed v4 di Cohere, e text-embedding-3-large di OpenAI. (Voyage è co-creatore di RTEB, quindi lo leggiamo come un forte segnale pubblico piuttosto che come un arbitro perfettamente neutrale - ma viene confrontato testa a testa con ogni modello commerciale importante, su set di hold-out privati.) Lo stesso indice che trova la funzione giusta per un agente trova la clausola giusta in un contratto o la riga giusta in una policy - e su quei domini, voyage-4-large non è un compromesso, è il leader.

Perché paghiamo per embedding premium

C’è un modo più economico di fare ricerca, e gran parte è gratuita. La ricerca lessicale - BM25 e i suoi simili - fa il match delle parole chiave, gira localmente, e non costa nulla. I modelli di embedding open-source come BGE, Nomic, ed embeddinggemma offrono un retrieval semantico genuinamente decente, e puoi ospitarli tu stesso al prezzo di una GPU. Anche Maguyva usa il lato gratuito: ogni query fonde ricerca testuale, AST, a grafo, e semantica. Ciò su cui non risparmiamo è il layer semantico.

Paghiamo per token per embedding premium - voyage-4-large - invece di ospitare noi stessi un modello gratuito, per due motivi. Primo, la sola ricerca per parole chiave non può rispondere a “dove gestiamo i retry” quando il codice dice backoff e circuit breaker e non dice mai la parola “retry” - rappresentare il significato è la ragion d’essere dell’embedding, e sui domini che serviamo i modelli open restano indietro rispetto a quelli premium: un paio di punti indietro sul testo generale, e ancora più indietro in nicchie come codice, contratti, e finanza. Secondo, nella nostra esperienza la qualità del retrieval plasma la risposta finale più di quanto faccia il modello dall’altra parte - un agente forte a cui viene dato il contesto sbagliato risponde comunque male, e non vede mai il documento che non gli è mai stato dato.

Quindi gli embedding premium sono un costo per token che cresce con ogni repository e documento che indicizziamo - e lo sosteniamo consapevolmente. Per il risultato che ottengono i nostri utenti, la funzione giusta o la clausola giusta, pensiamo che quel compromesso valga la pena.

La parte onesta

La documentazione stessa di Voyage etichetta ancora voyage-code-3 come il modello ottimizzato per il codice. Allora perché passare al nuovo?

Perché leggiamo il benchmark pubblico, non solo la tabella dei modelli del vendor, e il benchmark ha messo voyage-4-large in cima per il retrieval di codice. Questa è stata una scommessa lungimirante: prendere il modello più nuovo e generalmente più forte e validarlo contro una classifica pubblica sui task che contano. Siamo a nostro agio a fare quella scommessa perché l’evidenza è ampia - voyage-4-large non vince solo sul codice, guida anche in finanza, sanità, e retrieval complessivo.

Le fondamenta dietro le quinte

Ogni strumento che esponiamo - ricerca semantica, raccolta del task-context, domande e risposte fondate - alla fine si riduce al retrieval. Quando il retriever migliora, l’agente dall’altra parte ottiene prove migliori, prende meno decisioni sbagliate, e ancora le sue risposte al codice giusto - o alla clausola giusta, o alla policy giusta. Un modello di embedding più preciso non è una feature vistosa. È la base su cui poggia tutto il resto, e l’abbiamo appena migliorata. Non te ne accorgerai. Questo è il punto.

Miglioramento ricorsivo del supporto ai linguaggi: affinare l'intelligenza del codice su ~280 linguaggi

Tue, 26 May 2026 00:00:00 GMT

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (maggio 2026). Consulta la nostra pagina del team per le cifre attuali.

Maguyva estrae simboli, riferimenti e un grafo delle dipendenze dal codice sorgente in circa 280 linguaggi. Ogni linguaggio è un handler tree-sitter su misura — query, euristiche, casi limite — e ogni handler può essere sottilmente sbagliato a modo suo. Una chiamata a metodo emessa come una lettura. Una funzione attribuita allo scope contenitore sbagliato. Una relazione che semplicemente non esiste.

Questo non lo puoi controllare a mano. Nessun team può leggere l’output di estrazione su 280 grammatiche e individuare gli edge sbagliati. Quindi la domanda interessante non è “la nostra estrazione è corretta” — è “come scopri che è sbagliata, a questa ampiezza, senza un essere umano in ogni loop.” La nostra risposta è il miglioramento ricorsivo del supporto ai linguaggi: un loop di qualità guidato da agenti specializzati nei linguaggi, un LLM che agisce da giudice, e una regola che continuiamo a reimparare: verde non è lo stesso di corretto.

Verde non è corretto

Ogni linguaggio ha una suite di fixture, e un gate di rilascio lo valuta su cinque dimensioni — accuratezza, integrità strutturale, completezza, qualità e performance. Un linguaggio diventa VERDE solo quando, sulle sue fixture, precisione ≥ 0,95, recall ≥ 0,99, e F1 ≥ 0,97, con almeno 20 edge attesi per confidenza statistica. Sotto quella soglia è GIALLO o ROSSO, e non viene rilasciato.

Quel gate è necessario ma non sufficiente. Le fixture validano contro fixture che abbiamo scritto noi. Codificano i casi a cui abbiamo già pensato. Un handler può essere impeccabile sulle sue fixture e comunque devastare un pattern che compare solo nel codice reale — un idioma da macro, un metodo con vincoli sui tipi generici, una feature del linguaggio per cui nessuno ha scritto una fixture. VERDE significa che le fixture passano. Non significa che un repository reale venga estratto in modo pulito. Quindi il loop deve lasciarsi alle spalle le fixture ed esaminare il codice reale.

Il loop interno: campiona, giudica, correggi, dimostra

Il loop centrale gira un linguaggio alla volta:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Alcune cose fanno funzionare tutto questo invece di farlo arrancare a vuoto.

Il giudice è l’agente, non una chiamata API. Quando diciamo “LLM come giudice”, intendiamo che l’agente specializzato nel linguaggio confronta ogni edge campionato con il codice sorgente reale e lo classifica con una griglia di valutazione fissa a cinque categorie: questo edge è corretto, un falso positivo, la relazione giusta con il tipo sbagliato, attaccato allo scope sbagliato, o porta metadati sbagliati? Quella griglia di valutazione è fondamentale — “23% di tasso di errore” non significa nulla finché non sai se sono difetti reali o il giudice che conta male.

Correggi una cosa, poi dimostralo. Ogni iterazione modifica esattamente un asset modificabile, poi riesegue i test con un harness fisso e mantiene la modifica solo se F1 migliora e la riclassificazione sembra migliore. Se non è così, va in rollback. Nessun lotto di modifiche speculative, nessun “dovrebbe essere meglio”. Una modifica si guadagna il suo posto o sparisce. E quando una correzione regge, viene promossa nella suite di fixture — così il bug che ha corretto non può mai tornare silenziosamente. Quel passaggio di promozione è ciò che rende il loop ricorsivo invece di semplicemente ripetitivo: ogni passata rafforza l’oracolo contro cui la passata successiva valida.

La lezione che continuiamo a reimparare: le metriche sovrastimano

Ecco la trappola, e ci siamo caduti dritti. Le metriche secondarie del corpus — con che frequenza un target estratto non ha un simbolo risolvibile, quanti simboli sembrano “orfani”, e così via — sovrastimano enormemente i problemi. Sono per lo più artefatti del paradigma, non bug.

L’esempio più pulito: llvm una volta mostrava un tasso del 73% di “sorgente senza simbolo” e fu bollato come catastrofico. Abbiamo scavato. L’accuratezza reale era del 98,5%. I “simboli mancanti” erano quasi tutti riferimenti esterni legittimi — chiamate nella libreria standard, in framework, in codice che vive fuori dal repository. La metrica stava misurando una proprietà del linguaggio, non un difetto dell’handler. Linguaggi come Zig, COBOL e Odin mostrano tassi di “orfani” del 65-70% e sono completamente corretti; COBOL aveva zero errori reali.

Se avessimo lasciato che quei numeri guidassero il lavoro, avremmo passato settimane a “correggere” handler già corretti e a ignorare i linguaggi con bug reali e silenziosi. La conclusione è netta: le metriche aggregate sono al massimo un rozzo segnale di triage. Il vero segnale di qualità è il controllo a campione con classificazione degli edge — guardare gli edge reali in repository reali e giudicarli uno per uno. Dati sopra l’intuizione, ma solo una volta che sai quali dati dicono la verità.

Il loop esterno: una flotta, non una maratona

Procedere un linguaggio alla volta richiederebbe un’eternità per coprirne 280, quindi il loop interno è avvolto in uno esterno che ne fa girare molti in parallelo.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Ogni agente lavora in un worktree usa-e-getta così da non pestarsi i piedi a vicenda. L’orchestratore integra le loro correzioni una alla volta, ciascuna dietro un controllo di regressione a manifest completo: una modifica che aiuta il suo linguaggio ma silenziosamente ne rompe altri tre non viene integrata. L’integrazione è vincolata e confermata prima che qualcosa venga pushato — il gate di regressione decide cosa è sicuro, un essere umano decide ancora cosa viene rilasciato. Poi il pool ruota verso il prossimo gruppo di linguaggi e tutto il processo si ripete.

Cosa resta imperfetto

Il giudice può sbagliare, e l’errore ha una direzione: un agente che gira con troppo poco contesto sovrastima. In un lotto, otto linguaggi sono stati segnalati con un errore del 5-20%; all’ispezione solo uno di quei linguaggi presentava un bug reale — il resto erano errori del giudice dovuti a non aver colto la semantica propria del linguaggio (una riga sorgente che legittimamente emette più edge, binding di parametri modellati come assegnazioni, linguaggi con riferimento-per-identificatore). Ecco perché campioniamo con due seed e facciamo cross-check, e perché un disaccordo tra il giudice e le fixture è trattato come il segnale più interessante, non un verdetto definitivo — a volte è la fixture a essere sbagliata.

Siamo anche onesti sull’obiettivo. Il traguardo è zero errori reali, punto e basta — ma “zero” è un obiettivo verso cui lavoriamo con costanza, linguaggio per linguaggio, non una casella da spuntare. C’è sempre un altro repository con un altro idioma.

Dimostrato con il lavoro, non solo dichiarato

Tutto ciò che Maguyva fa per un agente — trovare un simbolo, tracciare una dipendenza, rispondere a una domanda con codice citato — poggia sul fatto che l’estrazione sottostante sia corretta. Su 280 linguaggi, la correttezza non può essere soltanto dichiarata; deve essere continuamente dimostrata sul codice reale. Il loop è il modo in cui ce la guadagniamo: un ciclo autonomo di campionamento-e-correzione che tratta le proprie metriche con sospetto, dimostra ogni modifica, e trasforma ogni correzione in una guardia contro la prossima regressione. Non è affascinante. È il lavoro che ci permette di dire “supportiamo il tuo linguaggio” e intenderlo davvero. Verde è facile. La correttezza si conquista con il lavoro.

Ricerca a fusione multi-modale: scegliere il retriever giusto per ogni query

Wed, 15 Apr 2026 00:00:00 GMT

Nota sul design storico: questo articolo dell’aprile 2026 descrive il design del routing di allora, non il comportamento predefinito attuale. La correzione di settembre riportata sotto riguarda esclusivamente un’affermazione su una misurazione. Per il routing attuale, i preset e i controlli espliciti delle modalità, si veda Come funziona.

Una query di ricerca non è una cosa sola.

“dove è definito parseConfig” vuole un simbolo esatto — una posizione precisa, veloce. “come funziona l’autenticazione” vuole significato — la distesa di codice correlato che spiega un concetto. “cosa si rompe se cambio questa funzione” vuole il grafo delle dipendenze. “trova la stringa ECONNREFUSED” vuole un match letterale, niente di furbo.

Grep è eccellente per i match letterali e utile per alcune cacce ai riferimenti, ma non è un grafo delle dipendenze e non capisce il significato. Gli embedding coprono il lato semantico, ma sono lo strumento sbagliato per stringhe esatte e analisi d’impatto. La maggior parte degli strumenti di ricerca sul codice sceglie un solo motore e impone quella scelta a ogni query. Maguyva non sceglie. Capisce che tipo di domanda hai fatto, poi combina quattro retriever nella proporzione che quella domanda merita.

Quattro modalità

Sotto il cofano ci sono quattro modi indipendenti per trovare codice:

semantica — ricerca vettoriale su embedding binari Voyage; trova codice per significato.
testuale — matching a trigrammi; trova letterali, stringhe di errore, identificatori esatti.
strutturale — query AST; trova definizioni, firme, e costrutti del linguaggio.
a grafo — il grafo delle dipendenze; trova chiamanti, chiamati, e raggio d’impatto.

Ognuna eccelle su una classe diversa di domanda. Il trucco sta nel decidere quanto fidarsi di ciascuna per la query che hai davanti.

Classificazione dell’intento

Prima che parta qualsiasi retrieval, un classificatore leggero smista la query in una di sei categorie di intento, con un punteggio di confidenza. È deliberatamente economico — euristiche ordinate, vince il primo match — perché gira sul percorso critico e aggiunge solo un millisecondo o due:

inizia con def , class , func , import … → find_definition (confidenza 0,95)
“who calls”, “usages of”, “references to” (chi chiama, usi di, riferimenti a) → find_references (0,90)
“impact”, “blast radius”, “what depends on” (impatto, raggio d’impatto, cosa dipende da) → impact_analysis (0,90)
una "string" tra virgolette o un token di errore come traceback → exact_match (0,85–0,90)
un identificatore CamelCase o snake_case → find_definition (0,60–0,80)
“how”, “why”, “explain”, “architecture” (come, perché, spiega, architettura) → understand_code (0,75)
niente corrisponde → understand_code, bassa confidenza (0,40)

Ogni intento porta un profilo di peso sulle quattro modalità. Questi sono i numeri reali:

Intento	semantica	testuale	strutturale (AST)	a grafo
find_definition	0,2	0,1	0,6	0,1
find_references	0,1	0,2	0,2	0,5
understand_code	0,5	0,2	0,2	0,1
find_similar	0,4	0,3	0,2	0,1
impact_analysis	0,1	0,1	0,1	0,7
exact_match	0,0	0,9	0,1	0,0

Quindi “dove è definito parseConfig” pesa forte sull’AST (0,6). “come funziona l’auth” pesa sui vettori semantici (0,5). “cosa dipende da questo” è quasi tutto grafo (0,7). “trova ECONNREFUSED” è quasi tutto trigrammi (0,9), con il modello di embedding completamente spento — perché la similarità semantica è esattamente lo strumento sbagliato per una stringa esatta.

Il percorso rapido, e il percorso fuso

Quando il classificatore è sicuro — punteggio ≥ 0,85 — e la query è di tipo normale, Maguyva salta del tutto la fusione e instrada direttamente verso la singola modalità dominante. “dove è definito X” non ha bisogno di quattro retriever; ha bisogno dell’indice AST, subito. Quel percorso diretto viene riportato indietro come fusion_strategy: "direct".

Tutto ciò che è ambiguo passa attraverso la fusione. Le quattro modalità (o tre, sul preset predefinito) girano in parallelo, ciascuna restituendo la propria lista ordinata, e le combiniamo.

Reciprocal Rank Fusion pesata

Fondere retriever eterogenei è più difficile di quanto sembri: una similarità coseno di 0,82 e un punteggio a trigrammi di 137 e una centralità di grafo di 0,004 non sono sulla stessa scala, quindi non puoi semplicemente sommarli. La Reciprocal Rank Fusion aggira il problema scartando i punteggi grezzi e mantenendo solo il rank che ogni motore ha assegnato. Il contributo di un risultato da una modalità è:

contribution = weight × 1 / (k + rank + 1)

dove rank è la sua posizione nella lista di quella modalità e k è una costante di smoothing. I contributi vengono sommati tra le modalità per qualsiasi risultato che più di un motore ha trovato — l’accordo tra i retriever sale naturalmente in cima. Usiamo k = 40 sul preset predefinito e 60 su thorough (quick gira solo in modalità semantica, quindi la fusione lì non entra mai in gioco). Il lavoro originale su RRF è arrivato a k = 60 per il retrieval general-purpose; il nostro default è leggermente più aggressivo, il che dà un po’ più peso all’accordo tra le modalità nei risultati meglio classificati — e non consigliamo di regolarlo a mano.

Oltre a questo, i risultati portano un boost di importanza del grafo. Un hub — una funzione su cui si appoggia tutto il codebase — dovrebbe superare in classifica un nodo foglia poco noto anche a parità di rilevanza testuale, quindi moltiplichiamo ogni contributo per:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

La centralità arriva dalle metriche PageRank/degree precalcolate dalla pipeline, e il boost è limitato a un massimo di 1,5× così che una funzione popolare non possa seppellire completamente una più rilevante ma oscura. Infine retrocediamo i risultati da percorsi vendor, build, e archive, e deduplichiamo al miglior chunk per file.

Cosa resta imperfetto

Il classificatore dell’intento è un insieme di regex, non un modello addestrato. Gestisce le forme di query comuni con euristiche, mentre una query ambigua ricade su understand_code e su una combinazione orientata alla semantica. Una versione precedente di questo articolo descriveva come raggiunta una riduzione del tasso di ricerche senza risultati da circa il 15% a meno del 5%. La proposta del dicembre 2025 riportava in realtà una stima iniziale e un obiettivo; non viene fornito alcun insieme di query o resoconto delle misurazioni a supporto. Ritiriamo quell’affermazione di miglioramento raggiunto; si vedano le evidenze della fonte e la correzione. Non abbiamo sostituito il classificatore con un modello addestrato perché la versione economica è veloce e sufficientemente valida per il ruolo di routing previsto, e perché un classificatore sicuro di sé ma in errore è peggiore di un fallback onesto. I pesi stessi sono prior scelti a mano, non appresi da dati sui clic che non raccogliamo.

Fai la domanda, senza dover scegliere lo strumento

Un agente non dovrebbe dover sapere se ricorrere a grep o agli embedding o al call graph — dovrebbe fare la sua domanda in termini semplici e ottenere la risposta giusta. La fusione multi-modale è ciò che permette a find_symbol, alla ricerca semantica, e all’analisi delle dipendenze di stare dietro un’unica interfaccia di query: il sistema legge la forma della domanda e assembla silenziosamente il retriever giusto per essa. Il modello che valuta gli embedding conta, ma conta anche sapere quando non usarli. Scegliere lo strumento giusto per ogni query è un tipo di qualità a sé, ed è uno che preferiamo possedere noi piuttosto che scaricare su chi chiama.

// you bring the question. it brings the tools.

Osservabilità degli agenti: hook, Alloy e Grafana

Tue, 24 Mar 2026 00:00:00 GMT

I sistemi ad agenti falliscono in modi strani.

A volte il problema è il modello. A volte è lo strumento. A volte il tuo server MCP funziona benissimo, ma l’agente ha scelto lo specialista sbagliato, oppure ha passato metà della sessione a fare lavoro di shell che non ti aspettavi, oppure ha silenziosamente bruciato budget in un loop che dall’esterno sembrava produttivo.

Se non riesci a vedere la differenza, non stai davvero gestendo un sistema ad agenti. Stai tirando a indovinare.

Così abbiamo costruito uno stack di observability per il nostro stesso workflow: Claude Code, Codex, eventi hook di Claude, eventi notify di Codex, OpenTelemetry nativo, Grafana Alloy e Grafana Cloud dall’altra parte.

La parte interessante non è “abbiamo fatto una dashboard”. La parte interessante è che abbiamo dovuto dividere la telemetria in due flussi diversi perché nessun singolo feed ci dava il quadro completo.

Il problema: la telemetria degli agenti è frammentata

Gli agenti di coding moderni emettono già una certa telemetria. Aiuta, ma non basta.

L’OTEL nativo è bravo a rispondere a domande come:

Quante richieste abbiamo fatto?
Quanto è costata una sessione?
Dove sono gli span e le trace?
C’è stato un picco di latenza?

È molto meno bravo a rispondere a domande come:

Su quale server MCP si è appoggiato l’agente?
Questo fallimento era in Bash, in uno strumento file integrato, o in una chiamata MCP?
Quale skill si è effettivamente attivata?
Quale tipo di subagent è stato dispatchato?
La sessione stava facendo lavoro utile, o stava solo arrancando a vuoto?

Quella seconda classe di domande vive più vicino agli hook che alle trace.

Ma è vero anche l’inverso: alcune delle domande di performance più importanti vivono più vicino alle trace che agli hook.

Se vuoi sapere dove si è effettivamente accumulata la latenza, quali span erano lenti, o se la sessione ha bruciato tempo nelle chiamate al modello piuttosto che nell’esecuzione degli strumenti, ti servono i dati di trace oltre agli eventi semantici.

L’architettura a cui siamo arrivati

Facciamo girare due percorsi di telemetria in parallelo.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Quella divisione è deliberata.

Ed è anche asimmetrica. Claude Code ci offre un’interfaccia di hook del ciclo di vita molto più ricca. Codex ci offre OTEL nativo più un’interfaccia notify, quindi normalizziamo eventi di completamento turno meno dettagliati nello stesso schema di log, invece di far finta che entrambi i runtime espongano gli stessi controlli.

L’OTEL nativo ci dà lo stream di base: log e trace dal runtime stesso, più metriche dove il runtime le emette effettivamente.

Gli eventi hook e notify ci danno il layer semantico: cose come PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, e i metadati classificati a cui teniamo davvero quando facciamo debug sul comportamento degli agenti. Claude Code fornisce qui lo stream di eventi più ricco. Codex fornisce uno stream normalizzato meno dettagliato ma comunque utile.

Perché esistono gli hook

La nostra pipeline di hook arricchisce gli eventi prima che arrivino a Loki.

Invece di dire semplicemente “è girato uno strumento”, classifichiamo l’evento in campi come:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: quale backend MCP ha gestito la chiamata
bash_cli: la famiglia di comandi shell
subagent_type: che tipo di specialista è stato dispatchato
agent_tool: se la sorgente era Claude Code o Codex

Questo significa che possiamo fare domande che contano operativamente:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Non sono campi messi lì per fare scena. Sono la differenza tra “l’agente sembrava lento” e “l’agente ha passato gli ultimi dieci minuti in operazioni git pesanti di shell con un alto tasso di fallimento degli strumenti”.

Un dettaglio implementativo che sembra più strano di quanto sia: lo stream Loki condiviso usa ancora service_name="claude-code-hooks" come label anche quando l’evento arriva da Codex. La vera separazione tra runtime avviene su agent_tool.

Perché Alloy sta nel mezzo

Grafana Alloy in questa configurazione non è solo un forwarder. È il punto in cui vengono applicate le policy.

Puntiamo lo stream OTEL nativo di Claude Code e Codex verso un proxy Alloy locale su localhost:4318, poi lasciamo che Alloy ripulisca il payload prima di inoltrarlo a Grafana Cloud.

Questo conta perché la telemetria grezza degli agenti è piena di campi ad alta cardinalità che sono utili per l’analisi ma pessimi come label indicizzate:

session_id
prompt_id
conteggi di token
durate
blob di parametri degli strumenti

Se indicizzi tutto, ottieni un’esplosione di label e una brutta giornata.

Quindi Alloy fa tre cose per noi:

Mantiene indicizzato un set molto piccolo di label a bassa cardinalità.
Sposta i campi rumorosi ma utili in metadati strutturati.
Scarta completamente il rumore puro.

L’idea importante è semplice: osserva di più, indicizza di meno.

Perché lo stream degli hook bypassa Alloy

Lo stream degli hook è già modellato per Loki.

Nel momento in cui send_event.py invia un evento, abbiamo già deciso quali campi meritano il trattamento da label e quali appartengono al corpo JSON strutturato. Quello stream va dritto al gateway OTLP di Grafana Cloud invece di passare di nuovo attraverso Alloy.

Quindi il sistema ha una chiara divisione del lavoro:

Alloy doma lo stream OTEL nativo grezzo.
L’arricchimento hook rende gli eventi semantici interrogabili.

Questo mantiene l’architettura più semplice rispetto a cercare di far passare tutto attraverso un unico percorso.

Cosa mostra davvero la dashboard

Lo screenshot qui sotto proviene da una delle dashboard di observability dietro il nostro workflow ad agenti. Non è un benchmark, e i numeri sono solo uno spaccato in un punto nel tempo. Il punto è la forma dei dati: feed di attività, chiamate agli strumenti, fallimenti, prompt, e ripartizioni per agente, strumenti integrati, uso di MCP, comandi shell e skill.

La parte utile è che questa dashboard vive sullo stesso stack Grafana del resto della telemetria degli agenti. Possiamo filtrare per agente sorgente e famiglia di strumenti e guardare attraverso i runtime senza inventare una storia di observability diversa per ogni sistema.

Una delle dashboard live dietro il nostro workflow ad agenti. Questo screenshot è solo uno spaccato di uno stack Grafana condiviso che riceve telemetria anche dagli altri nostri runtime e sistemi ad agenti. Clicca sull'immagine per la versione a piena risoluzione.

Perché le trace contano più di quanto sembri a prima vista

I log ci dicono che categoria di lavoro è stata svolta. Le trace ci dicono come il lavoro si è svolto nel tempo.

Quella distinzione conta nei sistemi ad agenti perché “lento” è troppo generico per essere utile.

Una trace può dirci se il rallentamento è stato causato da:

latenza del modello
tempo di esecuzione degli strumenti
retry ripetuti
un’interazione MCP particolarmente costosa
una lunga coda di piccole operazioni che sembravano innocue prese isolatamente

In pratica usiamo insieme lo stream degli hook e le trace di Tempo.

I log degli hook rispondono: che tipo di cosa è successa?
Le trace rispondono: dove è andato il tempo?

La combinazione è ciò che trasforma l’observability da una dashboard in una spiegazione.

Dove si inserisce Codex

Codex fa parte dello stesso stack, ma non è identico a Claude Code.

Per Codex colleghiamo due elementi:

OTEL nativo da Codex verso Alloy
Un webhook notify verso codex_notify.py, che mappa i completamenti dei turni nello stesso schema Loki che usiamo per gli eventi hook

Questo ci dà un filtro unificato come agent_tool="codex-cli" all’interno dello stesso stream di log.

L’avvertenza onesta: il payload notify di Codex oggi è meno dettagliato del payload hook di Claude Code perché non è lo stesso tipo di interfaccia di integrazione. Nella nostra configurazione attuale, i completamenti dei turni di Codex possono essere normalizzati nello schema condiviso, ma l’estrazione ricca strumento per strumento è ancora migliore nello stream OTEL nativo che nel bridge notify.

Questo non è un motivo per evitare l’articolo. È il punto dell’articolo. I sistemi di observability reali sono assemblati a partire da segnali imperfetti.

Grafana su MCP cambia le regole del gioco

Il cambiamento più grande è che Grafana non è solo un posto che gli umani visitano nel browser.

In questo repo esponiamo anche Grafana tramite MCP. Questo significa che un agente può interrogare Loki, Prometheus e Tempo direttamente, invece di aspettare che un umano ispezioni manualmente le dashboard per primo.

Questo trasforma l’observability in un input attivo per il workflow.

Un agente può chiedere:

Quali famiglie di strumenti hanno fallito di più nell’ultima ora?
Quale server MCP ha dominato una sessione?
Le modifiche recenti hanno ridotto i fallimenti degli strumenti o hanno solo spostato il lavoro su percorsi più pesanti di shell con gli stessi errori?
Quali trace mostrano la latenza più alta o retry ripetuti?

Una volta che hai questo, sei molto vicino a un loop di auto-miglioramento.

Dalla dashboard al loop di feedback

Questa è la parte che troviamo più interessante.

Una volta che lo stack di observability è interrogabile dal layer degli agenti, la telemetria smette di essere uno strumento di reportistica passiva e diventa un segnale di controllo.

Il loop funziona così:

L’attività dell’agente emette trace, metriche e log hook arricchiti.
Grafana archivia le prove in Loki, Tempo e Prometheus dove esistono le metriche.
Gli agenti interrogano quelle prove tramite Grafana MCP.
Il sistema identifica mix di strumenti scadenti, skill fragili, routing debole, o workflow pesanti di shell che continuano a produrre errori evitabili.
Agenti o operatori aggiustano prompt, configurazioni degli agenti, descrizioni delle skill, regole di routing, o accesso agli strumenti.
La sessione successiva produce una nuova forma di telemetria, e il ciclo si ripete.

Così si passa da “dashboard interessante” a “sistema di miglioramento misurabile”.

L’obiettivo non è massimizzare una categoria di strumenti. È arrivare al giusto mix di CLI, strumenti integrati, chiamate MCP e skill per il lavoro effettivamente svolto.

A cosa ci permette di rispondere

Una volta che entrambi i runtime finiscono nello stesso stack Grafana, possiamo rispondere a domande operative molto più velocemente:

I fallimenti sono concentrati in una famiglia di strumenti?
I workflow pesanti di shell stanno creando errori evitabili dove dovrebbe esistere uno strumento di livello superiore?
Quali server MCP stanno portando il carico di lavoro?
Stiamo pagando per attività di agenti che non producono progressi significativi?
Una sessione presenta problemi per colpa del modello, degli strumenti, o del layer di orchestrazione?

Questo è particolarmente utile nei workflow multi-agente, dove “l’agente era impegnato” non ti dice quasi niente.

Se uno specialista continua a essere dispatchato e a produrre alti tassi di fallimento, è un problema di routing o di formulazione dei prompt.

Se un server MCP domina tutte le chiamate, potrebbe essere una buona architettura o un segnale che tutto il resto è peso morto.

Se i fallimenti degli strumenti aumentano mentre il costo resta alto, hai un problema operativo, non un problema di qualità.

Se il lavoro di shell continua a fallire in modi prevedibili ed evitabili dove dovrebbe esistere uno strumento di livello superiore, quello è un segnale di prodotto.

Se una skill si attiva di continuo ma non migliora i risultati, quello è un segnale di prompt o di routing.

La vera lezione

La lezione più profonda qui è che l’observability degli agenti richiede sia telemetria di runtime che telemetria di workflow.

La telemetria di runtime ti dice cosa ha fatto il sistema.

La telemetria di workflow ti dice cosa l’agente pensava di stare facendo.

Ci servono entrambe.

Se tieni solo trace e contatori, perdi il layer semantico. Se tieni solo eventi hook, perdi latenza, span, e il quadro più ampio del runtime.

E se tieni entrambi ma non li reintroduci mai nel layer degli agenti, hai monitoraggio, non adattamento.

La combinazione è ciò che rende il sistema abbastanza spiegabile da poter essere gestito e abbastanza regolabile da poter essere migliorato.

Cosa resta imperfetto

Ci sono ancora spigoli da smussare.

Non tutti gli eventi hook includono i dati di durata e token che vorremmo.
Alcune delle migliori viste temporali arrivano ancora dalle trace di Tempo, non dai log degli hook.
Codex oggi è meno ricco semanticamente di Claude Code nello stream di eventi arricchiti.
Lo screenshot della dashboard è una superficie operativa live, non un artefatto di marketing rifinito.

Quest’ultimo punto è intenzionale. Preferiamo mostrare il vero pannello di controllo piuttosto che far finta che i sistemi ad agenti si spieghino magicamente da soli.

Perché questo conta per Maguyva

Maguyva punta a dare agli agenti una migliore intelligenza del codice. Ma una volta che gli agenti stanno effettivamente facendo lavoro utile, emerge subito un nuovo requisito: devi vedere come si stanno comportando.

Qualità della ricerca, qualità del routing, selezione degli strumenti, ed efficienza del contesto diventano tutti problemi osservabili.

Ecco perché pensiamo valga la pena scriverne. Lo stack degli agenti del futuro non è solo prompt e strumenti. È prompt, strumenti, e il layer di strumentazione che ti dice se tutto l’insieme sta funzionando.

Se stai costruendo workflow ad agenti seri, l’observability non è infrastruttura opzionale. È parte del prodotto.

Estrarre conoscenza per chiudere il loop: come le modifiche diventano memoria istituzionale

Tue, 03 Feb 2026 00:00:00 GMT

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (febbraio 2026). Consulta la nostra pagina del team per le cifre attuali.

Ogni team di ingegneria affronta la stessa sfida: le modifiche avvengono di continuo, ma il perché dietro quelle modifiche scompare. Sei mesi dopo, qualcuno chiede “perché abbiamo adottato DuckDB per gli stage della pipeline?” e la risposta vive solo nella testa di chi ha preso quella decisione — se è ancora in giro.

Abbiamo costruito un workflow di mining che chiude questo ciclo. Le modifiche fluiscono attraverso i commit git, vengono elaborate dalla nostra pipeline di mining, diventano voci di changelog strutturate e record di decisioni architetturali, e poi rientrano nei nostri agenti AI tramite query da CLI. Il risultato: una memoria istituzionale a cui possono accedere sia gli esseri umani che l’AI.

Il problema: le decisioni evaporano

Considera uno scenario tipico. Uno sviluppatore fa il commit di:

feat(canonical): add DuckDB runtime for pipeline stages

Questo commit rappresenta una scelta architetturale significativa. Il team ha valutato le opzioni, considerato i trade-off, e optato per DuckDB per motivi specifici. Ma tutto quel contesto vive in:

Un thread Slack (probabilmente cancellato)
La memoria di qualcuno (che sicuramente sbiadisce)
Un commento nel codice (forse, se sei fortunato)

Tre mesi dopo, un nuovo membro del team chiede: “Dovrei usare DuckDB o SQLite per questo nuovo stage?” Senza memoria istituzionale, o reinventa la ruota o fa scelte incoerenti.

Il loop: dai commit al contesto

Il nostro workflow di mining trasforma la cronologia git in conoscenza interrogabile:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

L’intuizione chiave: sia i changelog che le decisioni architetturali fluiscono dalla stessa cronologia git, elaborata attraverso una pipeline unificata. Questo garantisce che nulla sfugga.

Come funziona il mining

Passo 1: sincronizza l’indice

uv run orkestra mine sync

Questo comando scansiona la cronologia git e costruisce un indice di tutti i commit. Estrae segnali strutturati da ogni commit:

Tipo secondo Conventional Commits (feat, fix, chore, docs)
Scope (quale package o area)
Marcatori di breaking change
File toccati e metriche di complessità

Passo 2: controlla lo stato di copertura

uv run orkestra mine status

Ecco come appare il nostro stato attuale:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 commit elaborati. 476 sono diventati decisioni architetturali. 6.799 sono diventate voci di changelog. Ogni commit classificato.

Passo 3: ottieni i candidati per la revisione

uv run orkestra mine candidates --limit 50 --full

Questo fa emergere i commit non ancora elaborati, con il contesto completo per la classificazione:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

I segnali aiutano a guidare la classificazione: is_releasable_type: true suggerisce che questo dovrebbe apparire nel changelog. Il grande numero di inserimenti e i file infrastrutturali suggeriscono che potrebbe anche essere una decisione architetturale.

Passo 4: classifica i commit

Qui i percorsi si dividono in due: voci di changelog e decisioni architetturali.

Per le voci di changelog:

uv run orkestra mine classify abc123 --changelog added

Questo registra che il commit abc123 dovrebbe apparire nel changelog sotto la categoria “Added”.

Per le decisioni architetturali:

Prima, ottieni un ID di decisione reale:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Poi classifica con l’ID di decisione:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Questo collega il commit a un record di decisione che verrà creato o aggiornato.

Per l’elaborazione batch (quello che facciamo davvero):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Il formato JSONL supporta entrambi i domini in un solo passaggio:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Passo 5: renderizza gli output

uv run orkestra registry changelog render --package <pkg>

Questo genera file CHANGELOG.md per package a partire dal ledger. I changelog sono artefatti derivati — cancellali e si rigenerano perfettamente dal ledger sorgente.

La struttura del record di decisione

Le decisioni estratte diventano file YAML con metadati ricchi:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Ogni decisione rimanda ai suoi commit sorgente. Ogni decisione specifica quali file interessa. Le relazioni tra decisioni sono esplicite.

Integrazione CLI: interrogare la memoria istituzionale

È qui che il loop si chiude. Gli agenti possono interrogare le decisioni tramite la CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Restituisce decisioni sulla logica di retry, gestione degli errori, pattern di recupero.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Restituisce il record di decisione completo con contesto, motivazione e impatto.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Mostra quali scelte architetturali sono state fatte di recente.

Come gli agenti usano questo

Le istruzioni di base del nostro orchestratore includono:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Quando a un agente viene chiesto di implementare qualcosa legato a DuckDB, può prima controllare:

uv run orkestra registry decisions search --query "DuckDB"

E scoprire DEC-PL-142, imparando:

Perché abbiamo scelto DuckDB (context)
Come usarlo correttamente (agent_guidance)
Quali file guardare (files)
Quali decisioni correlate esistono (related)

L’agente non reinventa la ruota. Si basa su pattern già stabiliti.

Il test delle tre domande

Non ogni commit merita un record di decisione. Usiamo il test delle tre domande per filtrare:

È stata una decisione difficile da prendere? Ha richiesto un’analisi significativa, una valutazione dei trade-off, o un dibattito?
È una decisione costosa da cambiare? Invertire questa decisione richiederebbe una quantità significativa di lavoro da rifare?
Ha un impatto a livello di sistema? Interessa più package o stabilisce pattern che altri seguiranno?

Se un commit risponde “sì” ad almeno una di queste domande, è un candidato per l’estrazione di una decisione. Il nostro tasso tipico: 1-4 decisioni ogni 100 commit (circa l’1-4%).

Per le voci di changelog, la soglia è più bassa: ogni modifica visibile all’utente (feature, correzioni, miglioramenti) viene registrata. Le faccende interne, gli aggiornamenti di documentazione, e i refactor tipicamente vengono saltati. Il nostro tasso tipico: 30-50 voci di changelog ogni 100 commit.

Archiviazione dei dati: ledger append-only

Il sistema di mining usa ledger JSONL append-only per un funzionamento multi-agente senza conflitti:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Il formato JSONL con merge=union in .gitattributes significa che più agenti possono classificare i commit simultaneamente senza conflitti di merge. Ogni riga è indipendente.

Gate di validazione

Prima di ogni sessione di mining, eseguiamo la validazione:

uv run orkestra mine validate --quick

Questo controlla:

Validità del formato SHA
Conformità del formato dell’ID di decisione
Nessuna voce duplicata per lo stesso SHA
Le decisioni referenziate esistono davvero

Dopo la classificazione, validiamo di nuovo prima di fare il commit delle modifiche.

Perché questo conta

Il loop di feedback che abbiamo costruito risolve diversi problemi:

Per i nuovi membri del team: invece di chiedere “perché abbiamo fatto X?”, possono cercare nel registro delle decisioni. Il contesto è preservato.

Per gli agenti AI: non operano nel vuoto. Possono interrogare la conoscenza istituzionale prima di fare raccomandazioni. Quando viene chiesto di aggiungere un nuovo stage alla pipeline, possono scoprire il pattern DuckDB e seguirlo.

Per la coerenza architetturale: le decisioni sono esplicite e ricercabili. Quando qualcuno propone un approccio che contraddice una decisione esistente, il sistema può far emergere il conflitto.

Per la generazione del changelog: le note di rilascio non sono una corsa dell’ultimo minuto. Sono un sottoprodotto della classificazione continua durante lo sviluppo.

Per l’onboarding: i nuovi agenti ereditano il contesto completo del codebase. Non vedono solo il codice — vedono le decisioni che lo hanno plasmato.

Stato attuale

Ad oggi:

15.637 commit elaborati attraverso la pipeline
476 decisioni architetturali estratte e documentate
6.799 voci di changelog registrate
100% di copertura su entrambi i domini

Ogni commit da quando abbiamo iniziato è stato classificato. La memoria istituzionale è completa e interrogabile.

Come iniziare

Se vuoi implementare qualcosa di simile:

Inizia con lo standard Conventional Commits. La pipeline di mining funziona meglio quando i commit hanno prefissi strutturati (feat:, fix:, chore:).
Definisci i tuoi domini. Noi usiamo domini come pipeline, agent-design, observability, data-modeling. Questi organizzano le decisioni per area.
Costruisci l’abitudine alla classificazione. Il mining funziona quando i team classificano regolarmente i commit. L’elaborazione batch con assistenza LLM aiuta a scalare.
Rendi le decisioni interrogabili. Il valore si moltiplica quando gli agenti possono cercare le decisioni via CLI. Struttura il tuo output per il consumo automatico.
Chiudi il loop. Le decisioni dovrebbero influenzare il lavoro futuro. Includi riferimenti alle decisioni nelle istruzioni per gli agenti e nelle checklist di code review.

L’obiettivo non è una documentazione perfetta. È rendere il perché dietro le modifiche accessibile sia agli esseri umani che all’AI, oggi e tra sei mesi. Quando le modifiche diventano memoria istituzionale, i team si basano su pattern stabiliti invece di reinventarli.

Il workflow di mining fa parte del nostro motore di orchestrazione, in particolare del modulo del motore di contesto nel nostro package di orchestrazione.

Skill mining: da 3.500 candidate a 466 capacità

Tue, 27 Jan 2026 00:00:00 GMT

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra pagina del team per le cifre attuali.

Il problema delle 3.500 skill

Quando abbiamo iniziato a costruire un sistema di orchestrazione di agenti, abbiamo affrontato una sfida interessante: ci sono migliaia di skill potenziali sparse per l’ecosistema AI. Repository GitHub, documentazione dei vendor, progetti della community, pattern interni - le skill esistono ovunque. Ma quali contano? Quali funzionano? E come mantieni una libreria di skill coerente che gli agenti possano davvero usare?

La nostra risposta: un loop sistematico di mining e ingestione.

I numeri di oggi

Poco più di tre mesi dopo che Anthropic ha lanciato Agent Skills il 16 ottobre 2025, ecco a che punto eravamo quando questo articolo è stato pubblicato il 27 gennaio 2026:

Metrica	Conteggio
Candidati identificati	3.500+
Skill adottate	466
Skill dei vendor	373
Skill interne	93
Vendor attivi	25+
Token medi per skill	2.834
Strumenti referenziati	89
Tag unici	635

Abbiamo esaminato oltre 3.500 skill candidate. Ne abbiamo adottate 466. È un tasso di adozione del 13% - e quella selettività è voluta.

Il sistema a livelli di conoscenza

Non tutte le skill sono uguali. Le organizziamo in cinque livelli di conoscenza (K0-K4), ciascuno che rappresenta un ambito di applicabilità diverso:

K0: Fondamenta (universale)

Skill che ogni agente dovrebbe avere. Rappresentano capacità da “buon pensatore” che funzionano ovunque.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Le skill K0 sono portabili in qualsiasi progetto, qualsiasi dominio, qualsiasi stack. Codificano pattern cognitivi universali.

K1: Identità (disciplina)

Skill da “buon ingegnere” o “buon ricercatore” che si applicano tra progetti all’interno di una disciplina.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domini (competenza sulla materia)

Skill da “buon esperto di database” o “buon ingegnere della sicurezza” portabili all’interno di un campo.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stack (tecnologia)

Skill da “buon utente Supabase” o “buon sviluppatore Cloudflare” per stack tecnologici specifici.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Progetto (organizzazione)

Skill specifiche della nostra organizzazione e dei nostri workflow.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Il loop di mining

Fase 1: scoperta

Le skill arrivano da ovunque:

Repository dei vendor: AWS, Anthropic, Cloudflare, Supabase, e collaboratori della community pubblicano collezioni di skill. Tracciamo oltre 25 vendor root.

Progetti della community: GitHub è pieno di template per Claude Code, pattern di agenti, e definizioni di workflow.

Pattern interni: man mano che il nostro team risolve problemi, emergono pattern. Questi vengono formalizzati in skill.

Mining della documentazione: la documentazione tecnica spesso contiene skill implicite - procedure, checklist, alberi decisionali.

La scoperta è continua. Usiamo un backlog di skill per tracciare i candidati prima della valutazione formale.

Fase 2: valutazione

Ogni candidato passa attraverso la stessa griglia di valutazione:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Tutti e cinque i criteri di prodotto devono essere soddisfatti. Ecco perché l’87% dei candidati viene respinto.

Poi ogni candidato passa attraverso una verifica separata dell’affidabilità. Non trattiamo un repository ufficiale di un vendor, un maintainer noto della community, e un repository GitHub casuale come fonti di verità equivalenti.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

I vendor fidati ottengono una revisione di provenienza più leggera, ma non un lasciapassare gratuito. Le fonti non fidate o sconosciute ottengono un audit manuale più approfondito, e non eseguiamo gli script inclusi prima di averli letti, averne definito l’ambito operativo e averli classificati come sicuri.

Analisi delle lacune: prima di adottare, cerchiamo nel nostro registro:

uv run orkestra skills search "<capability>"

Se ce l’abbiamo già, non ci serve. Se abbiamo qualcosa di simile, potremmo unire invece di adottare.

Punteggio di profondità e standard: valutiamo anche quanto pienamente un candidato usa il modello agent-skill. Un singolo SKILL.md può comunque essere utile, ma le skill più profonde hanno più valore quando separano istruzioni da riferimenti, script, e asset come raccomandato da agentskills.io.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Le stelle GitHub possono alzare un po’ un punteggio di credibilità, ma non salvano mai una skill superficiale o non sicura. Un repository con molte stelle e un SKILL.md vago e script opachi ottiene un punteggio inferiore a un repository più piccolo con una descrizione precisa, materiali di riferimento selezionati in references/, e helper atomici che sfruttano davvero la piena capacità della skill.

Analisi strutturale: controlliamo la qualità della skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Se un candidato include script, quella revisione diventa più stringente. Una buona skill non è solo utile; deve essere leggibile, delimitata, e sicura da affidare a un agente. Solo quel filtro di sicurezza squalifica una fetta significativa di candidati altrimenti interessanti.

Fase 3: ingestione

Quando una skill supera la valutazione, entra nel registro. Ma le skill non vengono mai adottate senza modifiche. Vengono adattate al nostro sistema.

Modifiche all’adozione:

Normalizzazione dei metadati: ogni skill ottiene il nostro schema di frontmatter
Assegnazione del livello K: le skill vengono collocate nel livello di conoscenza appropriato
Arricchimento dei tag: vengono aggiunti tag per la scopribilità
Dichiarazione degli strumenti: gli strumenti consentiti vengono dichiarati esplicitamente
Allineamento delle sezioni: il contenuto viene ristrutturato per corrispondere al nostro template

Una tipica skill YAML dopo l’ingestione:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fase 4: assegnazione dell’ambito

Le skill vengono assegnate ad ambiti - categorie che determinano quali agenti caricano quali skill:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Gli agenti dichiarano i propri ambiti, e le skill vengono assegnate automaticamente:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fase 5: materializzazione

Le skill non vivono come YAML in produzione. Vengono renderizzate in file SKILL.md che Claude Code può caricare:

uv run orkestra sync

Questo comando:

Legge tutte le definizioni YAML delle skill
Le renderizza attraverso template Jinja
Scrive i file SKILL.md in .claude/skills/
Organizza per livello K (foundations/, identities/, domains/, stacks/, project/)

La struttura di output finale:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Il pattern dell’ambito dormiente

Uno dei nostri pattern più potenti è quello delle skill “adottate ma non caricate”. Le chiamiamo ambiti dormienti.

Considera le skill di calcolo scientifico dal repository k-dense-scientific. Abbiamo adottato oltre 120 skill che coprono bioinformatica, chimica, calcolo quantistico, e informatica clinica. Ma la maggior parte dei nostri agenti non ha bisogno di docking molecolare o analisi dell’espressione genica.

Invece di caricare tutte le 120 skill in ogni agente (gonfiando le finestre di contesto), noi:

Adottiamo le skill con un ambito specifico (es. bioinformatics)
Le manteniamo dormienti - registrate ma non caricate
Le attiviamo solo quando un agente dichiara quell’ambito

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Questo pattern ci permette di avere 466 skill nel registro mentre gli agenti tipici ne caricano solo 40-60 rilevanti.

Tipi di skill

Le skill si presentano in tre pattern cognitivi:

Workflow

Passi procedurali ordinati: “1. Fai X, 2. Poi Y, 3. Infine Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Disciplina

Guardrail comportamentali: “Fai sempre X”, “Non fare mai Y”, “Preferisci Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

Criteri di verifica: “Conferma X”, “Verifica Y”, “Controlla Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Gate di qualità

Ogni skill deve superare la validazione prima di essere rilasciata:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Le descrizioni devono essere lunghe 50-400 caratteri con frasi di attivazione (“Usa quando…”, “Quando hai bisogno di…”) così che Claude Code sappia quando suggerirle.

Validiamo continuamente:

uv run orkestra validate --show-warnings

L’ecosistema dei vendor

Le nostre 373 skill di vendor arrivano da:

Provider	Skill	Dominio
AWS Agent	19	Servizi cloud
Anthropic	12	Generazione documenti
Cloudflare	8	Edge computing
Supabase	5	Database
k-dense	100+	Calcolo scientifico
silvainfm	4	Data science
Java Developer Kit	45+	Spring/Java
Vercel	1	Automazione browser

Ogni vendor root è dichiarato in metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Quando orkestra sync viene eseguito, le skill dei vendor vengono collegate con symlink in .claude/skills/vendor/ con il proprio namespace del provider.

Cosa abbiamo imparato

La selettività ripaga. È allettante adottare tutto ciò che sembra utile. Ma ogni skill costa token. Con 2.834 token medi per skill, il sovraccarico di contesto si fa sentire presto. Il nostro tasso di adozione del 13% mantiene gli agenti snelli.

La struttura abilita la scopribilità. Il sistema a livelli K non è solo organizzazione - riguarda la portabilità. Le skill K0 possono essere riutilizzate ovunque. Le skill K4 sono intenzionalmente specifiche del progetto. Questa chiarezza aiuta sia gli esseri umani che gli agenti a trovare ciò di cui hanno bisogno.

Gli ambiti dormienti scalano. Puoi adottare centinaia di skill senza caricarle tutte. Gli ambiti ti permettono di costruire un registro completo mantenendo gestibili le finestre di contesto dei singoli agenti.

La modifica all’adozione è essenziale. Le skill grezze dei vendor raramente si adattano al tuo sistema. Il processo di ingestione - aggiungere metadati, assegnare livelli, arricchire i tag - fa funzionare internamente le skill esterne.

Il mining è continuo. Il numero 3.500 continua a crescere. Compaiono nuovi repository di vendor. Emergono pattern della community. I workflow interni si consolidano. Il loop non si ferma mai.

Cosa viene dopo

Stiamo lavorando su diversi miglioramenti:

Rilevamento automatico delle lacune: avvisa quando fallimenti comuni degli agenti potrebbero essere risolti da una skill non ancora adottata
Workflow di deprecazione delle skill: processo formale per ritirare skill superate o non utilizzate
Dipendenze tra skill: dichiarazione esplicita dei prerequisiti delle skill
Analisi di utilizzo: traccia quali skill gli agenti invocano davvero rispetto a quelle che si limitano a caricare

Il loop di mining delle skill è infrastruttura. Non è affascinante. Ma è ciò che fa funzionare 41 agenti in modo coerente con 466 capacità pur restando entro i limiti di contesto.

Questa è la storia di come 3.500 diventano 466. Non ignorandone 3.000 - valutandoli sistematicamente e adottando solo ciò che funziona.

Vuoi vedere il sistema di skill in azione? Dai un’occhiata a uv run orkestra skills list per esplorare il nostro registro attuale.

Progressive disclosure: finestre CLI sui sistemi ad agenti

Tue, 20 Jan 2026 00:00:00 GMT

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra pagina del team per le cifre attuali.

I sistemi ad agenti sono opachi per design. Prendono decisioni, invocano strumenti, e coordinano lavoro attraverso dozzine di specialisti. Ma quando qualcosa va storto — o quando semplicemente vuoi capire cosa sta succedendo — dove guardi?

La risposta è la progressive disclosure: un’interfaccia a livelli che rivela esattamente tanta complessità quanta te ne serve, esattamente quando ti serve.

Il problema dell’opacità

Un moderno sistema di orchestrazione ad agenti potrebbe avere:

40+ agenti specialisti, ciascuno con capacità distinte
700+ skill che spaziano tra automazione interna e integrazioni con vendor
470+ decisioni architetturali che plasmano il comportamento
Dozzine di server di strumenti MCP che forniscono capacità esterne

Questa complessità è intenzionale. Gli agenti hanno bisogno di accesso a un contesto ricco — conoscenza di dominio, intelligenza del codice, schemi di database — per prendere buone decisioni. Ma quella stessa ricchezza crea un problema di visibilità.

Come fai a sapere quale agente gestisce le migrazioni di database? Quali decisioni hanno plasmato il comportamento di ranking del sistema di ricerca? A quali strumenti ha accesso il consulente di architettura?

Senza un accesso strutturato, ti ritrovi a leggere il codice sorgente o a sperare che la documentazione sia aggiornata.

La progressive disclosure come architettura

La progressive disclosure non è solo un pattern di UI. È un principio architetturale: organizza le informazioni in livelli, ciascuno più profondo del precedente, così gli utenti possono fermarsi al livello che risponde alla loro domanda.

Per i sistemi ad agenti, questo si traduce in comandi CLI a profondità crescenti:

Livello	Comando	Domanda a cui risponde
1	`orkestra system status`	Va tutto bene?
2	`orkestra agents list`	Quali agenti esistono?
3	`orkestra agents info <name>`	Cosa fa questo agente?
4	`orkestra decisions search`	Perché funziona in questo modo?
5	Strumenti MCP di Maguyva	Mostrami il codice.

Ogni livello risponde a una naturale domanda di follow-up. Raramente devi saltare direttamente al livello 5.

Livello 1: salute del sistema

La prima domanda è sempre: funziona tutto?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Un comando. Quattro numeri. Sufficiente per sapere che il sistema è configurato e i registri sono popolati.

Se il conteggio degli agenti scende inaspettatamente o le skill non si caricano, lo vedi qui per primo. Nessun bisogno di scavare nei log.

Livello 2: inventario degli agenti

Una volta che sai che il sistema è in salute, la prossima domanda è: cosa è disponibile?

$ orkestra agents list

Questo restituisce dati strutturati — nomi degli agenti, descrizioni, preferenze di modello, copertura di dominio. L’output è JSON per default, il che rende facile incanalarlo in jq per il filtraggio:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Vuoi agenti che gestiscono lavoro sui database? Il comando di ricerca restringe i risultati:

$ orkestra agents search "database"

Questo scansiona nomi, descrizioni, e capacità. Trovi lo specialista giusto senza leggere 40 definizioni di agenti.

Livello 3: approfondimento sull’agente

Hai trovato un agente che sembra rilevante? Il comando info rivela tutto:

$ orkestra agents info architecture-advisor

L’output include:

Metadati: nome, categoria, preferenza di modello, descrizione
Domini: quali aree di conoscenza copre questo agente
Identità: tratti caratteriali (architect, strategist, knowledge-architect)
Guide agli strumenti: quale documentazione degli strumenti viene iniettata nel contesto
Strumenti: l’elenco completo degli strumenti MCP disponibili per questo agente

Ecco un campione di ciò che vedi:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Questo ti dice esattamente cosa può fare l’agente. Nessun codice sorgente richiesto.

Livello 4: archeologia delle decisioni

Gli agenti si comportano secondo decisioni documentate. Quando hai bisogno di capire perché qualcosa funziona in un modo particolare, il registro delle decisioni è la fonte di verità.

$ orkestra decisions search "agent"

Questo restituisce le decisioni architetturali corrispondenti:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Ogni decisione ha una provenienza completa — quando è stata presa, perché, quali trade-off sono stati considerati, quali commit l’hanno implementata:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Questa è documentazione architetturale che rimane aggiornata perché viene estratta dai commit, non mantenuta manualmente.

Livello 5: intelligenza del codice diretta

Quando hai bisogno di vedere l’implementazione reale — non i metadati su di essa — gli strumenti MCP di Maguyva forniscono accesso diretto.

Dall’interno di una sessione agente:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Questo instrada automaticamente tra ricerca semantica, testuale, e AST per trovare codice rilevante. Per simboli specifici:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Per l’analisi delle dipendenze:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Questi non sono solo sostituti di grep. Sono consapevoli del grafo, indicizzati semanticamente, e integrati con la stessa intelligenza del codice che alimenta gli agenti stessi.

Ricerca unificata tra i registri

A volte non sai quale registro contiene la risposta. La ricerca unificata copre tutto:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 corrispondenze su cinque registri. Il riepilogo ti dice dove approfondire. Rimuovi --summary per risultati dettagliati, o aggiungi --limit 5 per mantenere l’output gestibile.

Perché questo conta

La progressive disclosure non riguarda solo la comodità. Cambia il modo in cui interagisci con sistemi complessi.

Il debugging diventa gestibile. Quando un agente prende una decisione inaspettata, non fai grep nei log. Controlli a quali strumenti ha accesso (agents info), quali decisioni plasmano il suo comportamento (decisions search), e tracci l’implementazione se necessario (intelligent_search).

L’onboarding accelera. I nuovi membri del team non devono leggere l’intero codebase. Iniziano con system status, esplorano con agents list, e vanno più a fondo solo quando incontrano qualcosa che non capiscono.

La documentazione resta aggiornata. Poiché la CLI legge dagli stessi registri che configurano gli agenti, l’output è sempre accurato. Non c’è disallineamento tra ciò che dice la documentazione e ciò che fa il sistema.

La CLI come interfaccia

Avremmo potuto costruire una dashboard web. Avremmo potuto scrivere documentazione estesa. Invece, abbiamo costruito una CLI che legge dalla fonte di verità.

La CLI ha dei vantaggi:

Componibile: incanala l’output attraverso jq, integra con gli script
Scriptabile: automatizza controlli, genera report
Veloce: nessun caricamento di pagina, nessun flusso di autenticazione
Accurata: legge la configurazione reale, non una rappresentazione in cache

Per i sistemi dove la correttezza conta più dell’estetica, vince la CLI.

Costruire la tua progressive disclosure

Se stai costruendo sistemi ad agenti, considera come gli utenti li ispezioneranno:

Inizia con i controlli di salute. Un comando che ti dice se le cose funzionano.
Fornisci viste di inventario. Elenca cosa esiste prima di spiegare cosa fa.
Abilita query mirate. La ricerca batte la navigazione su larga scala.
Esponi la provenienza. Lascia che gli utenti traccino le decisioni fino alle loro origini.
Connetti all’intelligenza del codice. Alla fine, gli utenti devono vedere l’implementazione.

Ogni livello risponde a una domanda di follow-up. Costruiscili in ordine di frequenza — la maggior parte degli utenti si ferma al livello 2 o 3. Solo gli utenti esperti raggiungono il livello 5.

L’obiettivo non è esporre tutto. È esporre esattamente ciò che serve, esattamente quando serve. Questa è la progressive disclosure applicata all’architettura degli agenti.

Verità di base: ancorare gli agenti AI alla realtà

Tue, 13 Jan 2026 00:00:00 GMT

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra pagina del team per le cifre attuali.

Gli agenti AI sono straordinariamente capaci. Sanno ragionare, sintetizzare e generare. Ma hanno una debolezza fondamentale: si inventano le cose. Non in malafede, ma con sicurezza. Un agente può inventare parametri API che non esistono, fare riferimento a configurazioni mai definite, o applicare pattern dai suoi dati di addestramento che contraddicono la tua architettura reale.

La mitigazione standard è “dare all’agente più contesto”. Ma il contesto può essere contraddittorio. La documentazione si scosta dall’implementazione. I commenti mentono. Persino il codice può fuorviare se letto senza capire l’intento.

Ci serviva qualcosa di più esplicito. Qualcosa che non potesse essere ignorato o frainteso. Qualcosa che ancorasse gli agenti a una realtà verificabile.

Le chiamiamo Verità di Base.

Cos’è una Verità di Base?

Una verità di base è un’affermazione di fatto esplicita e versionata che gli agenti devono rispettare. Non è documentazione. Non è un commento. È un’entità di primo livello nel sistema, con:

Un identificatore univoco (come GT-MAG-015 o GT-MAG-036)
Uno stato di ciclo di vita (corrente, provvisorio, o deprecato)
Un ambito (piattaforma intera, specifico per package, o vincolato a un dominio)
Prove (percorsi di file, URL, o riferimenti che dimostrano l’affermazione)
Indicazioni per l’agente (istruzioni esplicite su cosa fare/evitare)

Ecco un esempio dalla nostra piattaforma di intelligenza del codice Maguyva:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Questa non è prosa. È un contratto. Quando un agente incontra questa verità di base, sa:

Il default è deterministico (risultati vuoti, non ipotesi approssimative)
Ci sono parametri specifici (find_similar, exact_match) con comportamenti definiti
Esistono prove in file specifici che possono essere verificati
L’affermazione è stata verificata a una data specifica

L’anatomia di un registro di Verità di Base

Le verità di base vivono in registri YAML sotto ai_assets/reference/ground_truths.yaml. Ogni package o dominio può avere il proprio registro. La struttura è:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Il registro include metadati sulla collezione stessa, configurazione di rendering per la generazione della documentazione, e le affermazioni stesse. Ogni affermazione segue uno schema rigoroso validato da modelli Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Come gli agenti accedono alle Verità di Base

Le verità di base sono esposte attraverso più canali:

1. Documentazione renderizzata

Il comando orkestra sync trasforma i registri YAML in markdown leggibile:

uv run orkestra sync

Questo genera file GROUND_TRUTHS.md inclusi nel contesto dell’agente. L’output renderizzato raggruppa le affermazioni per stato e categoria:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Ricerca da CLI

Gli agenti con accesso shell possono cercare le verità di base programmaticamente:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

La funzione di ricerca assegna un punteggio ai risultati su più campi con rilevanza pesata:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Composizione del contesto

Quando gli agenti vengono renderizzati da definizioni YAML, il loro contesto può fare riferimento ai registri di verità di base:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Questo garantisce che le verità di base rilevanti vengano caricate prima che l’agente inizi il lavoro.

Categorie di Verità di Base

Osservando i nostri registri, le verità di base si raggruppano in diversi pattern:

Principi di prodotto

Vincoli su cosa il prodotto è e non è:

“Maguyva è di sola lettura rispetto ai repository degli utenti; l’unico asset non ricostruibile è la cache di embedding a pagamento.” (GT-MAG-001)

Confini architetturali

Dove vivono le responsabilità e perché:

“I confini tra pipeline e Maguyva sono intenzionali: la pipeline è riutilizzabile, Maguyva contiene la logica specifica del codice, e CQRS separa le operazioni di scrittura degli stage della pipeline dalle letture del server.” (GT-MAG-006)

Regole anti-allucinazione

Regole esplicite che mantengono i contratti degli strumenti deterministici invece che inferiti:

“Il matching fuzzy dei simboli è opt-in tramite find_similar=true. Il comportamento predefinito restituisce risultati vuoti per simboli inesistenti; exact_match=true impone un matching rigoroso e disabilita tutti i fallback fuzzy.” (GT-MAG-015)

Gate di qualità

Standard che devono essere mantenuti:

“Le modifiche all’infrastruttura condivisa (post_filters.py, estrattori di relazioni, handler condivisi) DEVONO essere validate contro TUTTI i linguaggi supportati tramite generazione del manifest completo prima del commit. Una validazione a linguaggio singolo non è sufficiente per il codice condiviso.” (GT-MAG-036)

Pattern di codice

Requisiti di implementazione:

“Usa asyncio.to_thread() per lavoro CPU-bound in contesti async; il pattern deprecato loop.run_in_executor() non deve essere usato in nuovo codice.” (GT-MAG-018)

Il ciclo di vita di una Verità di Base

Le verità di base non sono statiche. Evolvono attraverso un ciclo di vita definito:

Provvisoria

Una verità proposta in fase di valutazione. L’affermazione è registrata ma può cambiare:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Corrente

Una verità verificata che gli agenti devono rispettare. Le prove sono state convalidate:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecata

Una verità che non si applica più. Conservata come riferimento storico con un puntatore a ciò che l’ha sostituita:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Perché non semplice documentazione?

La documentazione serve a uno scopo diverso. Spiega. Insegna. Può essere vaga, può usare qualificatori come “generalmente” o “tipicamente”.

Le verità di base non possono essere vaghe. Sono asserzioni. O si applicano o non si applicano.

Considera la differenza:

Documentazione: “L’API generalmente restituisce risultati vuoti quando un simbolo non viene trovato, sebbene il matching fuzzy possa essere abilitato in alcune configurazioni.”

Verità di base: “Il comportamento predefinito restituisce risultati vuoti per simboli inesistenti; exact_match=true impone un matching rigoroso e disabilita tutti i fallback fuzzy.”

La prima è utile per gli esseri umani che imparano il sistema. La seconda fornisce indicazioni applicabili agli agenti che prendono decisioni.

Indicazioni per l’agente: fare ed evitare

Alcune verità di base includono indicazioni esplicite per l’agente:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Questo elimina l’ambiguità. Un agente che legge questo sa non solo cosa è vero, ma quali azioni quella verità implica.

Verifica e manutenzione

Le verità di base richiedono manutenzione. Tracciamo:

last_verified: quando qualcuno ha confermato che l’affermazione è ancora valida
evidence: file che dimostrano l’affermazione (può essere verificata la loro esistenza)
source: da dove ha origine la verità (ispezione da CLI, revisione architetturale, apprendimento post-incidente)

Una verità di base con date di verifica obsolete o link di prova rotti è un segnale da indagare. O la verità è ancora valida e necessita una riverifica, oppure la realtà è cambiata e la verità va aggiornata.

Esempi reali dalla produzione

Confine di sicurezza

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Questa verità di base previene una classe di “miglioramenti di sicurezza” mal indirizzati che romperebbero il prodotto.

Accuratezza al momento dell’estrazione

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Questa è nata da un’esperienza dolorosa. Gli agenti riparavano i language pack falliti aggiungendo filtri solo-validatore che facevano sembrare più verde il test harness, mentre l’estrattore Maguyva live continuava a emettere gli edge sbagliati. La regola costringe le correzioni a tornare sul percorso reale: config YAML, query, o handler.

Filtraggio multi-livello

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Questo impedisce agli agenti di aggiungere filtri nel posto sbagliato, un errore comune che causava regressioni di accuratezza.

Integrazione con il sistema di orchestrazione

Le verità di base sono un livello di un sistema di contesto più ampio:

Decisioni architetturali (ADR) - Registrano perché abbiamo scelto l’approccio A invece di B
Verità di base - Affermano cosa è accertato come vero in questo momento
Pattern di dominio - Descrivono come fare le cose correttamente
Anti-pattern - Descrivono cosa evitare e perché

Un agente che lavora nel sistema ha accesso a tutti e quattro. Le verità di base forniscono l’ancora fattuale, mentre le decisioni spiegano la storia, i pattern guidano l’implementazione, e gli anti-pattern avvertono delle insidie.

Misurare l’impatto

Da quando abbiamo introdotto le verità di base, abbiamo osservato:

Meno cicli di “correggere la correzione allucinata”
Un processo decisionale degli agenti più sicuro quando i fatti sono chiari
Revisioni delle PR migliori perché le aspettative sono esplicite
Tempi di onboarding ridotti per i nuovi agenti (e per gli esseri umani)

L’investimento nel mantenere le verità di base ripaga in meno debugging e confini di sistema più chiari.

Come iniziare

Per aggiungere una verità di base al tuo sistema:

Crea un ground_truths.yaml nella directory ai_assets/reference/ del tuo package
Definisci metadati e configurazione di rendering
Aggiungi affermazioni seguendo lo schema
Esegui uv run orkestra sync per generare la documentazione
Includi il registro nella composizione del contesto dell’agente

Inizia dai fatti che causano più confusione o dai vincoli che vengono violati più spesso. Quelle sono le tue verità di base a più alto valore.

Conclusione

Gli agenti AI avranno allucinazioni. È nella loro natura. Ma possiamo creare ambienti in cui l’allucinazione è vincolata, in cui certi fatti non sono negoziabili, in cui gli agenti possono confrontare le proprie ipotesi con una realtà verificata.

Le verità di base non sono una soluzione completa. Richiedono manutenzione. Possono diventare obsolete. Aggiungono overhead al processo di sviluppo.

Ma offrono qualcosa di prezioso: un vocabolario condiviso di fatti di cui sia gli esseri umani che gli agenti possono fidarsi. In un mondo in cui gli agenti partecipano sempre di più allo sviluppo software, quella base condivisa diventa essenziale.

L’alternativa sono cicli infiniti di agenti che commettono errori con sicurezza e di esseri umani che li correggono. Le verità di base rompono quel ciclo rendendo le correzioni esplicite e durature.

I tuoi agenti meritano di sapere cosa è vero. Diglielo.

Orkestra: orchestrare agenti AI su larga scala

Tue, 06 Jan 2026 00:00:00 GMT

I numeri in questo articolo riflettono il sistema al momento della pubblicazione (gennaio 2026). Consulta la nostra pagina del team per le cifre attuali.

Quando abbiamo iniziato a costruire con Claude Code, ci siamo imbattuti in un problema che ogni team che usa assistenti AI per il coding finisce per affrontare: un singolo agente non può fare tutto bene.

Puoi istruire un agente a essere uno specialista di database. O un auditor di sicurezza. O un ingegnere frontend. Ma nel momento in cui gli chiedi di essere tutti e tre insieme, la qualità ne risente. Il contesto si diluisce. Le istruzioni entrano in conflitto. L’agente diventa un generalista mediocre in tutto.

Quindi abbiamo costruito Orkestra.

Cos’è Orkestra?

Orkestra è un sistema di orchestrazione di agenti per Claude Code e strumenti AI di coding simili. Coordina più agenti specializzati, ciascuno con competenze distinte, sotto un unico orchestratore che instrada il lavoro allo specialista giusto.

Pensalo come un’agenzia di collocamento per agenti AI. L’orchestratore riceve un task, identifica quale specialista dovrebbe gestirlo, e delega con il contesto giusto. Quando il lavoro è finito, i risultati rifluiscono verso l’orchestratore per la sintesi.

I numeri raccontano la storia:

Componente	Conteggio
Agenti specialisti	46
Skill riutilizzabili	466
Archetipi di identità	27
Mindset	11
Stili di comunicazione	10
Domini di conoscenza	21

Il sistema dei personaggi: D&D per gli agenti

L’intuizione centrale dietro Orkestra è che il comportamento dell’agente emerge da tre primitive componibili:

L’identità definisce cosa è l’agente. Un architetto progetta strutture di sistema. Un debugger risale dai fallimenti alle cause profonde. Un guardiano fa rispettare compliance e confini di sicurezza. Abbiamo 27 archetipi di identità che possono essere combinati.

Il mindset definisce come pensa l’agente. Un mindset analitico ancora le asserzioni alle prove e quantifica l’incertezza. Un mindset scettico mette in discussione le assunzioni e cerca prove che le smentiscano. Un mindset esplorativo abbraccia l’ambiguità e prova approcci multipli.

Lo stile definisce come comunica l’agente. Uno stile tecnico include valori esatti e fa riferimento a file specifici. Uno stile conciso taglia i fronzoli e parte dalla risposta. Uno stile diplomatico bilancia onestà e tatto.

Un agente combina queste primitive:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Questa composizione crea un agente che progetta sistemi (architect), connette conoscenza tra domini (knowledge-architect), fissa la direzione strategica (strategist), ragiona sulla base di prove e dati (analytical), e comunica senza fronzoli (concise).

La potenza sta nell’esplosione combinatoria. 27 identità per 11 mindset per 10 stili producono quasi 3.000 possibili personalità di agente. Ma definisci solo le combinazioni che contano per il tuo lavoro.

Skill: moduli di capacità riutilizzabili

Le skill sono la conoscenza e i workflow che gli agenti possono invocare. Seguono un sistema a livelli basato sull’ambito:

Livello	Nome	Ambito	Esempio
K0	Fondamenta	Metodologia universale	Disciplina test-first, completamento basato su prove
K1	Identità	Workflow basati sul ruolo	Standard di interfaccia CLI, performance playbook
K2	Domini	Conoscenza specifica del dominio	Pattern di migrazione database, validazione dell’autenticazione
K3	Stack	Specifico per tecnologia	Deployment su Cloudflare, operazioni Supabase
K4	Progetto	Solo questo codebase	Workflow e convenzioni specifici del progetto

Le skill sono caricate in modo lazy. Un agente vede nomi e descrizioni delle skill all’avvio, ma il contenuto completo della skill si carica solo quando viene attivato. Questo mantiene il contesto snello rendendo al contempo centinaia di skill scopribili.

Ogni skill include:

Condizioni di attivazione chiare (“Usa quando fai la migrazione degli schemi database”)
Guida passo per passo
Strumenti consentiti per il workflow
Criteri di successo e percorsi di recupero dal fallimento

Le 466 skill nel nostro registro coprono tutto, dall’isolamento dei worktree git ai workflow di ricerca web fino alla validazione della salute dei deployment.

Perché l’orchestrazione conta

Le architetture a singolo agente sbattono contro muri rapidamente:

Diluizione del contesto. Una finestra di contesto da 200k token sembra grande finché non ci carichi schemi di database, documentazione API, fixture di test, e conoscenza di dominio. Gli specialisti possono lavorare con contesto mirato.

Conflitti di istruzioni. Dire a un agente di “essere approfondito ma veloce” e “verificare tutto ma senza over-engineering” crea tensione. Gli specialisti risolvono questo avendo un ambito chiaro.

Profondità di competenza. Un agente generalista sa un po’ di tutto. Un agente specialista, composto con l’identità e le skill giuste, conosce il suo dominio a fondo.

Orkestra implementa un’orchestrazione piatta: un orchestratore coordina più specialisti. Gli specialisti non possono generare sub-specialisti. Questo previene l’esplosione di complessità permettendo al contempo il lavoro parallelo.

L’orchestratore ha accesso a 2,2 milioni di token di capacità effettiva: la propria finestra da 200k più 10 subagent concorrenti da 200k ciascuno. Lavoro che esaurirebbe un singolo agente gira comodamente attraverso la flotta.

La pipeline di rendering

Le definizioni degli agenti vivono in YAML. Claude Code legge Markdown. Orkestra colma questo divario con una pipeline di rendering deterministica:

YAML Registries → Jinja Templates → .claude/agents/*.md

Gli operatori modificano la sorgente YAML. Eseguono orkestra sync. Il Markdown renderizzato appare in .claude/agents/. Claude Code recepisce le modifiche.

Questa separazione serve pubblici diversi:

La sorgente YAML include metadati di ciclo di vita, tag, regole di validazione, e note di deprecazione per il tooling
Il Markdown renderizzato include solo ciò di cui il modello ha bisogno: descrizione, strumenti, skill, e guida comportamentale

La pipeline compone identità, mindset, stili, e skill in un unico prompt coerente. Un agente architect-analytical-concise ottiene un system prompt molto diverso da un agente debugger-skeptical-technical, anche se condividono alcune skill sottostanti.

Conoscenza di dominio: il pattern a quattro file

Ogni dominio di conoscenza segue una struttura coerente:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Questa struttura serve il caricamento del contesto dell’agente. Un agente che lavora sull’autenticazione carica authentication/patterns.md per la guida e authentication/anti-patterns.md per evitare le insidie conosciute. I file sono dimensionati per un caricamento efficiente del contesto: abbastanza mirati da essere utili, abbastanza completi da essere autorevoli.

Manteniamo 21 domini di primo livello tra cui analytics, autenticazione, data science, infrastruttura, machine learning, performance, sicurezza, e altro ancora. Ogni dominio può avere sotto-domini per una granularità più fine.

Valori: il sistema operativo

Tutti gli agenti condividono un livello di base di valori che definisce come operano:

Semplicità prima di tutto. Usa la soluzione più semplice che funziona. Aggiungi complessità solo quando è giustificata.

Correggi le cause profonde. Non aggirare mai i problemi con soluzioni di ripiego. Se una pipeline fallisce, fai debug della pipeline. Se un test fallisce, correggi il codice o il test.

Basato su prove. Etichetta le affermazioni come “verificate” (con benchmark) o “stimate” (con assunzioni). Un pattern rilevato non equivale a un problema confermato.

Economia del contesto. Gli strumenti MCP costano lo 0,1% del contesto. Le letture di file costano il 2% ciascuna. Applica la competenza di dominio prima di esplorare il codice.

Questi valori si propagano a ogni specialista attraverso la pipeline di rendering. Un agente non può aggirarli tramite composizione.

CLI: il piano di controllo

Orkestra include una CLI per gestire l’ecosistema di agenti:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

La CLI è la fonte di verità su quali agenti esistono, quali skill hanno, e se il sistema è in salute. Esegue la validazione prima della sincronizzazione per intercettare i problemi in anticipo.

Considerazioni sull’open source

Abbiamo costruito Orkestra per risolvere il nostro stesso problema: coordinare agenti AI su larga scala per un codebase complesso. I pattern che abbiamo scoperto non sono specifici del nostro dominio.

Il sistema di composizione dei personaggi (identità + mindset + stile) si applica a qualsiasi team che definisce personalità di agente.

Il sistema a livelli delle skill (K0-K4) fornisce un modello mentale per organizzare capacità riutilizzabili per ambito.

Il pattern della pipeline di rendering (sorgente YAML + template + artefatti generati) separa le responsabilità tra tooling e consumo da parte del modello.

Il modello di orchestrazione piatta (un coordinatore, molti specialisti) evita la complessità pur abilitando il parallelismo.

Se Orkestra diventerà open source dipende dal fatto che questi pattern abbiano valore per altri che costruiscono con Claude Code. Se stai sbattendo contro i muri che abbiamo descritto, l’architettura potrebbe aiutare.

Cosa abbiamo imparato

Costruire Orkestra ci ha insegnato che l’orchestrazione non riguarda il rendere gli agenti più intelligenti. Riguarda il renderli più focalizzati.

Un singolo agente con istruzioni perfette esaurisce comunque il contesto. Un singolo agente con tutte le skill si confonde comunque su quale applicare. Un singolo agente che cerca di essere tutto produce risultati mediocri ovunque.

Quaranta specialisti, ciascuno eccellente nel proprio dominio, coordinati da un orchestratore che sa quando delegare: è così che rilasciamo il software.

I numeri contano meno dell’architettura. Potresti aver bisogno di cinque agenti o cinquanta. Il principio resta: privilegiare la composizione rispetto alle singole capacità, la specializzazione rispetto alla generalizzazione e il coordinamento rispetto agli eroismi individuali.

Orkestra alimenta l’ecosistema di agenti dietro Maguyva, la nostra piattaforma di intelligenza del codice. Vuoi saperne di più? Contatta il team.