Graphify per Claude Code: trasformare il repository in un grafo interrogabile

Graphify Claude Code: trasformare un repository in un grafo interrogabile

Un repository con 800,000 righe di codice può contenere la risposta a una domanda apparentemente semplice in sei punti diversi: un modulo Terraform, una migrazione del database, un client generato, un documento OpenAPI, un manifesto di deployment e un runbook scritto due anni fa.

Claude Code può cercare e leggere questi file, ma il lavoro su scala di repository è spesso limitato dalla rapidità con cui l'agente riesce a scoprire le relazioni tra di essi. Una ricerca testuale di customer_id trova le occorrenze. Non spiega automaticamente che:

• customer_id è dichiarato in una migrazione del database,
• esposto da uno schema API,
• mappato in un modello ORM,
• copiato nel payload di un evento,
• utilizzato da un worker in background,
• e menzionato in una procedura di rollback in produzione.

Graphify affronta questo problema convertendo il materiale del repository in un grafo di conoscenza: le entità diventano nodi, i riferimenti e le dipendenze diventano archi e Claude Code può interrogare questa struttura per ottenere ulteriore contesto.

La precisazione importante è che un grafo non è una seconda fonte di verità creata per magia. È un'interpretazione indicizzata del repository. Il suo valore dipende dalla copertura dei parser, dalla regolarità degli aggiornamenti, dalle autorizzazioni e dalla capacità delle relazioni risultanti di rispondere a domande concrete di ingegneria del software.

Cosa aggiunge Graphify a Claude Code

Claude Code dispone già di diversi strumenti utili per comprendere un progetto:

• Lettura diretta dei file
• rg e altre ricerche tramite shell
• Cronologia e diff di Git
• Istruzioni del progetto in CLAUDE.md
• Skill per flussi di lavoro ripetibili
• Server MCP per strumenti e dati esterni

Graphify aggiunge una diversa modalità di accesso: il recupero di informazioni orientato alle relazioni.

Una ricerca convenzionale chiede:

Dove compare questo simbolo?

Una query sul grafo chiede:

Quali servizi dipendono da questo schema, quale infrastruttura distribuisce quei servizi e quali documenti descrivono le conseguenze operative?

Questa distinzione è importante quando l'attività coinvolge ambiti di responsabilità o formati di file diversi.

Un grafo tipico può contenere nodi come:

Gli archi possono rappresentare relazioni come:

• imports
• calls
• implements
• extends
• reads_from
• writes_to
• publishes
• consumes
• deploys
• configured_by
• documented_by
• owned_by
• depends_on

Il vocabolario esatto di nodi e archi dipende dagli indicizzatori e dalla configurazione attuali di Graphify. Considera lo schema del grafo come una parte del prodotto da esaminare, non come un presupposto. Prima di costruire prompt attorno a una relazione come publishes, verifica che la versione installata la produca effettivamente.

Installazione di Graphify per Claude Code

Graphify è un progetto in sviluppo attivo, quindi le modalità di installazione e i nomi dei comandi di avvio potrebbero cambiare. Parti dal repository e usa il comando di installazione documentato per la versione che intendi adottare:

git clone https://github.com/Graphify-Labs/graphify.git
cd graphify

Se utilizzi un pacchetto pubblicato, è preferibile usare il comando del gestore di pacchetti documentato dal progetto anziché copiarlo da un vecchio articolo di blog. Dopo l'installazione, accerta tre aspetti prima di indicizzare un monorepo di grandi dimensioni:

graphify --help
graphify version
graphify config --help

I comandi sopra illustrano i controlli da eseguire; usa l'eseguibile e i sottocomandi disponibili nella versione installata.

Una prima esecuzione sicura dovrebbe essere effettuata su un piccolo repository di prova:

mkdir -p /tmp/graphify-fixture
cd /tmp/graphify-fixture

git init
printf 'def charge(order):\n    return order.total\n' > billing.py
printf 'from billing import charge\n' > worker.py

graphify index .

L'indicizzazione iniziale esegue normalmente una combinazione di individuazione, parsing, estrazione delle relazioni e persistenza del grafo. Su un repository reale, esamina la configurazione generata e il percorso di archiviazione prima di integrarla nella CI. Devi sapere se l'indice è:

