La maggior parte delle persone usa ancora Claude Code come un tirocinante molto costoso.
Gli danno un compito, aspettano una risposta, poi decidono manualmente cosa fare dopo.
Ma i team che ottengono il massimo dall'IA stanno costruendo qualcosa di più simile a un piccolo sistema distribuito.
Un agente definisce il problema.
Cinque agenti più economici cercano in parallelo.
Uno script deterministico rimuove i duplicati.
Tre agenti scettici cercano di smontare i risultati.
Un modello di alto livello prende la decisione finale.
Questa è l'ingegneria del grafo (graph engineering).
Prima di continuare a leggere:
Segna questa guida così puoi tornare ai pattern del grafo quando inizierai a costruire i tuoi flussi di lavoro con Claude.
E segui
@Gyome1_ -
Analizzo Claude Code, gli agenti IA e i sistemi che trasformano un singolo modello in un flusso di lavoro ingegneristico affidabile.
Ho passato settimane a sezionare architetture reali di agenti, diagrammi di flusso e pattern di produzione per ricostruire l'ingegneria del grafo in un manuale pratico.
Invece di scrivere un prompt più lungo, progetti il percorso che le informazioni fanno attraverso il sistema:
lineare → fan-out → reduce → verify → synthesize
Ogni agente diventa un nodo con un compito delimitato. Ogni arco trasporta dati strutturati. I router decidono quale ramo eseguire. I verificatori respingono output deboli. I loop continuano finché il grafo non smette di trovare novità.
Il cambiamento importante è che Claude Code non deve più comportarsi come un'unica intelligenza che segue una gigantesca lista di controllo.
Può generare il codice di orchestrazione, far nascere una flotta di sottoagenti specializzati, instradare i loro output attraverso modelli diversi e assemblare il risultato finale solo dopo che le prove hanno superato la verifica.
I pattern di base non sono nuovi. Gli ingegneri del software usano DAG, pipeline, barriere, MapReduce e worker distribuiti da decenni.
Quello che è cambiato è ciò che ora risiede dentro ogni nodo.
Un nodo può cercare in un repository, fare audit di una migrazione, mettere in discussione una decisione architetturale, ispezionare fallimenti di test o sintetizzare cinquanta risultati indipendenti in un unico report citato.
Questa guida scompone l'intero sistema, dall'agente lineare più semplice fino a grafi a diamante, nodi router, pannelli di verifica antagonisti, loop convergenti, livelli di modello e flussi di lavoro dinamici generati direttamente dentro Claude Code.
Alla fine, sarai in grado di guardare un compito grande e smettere di chiederti:
"Quale prompt dovrei scrivere?"
1. L'INGEGNERIA DEL GRAFO INIZIA CON IL CONTO
L'ingegneria del grafo viene spesso presentata come un modo per eseguire più agenti.
Questa inquadratura perde la parte costosa.
Puoi lanciare venti agenti di Claude contro lo stesso repository e ricevere venti report sovrapposti, contesto ripetuto, conclusioni contrastanti e un conto API molto più alto.
Un grafo utile controlla dove avviene il calcolo, quale modello gestisce ogni decisione e come i risultati incerti si muovono attraverso il flusso di lavoro.
Immagina di chiedere a Claude Code di preparare una migrazione in produzione:
Ispeziona il repository, trova ogni dipendenza, proponi la migrazione, identifica i rischi, verifica il piano e scrivi il briefing finale.
Dentro un unico prompt, questo diventa un processo lungo e opaco. Claude cerca nel codice, memorizza i risultati nel contesto, progetta la migrazione, rivede il proprio piano e produce il report finale.
Quando il report fallisce, è difficile individuare la fonte del fallimento. Claude potrebbe aver perso un file, frainteso una dipendenza, dimenticato un dettaglio precedente o accettato un'ipotesi debole durante la verifica.
Ogni stadio può anche girare sullo stesso modello costoso, anche quando parti del compito riguardano semplice estrazione o ordinamento.
L'ingegneria del grafo apre quel flusso di lavoro e dà a ogni decisione un posto visibile.
I rami di ispezione vengono eseguiti contemporaneamente perché usano lo stesso compito delimitato e non dipendono l'uno dall'output dell'altro.
I loro risultati si incontrano in una fase di riduzione, dove i duplicati scompaiono e le prove vengono compresse in un dataset più piccolo.
Un router legge poi la gravità. I cambiamenti di routine passano attraverso una revisione leggera. I risultati ad alto rischio ricevono un'analisi più approfondita da diversi revisori indipendenti prima di raggiungere il modello finale.
Il risultato è un flusso di lavoro in cui latenza, costo del modello, dimensione del contesto e profondità di verifica sono controllati attraverso la struttura del grafo.
Un nodo dovrebbe prendere una sola decisione
Un nodo utile ha una responsabilità delimitata.
Trova ogni chiamata all'API deprecata. Classifica ogni rischio di migrazione come basso, medio o alto. Testa il piano di rollback per i casi di fallimento.
Ogni nodo ha bisogno di un input chiaro, un output definito e una superficie decisionale limitata.
Un nodo che cerca nel repository, stima l'impatto aziendale, progetta la soluzione e scrive la raccomandazione contiene ancora diverse fasi nascoste. Il debug rimane difficile perché il ragionamento intermedio è sepolto dentro una singola chiamata al modello.
Confini più piccoli rivelano dove le prove sono entrate nel sistema e dove il loro significato è cambiato.
Un arco dovrebbe trasportare prove
Un arco rappresenta i dati richiesti dal nodo successivo.
Lo scanner può restituire un oggetto prevedibile:
1{2 "file": "src/auth/session.ts",3 "lines": [84, 119],4 "dependency": "legacySessionClient",5 "confidence": 0.94,6 "evidence": "Entrambi i punti di chiamata dipendono dal metodo deprecato refresh."7}
Il classificatore di rischio ora riceve gli stessi campi per ogni risultato. Può respingere risultati incompleti, raggruppare file correlati e instradare prove incerte verso un'altra revisione.
Gli schemi riducono la deriva interpretativa tra i nodi. I paragrafi liberi costringono ogni agente a valle a ricostruire il significato dell'agente precedente. Dopo diverse fasi, piccole ambiguità possono alterare la conclusione finale.
L'output strutturato mantiene le prove stabili mentre si muovono attraverso il grafo.
Alcuni nodi sono codice ordinario
Supponiamo che otto agenti di ricerca restituiscano ottanta risultati.
Il flusso di lavoro deve combinare array, scartare risposte vuote, rimuovere duplicati e ordinare gli elementi rimanenti.
Queste operazioni hanno risposte deterministiche:
1const uniqueFindings = [2 ...new Map(3 results4 .flatMap(batch => batch ?? [])5 .map(item => [`${item.file}:${item.lines.join("-")}`, item])6 ).values()7];
Una trasformazione JavaScript gestisce questo istantaneamente e produce lo stesso output a ogni esecuzione. Inviare lo stesso compito a un altro modello aggiunge costo in token e crea un altro posto dove le prove possono scomparire.
I nodi modello appartengono intorno a ricerca, classificazione, confronto, revisione e sintesi. Il codice può gestire validazione, deduplicazione, ordinamento, regole di routing esplicite e altre trasformazioni prevedibili.
Questa divisione diventa il fondamento del grafo.
Ogni chiamata al modello dovrebbe corrispondere a una decisione che richiede genuinamente giudizio.
2. IL DIAMANTE: COME I GRAFI DI AGENTI REALI SPOSTANO IL LAVORO
La maggior parte dei grafi di agenti seri finisce per assumere la stessa forma.
Un compito inizia con un ambito condiviso, si divide tra diversi worker indipendenti, attende i loro output, comprime le prove e passa il risultato a una decisione finale.
Quella forma è il diamante.
Il lato sinistro è il fan-out.
Il punto centrale dove tutti i rami si incontrano è la barriera.
Il lato destro è il fan-in.
Questo pattern appare ovunque una volta che un compito diventa troppo grande per un'unica finestra di contesto.
Un audit del repository può essere suddiviso per sottosistema. Un report di mercato può essere suddiviso per fonte. Un compito di ricerca può essere suddiviso per ipotesi. Una revisione di migrazione può essere suddivisa tra utilizzo API, modifiche al database, rischio di deployment e copertura dei test.
Ogni worker riceve lo stesso ambito con un compito più ristretto.
Il grafo poi attende che siano tornate abbastanza prove utili.
Il fan-out dovrebbe creare lavoro indipendente
Un ramo appartiene al fan-out quando può iniziare dall'input condiviso e produrre un risultato utile senza leggere l'output di un altro ramo.
Per un audit di sicurezza, la suddivisione potrebbe essere così:
Claude Code può lanciare queste chiamate concorrentemente con una primitiva di barriera come parallel()
1const findings = await parallel(2 checks.map(check => async () => {3 return agent({4 task: check.task,5 context: auditScope,6 schema: FINDING_SCHEMA7 });8 })9);
L'orchestrazione rimane in JavaScript ordinario. Ogni ramo riceve un compito delimitato e restituisce un oggetto validato.
Il risultato arriva come una collezione di output che possono essere filtrati, ispezionati e passati alla fase successiva.
Un fan-out grande ha comunque bisogno di una ragione dietro ogni ramo.
Dividere un compito vago in dodici agenti quasi identici spesso produce risultati ripetuti con una formulazione leggermente diversa. Il parallelismo utile deriva da fonti, prospettive, regioni di codice o ipotesi distinte.
La barriera crea un punto decisionale
Una barriera mette in pausa la fase successiva fino a quando i rami richiesti non sono stati completati.
Quella pausa è importante perché alcune decisioni dipendono dall'insieme completo.
Un nodo di classificazione non può identificare la vulnerabilità più importante mentre metà del repository è ancora in fase di ispezione. Un modello di sintesi non può scrivere un piano di migrazione completo mentre la revisione del deployment è ancora in esecuzione.
Alla barriera, il grafo ha la possibilità di ispezionare lo stato dell'esecuzione:
1const completed = findings.filter(Boolean);23if (completed.length < MIN_REQUIRED_RESULTS) {4 throw new Error("Insufficient audit coverage");5}
È qui che i fallimenti parziali diventano visibili.
Un worker potrebbe andare in timeout, restituire dati malformati o non produrre risultati. Filtrare i valori null mantiene l'esecuzione in corso, ma i flussi di lavoro di produzione di solito hanno bisogno di una politica più chiara:
- quanti rami riusciti sono richiesti;
- quali rami sono obbligatori;
- se un nodo fallito dovrebbe riprovare;
- se il risultato finale dovrebbe essere marcato come incompleto.
La barriera è quindi parte del modello di affidabilità, non solo un meccanismo di sincronizzazione.
Riduci prima di sintetizzare
Dopo il fan-out, il grafo può contenere dozzine di risultati sovrapposti.
Inviarli tutti direttamente a un modello di alto livello crea un contesto grande, ripete le stesse prove e rende più difficile distinguere i dettagli importanti.
La fase di riduzione prepara le prove.
Alcune riduzioni possono avvenire nel codice:
1const unique = deduplicateByKey(2 completed.flatMap(result => result.findings),3 finding => `${finding.file}:${finding.line}:${finding.type}`4);
Il livello successivo può richiedere giudizio:
1const curated = await agent({2 task: `3 Raggruppa i risultati correlati.4 Conserva tutti i riferimenti a file e righe.5 Classifica ogni gruppo per impatto operativo.6 Restituisci la prova più forte per ogni conclusione.7 `,8 input: unique,9 schema: CURATED_FINDINGS_SCHEMA10});
La riduzione controlla cosa raggiunge il modello finale.
Un buon riduttore rimuove la ripetizione preservando le prove. Un riduttore aggressivo può comprimere diversi rischi distinti in un unico riassunto vago e cancellare i dettagli necessari per la verifica.
Il pattern più sicuro mantiene un collegamento tra ogni affermazione ridotta e i suoi elementi di origine.
1{2 "risk": "Il refresh della sessione potrebbe fallire dopo la migrazione",3 "severity": "alto",4 "sourceFindingIds": ["AUTH-04", "API-11", "TEST-07"],5 "evidence": [6 "Tre servizi chiamano il metodo deprecato refresh",7 "Non esiste un percorso di fallback",8 "Manca la copertura dell'integrazione"9 ]10}
Ora il nodo di sintesi riceve un dataset più piccolo senza perdere la tracciabilità.
3. L'AFFIDABILITÀ FA PARTE DEL GRAFO
Un grafo può finire rapidamente e produrre comunque una risposta sbagliata.
Una volta che diversi agenti iniziano a cercare, classificare e rivedere lo stesso compito, il problema principale diventa il controllo.
Il sistema ha bisogno di regole per decidere quali risultati meritano un lavoro più approfondito, quali output dovrebbero essere respinti e quando il flusso di lavoro ha cercato abbastanza.
Instrada per rischio
Un nodo router legge l'output strutturato e sceglie il ramo successivo.
La classificazione può venire da un modello, mentre il ramo stesso rimane esplicito nel codice.
1const route =2 finding.severity === "high"3 ? runFullAudit(finding)4 : runQuickReview(finding);
Questo mantiene la revisione costosa concentrata intorno ai risultati con impatto significativo.
Un router utile si basa su campi che il grafo può ispezionare: gravità, confidenza, sistemi interessati, esposizione finanziaria o la presenza di prove mancanti.
Aggiungi verifica indipendente
Un agente che rivede la propria conclusione porta le stesse ipotesi in entrambe le fasi.
Un grafo più forte invia i risultati importanti a diversi revisori con compiti differenti.
I revisori non dovrebbero ricevere istruzioni per migliorare la risposta originale. Il loro compito è cercare ragioni per cui potrebbe essere incompleta o sbagliata.
Il grafo può richiedere accordo prima che un risultato proceda:
1const accepted = votes.filter(vote => vote.approve).length >= 2;
Isola gli agenti che modificano il codice
Agenti di codifica paralleli possono interferire tra loro quando modificano la stessa directory di lavoro.
Un agente potrebbe sovrascrivere un file mentre un altro lo sta ancora leggendo. I test potrebbero essere eseguiti su una miscela di modifiche non correlate.
I worktree Git danno a ogni ramo la propria copia del repository.
1main repository2 │3 ├→ worktree/auth-fix4 ├→ worktree/db-migration5 └→ worktree/test-repair
Ogni agente può modificare file ed eseguire test all'interno del proprio ambiente. Un nodo successivo confronta le patch, controlla i conflitti e seleziona cosa dovrebbe essere unito.
Questo trasforma l'isolamento in parte del grafo, piuttosto che un passaggio manuale di pulizia.
Lascia che la scoperta converga
Alcuni compiti non possono essere completati in un unico passaggio.
Un audit del repository potrebbe scoprire una dipendenza che punta verso un altro pacchetto. Quel pacchetto potrebbe rivelare un altro punto di chiamata. Il grafo ha bisogno di un modo controllato per continuare a cercare senza ripetere tutto ciò che ha già visto.
1const seen = new Set();2let dryRounds = 0;34while (dryRounds < 2) {5 const findings = await discoverNext([...seen]);6 const fresh = findings.filter(item => !seen.has(item.id));78 fresh.forEach(item => seen.add(item.id));9 dryRounds = fresh.length === 0 ? dryRounds + 1 : 0;10}
Il dettaglio importante è deduplicare rispetto a ogni elemento già visto.
Deduplicare solo rispetto ai risultati confermati permette agli elementi respinti o incerti di tornare al passaggio successivo e consumare lo stesso lavoro di nuovo.
Il ciclo si ferma dopo diversi giri a vuoto, un budget fisso o un numero massimo di iterazioni. I grafi di produzione di solito hanno bisogno di tutti e tre.
Abbina il modello al nodo
Non tutti i nodi hanno bisogno del modello più potente disponibile.
Estrazione, classificazione di base e ricerche ristrette possono spesso girare su un livello più veloce. Revisione dell'architettura, verifica antagonistica e sintesi finale possono giustificare un modello più forte.
Il tiering dei modelli diventa un'altra proprietà del grafo.
Il budget è determinato da quanti nodi girano, quanto spesso i loop si ripetono, quanto contesto attraversa ogni arco e quale modello gestisce ogni fase.
Un grafo con venti chiamate di ricerca economiche può comunque costare più di una singola chiamata potente. L'architettura ha bisogno di un budget di token prima di aver bisogno di un altro ramo.
Sapere quando smettere di disegnare
I compiti piccoli raramente hanno bisogno di router, pannelli di voto, worktree e loop di convergenza.
Il sovraccarico del grafo include codice di orchestrazione, schemi, tentativi, logging, storage intermedio e più stati di fallimento da debuggare.
Un flusso di lavoro lineare è di solito sufficiente quando un modello può contenere il contesto rilevante, il compito ha pochi rami indipendenti e il costo di una risposta sbagliata è basso.
L'ingegneria del grafo diventa utile quando il compito guadagna lavoro parallelo, decisioni costose, grandi set di prove o requisiti di verifica significativi.
Il flusso di lavoro completo potrebbe alla fine assomigliare a questo:
Il valore deriva dal rendere visibile il movimento del lavoro.
Ogni nodo ha una responsabilità limitata. Ogni arco trasporta prove strutturate. Ogni ramo ha una ragione di esistere. Ogni ciclo ha una condizione di arresto.
A quel punto, Claude Code non sta più eseguendo una lunga istruzione.
Sta eseguendo un sistema ingegnerizzato.