• Locale o ospitato
• Incrementale o ricostruito integralmente
• Memorizzato in un database, in file o in un archivio incorporato
• Sicuro da generare contemporaneamente a un altro indicizzatore
• In grado di escludere segreti, artefatti di build e directory di dipendenze di terze parti

Per l'integrazione con Claude Code, Graphify deve essere esposto tramite il meccanismo di integrazione supportato dal progetto, generalmente MCP. Un file locale .mcp.json potrebbe avere questo aspetto:

{
  "mcpServers": {
    "graphify": {
      "command": "graphify",
      "args": ["mcp", "--project", "."],
      "env": {
        "GRAPHIFY_INDEX": ".graphify/index"
      }
    }
  }
}

Non considerare questo specifico sottocomando valido in ogni caso. Verifica il punto di ingresso MCP con:

graphify mcp --help

Quindi verifica il server da Claude Code:

/mcp

Dovresti vedere il server Graphify e gli strumenti disponibili. I nomi degli strumenti e la sintassi delle query dipendono dalla versione. La verifica utile è operativa: chiedi a Claude Code di elencare gli strumenti del grafo, eseguire una query circoscritta e indicare quale revisione del repository è stata indicizzata.

Un errore comune è avviare Claude Code dalla directory sbagliata. I percorsi relativi del progetto in .mcp.json, nei file di esclusione e nella configurazione di Graphify vengono risolti in base alla directory di lavoro del processo del server, che non coincide necessariamente con quella che avevi in mente.

Le relazioni che contano nella pratica

Il grafo è particolarmente utile quando rende visibili relazioni che sarebbe laborioso ricostruire dal testo.

Tracciabilità dal codice ai dati

Supponiamo che una migrazione rinomini accounts.status a accounts.lifecycle_state. Una ricerca testuale può individuare i riferimenti, ma un grafo può organizzare l'insieme degli elementi interessati:

table accounts
  -> column lifecycle_state
  -> migration 2025_04_rename_status
  -> model Account
  -> repository AccountRepository
  -> API response AccountSummary
  -> dashboard query active_accounts

Questo offre a Claude Code un punto di partenza migliore per la revisione di una migrazione. Dopo che il grafo ha individuato i probabili elementi dipendenti, può esaminare i file effettivi.

Topologia dei servizi e dell'infrastruttura

Le relazioni infrastrutturali sono particolarmente preziose nei monorepo in cui il codice applicativo e quello di deployment risiedono insieme:

service payments-api
  -> container image payments-api
  -> Kubernetes deployment payments
  -> reads secret PAYMENTS_DATABASE_URL
  -> writes queue payment-events
  -> consumed by reconciliation-worker

Questo aiuta a rispondere a domande come:

• Quale deployment deve cambiare se cambia una porta?
• Che cosa utilizza questa coda?
• Quali servizi condividono questo database?
• Quale configurazione è specifica dell'ambiente?
• Quale risorsa Terraform crea la dipendenza?

Graphify non può dedurre perfettamente il comportamento in esecuzione dai file statici. Il rilevamento dinamico dei servizi, la reflection, la configurazione generata e l'indirezione tramite variabili d'ambiente possono lasciare lacune. Usa i risultati della topologia come mappa dell'impatto, quindi verifica gli archi critici nella configurazione di deployment e di esecuzione.

Dalla documentazione all'implementazione

La documentazione è spesso scollegata dalla ricerca nel codice perché la relazione è semantica anziché sintattica. Un runbook può fare riferimento al “processore di regolamento”, mentre nel repository è chiamato reconciliation-worker.

Se Graphify collega i riferimenti della documentazione alle entità del codice o dell'infrastruttura, Claude Code può rispondere a domande operative riducendo la consultazione manuale:

"Where is the rollback procedure for the component that consumes payment-events?"

La risposta è affidabile solo se i nomi presenti nella documentazione sono mappati correttamente. Una terminologia obsoleta crea archi plausibili ma errati, il che è più pericoloso di un'evidente ricerca senza risultati.

Graphify, skill e MCP sono livelli diversi

Graphify dovrebbe integrare i punti di estensione esistenti di Claude Code anziché sostituirli.

Un'architettura utile è la seguente:

1. Graphify individua entità e dipendenze candidate.
2. Claude Code usa questi risultati per selezionare i file.
3. Gli strumenti nativi per i file verificano l'implementazione attuale.
4. Una skill applica la procedura di revisione o modifica del team.
5. Test, linter e controlli di deployment forniscono le prove finali.

Per esempio, una skill per la revisione delle migrazioni potrebbe risiedere in .claude/skills/review-migration/SKILL.md:

# Review Database Migration

When reviewing a migration:

1. Identify renamed, removed, or changed columns.
2. Query Graphify for code, schema, event, and infrastructure dependents.
3. Read each high-confidence dependent from the working tree.
4. Check backward compatibility for deployed application versions.
5. Run the repository migration and contract tests.
6. Report uncertain graph relationships separately from verified findings.

La skill definisce il flusso di lavoro. Graphify fornisce il contesto delle relazioni. MCP costituisce il livello di trasporto e il confine degli strumenti.

Questa separazione è importante. Inserire tutta la conoscenza del grafo in una skill produrrebbe istruzioni statiche che invecchiano male. Inserire tutte le regole del flusso di lavoro in Graphify renderebbe l'indicizzatore responsabile di decisioni che non può prendere in modo affidabile.

Gestire il costo e l'aggiornamento dell'indice

L'indicizzazione ha un costo in termini di risorse di calcolo, spazio su disco, latenza e complessità operativa. Il costo non si limita alla prima scansione. I repository di grandi dimensioni richiedono anche attività di aggiornamento quando cambiano i branch, vengono ricostruiti i file generati o vengono invalidati i grafi delle dipendenze.

Inizia dalle esclusioni:

# .graphifyignore
.git/
node_modules/
vendor/
dist/
build/
coverage/
tmp/
*.min.js
*.map
.env
*.pem

La sintassi potrebbe differire da quella di .gitignore, quindi verifica come Graphify gestisce i file di esclusione. Escludi esplicitamente credenziali ed esportazioni sensibili anche se Git le ignora già. Uno strumento che indicizza un file può esporne il contenuto tramite una query.

Adotta una strategia di indicizzazione per fasi:

• Indicizza il codice sorgente dell'applicazione, gli schemi, l'infrastruttura e la documentazione mantenuta aggiornata.
• Escludi gli output generati, a meno che non costituiscano l'artefatto di riferimento.
• Crea un indice completo in CI o tramite un job pianificato.
• Aggiorna in modo incrementale l'indice di un branch, ove supportato.
• Registra il commit sorgente accanto ai metadati del grafo.
• Ricostruisci l'indice dopo modifiche al parser o alla configurazione.

La revisione del codice sorgente deve essere visibile all'agente. Una risposta strutturata così è molto più sicura di un elenco privo di informazioni contestuali:

{
  "query": "dependents of table accounts",
  "indexed_revision": "9f31a7c",
  "generated_at": "2025-05-14T10:22:11Z",
  "results": [
    {
      "entity": "AccountRepository",
      "relationship": "reads_from",
      "target": "accounts",
      "confidence": "high",
      "path": "src/accounts/repository.py"
    }
  ]
}

Quando Claude Code modifica un albero di lavoro dopo l'ultima indicizzazione, i risultati del grafo rappresentano un contesto storico. I file attuali hanno la precedenza. In pratica, dico all'agente di includere indexed_revision nel proprio ragionamento e di verificare nuovamente ogni affermazione derivata dal grafo confrontandola con l'albero di lavoro.

Accuratezza, privacy e limiti in produzione

Un grafo può far apparire autorevoli informazioni incomplete. Esistono diverse modalità di errore da prevedere:

• Le importazioni dinamiche e la reflection non vengono rilevate.
• Gli script shell nascondono relazioni dietro l'espansione delle variabili.
• I client generati rendono poco visibile lo schema sorgente.
• I collegamenti nella documentazione usano alias che il parser non riconosce.
• I file eliminati rimangono finché non viene eseguita una pulizia o una ricostruzione.
• Viene interrogato l'indice di un branch mentre l'agente lavora su un altro branch.
• I moduli infrastrutturali vengono interpretati senza i valori specifici dell'ambiente.

Nei flussi di lavoro in produzione, rendi visibili il livello di confidenza e la provenienza ogni volta che è possibile. Una relazione senza percorso del file, revisione o metodo di estrazione è difficile da verificare.

La privacy richiede altrettanta attenzione. I grafi dei repository possono rivelare:

• Nomi di servizi interni
• Modelli dei dati relativi a clienti e pagamenti
• Topologia della rete
• Segreti tramite nomi di file o riferimenti nella configurazione
• Dipendenze sensibili sotto il profilo delle vulnerabilità
• Documentazione proprietaria

Mantieni gli indici sensibili in locale o all'interno dello stesso perimetro di fiducia del repository. Configura MCP secondo il principio del privilegio minimo, escludi il materiale contenente segreti ed evita di inviare i contenuti del grafo a un servizio ospitato, a meno che l'organizzazione non abbia approvato quel flusso di dati. La capacità di Claude Code di interrogare un grafo non modifica i requisiti di controllo degli accessi del repository.

La popolarità, inoltre, non equivale all'affidabilità. Un progetto può attirare notevole attenzione e avere comunque una copertura dei parser immatura, schemi del grafo instabili, garanzie di aggiornamento limitate o un comportamento inadeguato di fronte a frequenti modifiche su scala monorepo. Valutalo con un corpus di fixture tratto dal tuo repository:

• Identifica le importazioni e le dipendenze tra servizi note?
• Rimuove le relazioni eliminate?
• L'indicizzazione incrementale converge al risultato di una ricostruzione da zero?
• Gli utenti possono distinguere i risultati non aggiornati e quelli con un basso livello di confidenza?
• Il server MCP segnala chiaramente l'errore quando l'indice non è disponibile?
• Le query sono abbastanza veloci per il lavoro interattivo dell'agente?
• Puoi riprodurre l'indice in CI?

Non rendere Graphify un prerequisito obbligatorio per ogni azione dell'agente. È essenziale una modalità degradata che ripieghi sulla normale ricerca nei file.

Un modello pratico di adozione

Inizia con un flusso di lavoro in cui individuare le relazioni è costoso e gli errori sono visibili, come modifiche alle API, migrazioni del database o refactoring dell'infrastruttura.

Misura risultati utili anziché le dimensioni del grafo:

• Tempo necessario per identificare i componenti interessati
• Numero di componenti dipendenti non rilevati durante la revisione
• Percentuale di relazioni non aggiornate o errate
• Tempo di indicizzazione dopo commit tipici
• Errori nelle query e frequenza del ricorso alla modalità alternativa
• Dati aggiuntivi esposti al modello

Usa Sonnet 4.6 per indagini estese sul repository quando conta la profondità del ragionamento, Haiku 4.5 per classificazioni leggere o attività di consultazione ripetute e Fable 5, con un contesto più ampio, quando il flusso di lavoro del progetto con contesto 1M trae un beneficio concreto dall'inclusione di un ampio insieme di elementi di riscontro. La scelta del modello non corregge un grafo di scarsa qualità. Un modello più piccolo con relazioni precise e aggiornate può essere più utile di un modello più grande che riceve un dump dell'indice senza filtri.

Il modello pratico di prompt indica esplicitamente la provenienza:

Use Graphify to identify likely dependents of the `accounts.lifecycle_state`
column. For every result, include its path, indexed revision, relationship,
and confidence. Then read the current files and discard relationships that
do not exist in the working tree. Do not treat graph results as proof.

Quella frase finale non è una formalità. Impedisce che un livello di contesto non aggiornato diventi un'autorità indiscussa.

Indicazioni pratiche

• Il valore principale di Graphify è il recupero delle relazioni tra codice, schemi, infrastruttura e documentazione.
• Installa una versione specifica dello strumento, esamina i suoi comandi CLI e MCP effettivi e provalo su una fixture prima di indicizzare un monorepo.
• Mantieni Graphify responsabile del contesto del repository; usa le skill di Claude Code per procedure di sviluppo ripetibili.
• Includi la revisione dell'indice, la provenienza e il livello di confidenza nelle risposte del grafo.
• Escludi segreti, contenuti generati superflui e contenuti di terze parti non necessari.
• Tratta i risultati del grafo come indicazioni da verificare rispetto all'albero di lavoro attuale.
• Verifica l'indicizzazione incrementale, la gestione delle eliminazioni, l'isolamento dei branch e il funzionamento in modalità degradata prima dell'adozione in produzione.
• La popolarità può giustificare una valutazione, ma solo l'accuratezza specifica per il repository e il comportamento operativo giustificano la scelta di farvi affidamento.