{"id":4698,"date":"2026-06-02T23:16:45","date_gmt":"2026-06-02T22:16:45","guid":{"rendered":"https:\/\/www.fullo.net\/blog\/?p=4698"},"modified":"2026-06-02T23:16:48","modified_gmt":"2026-06-02T22:16:48","slug":"come-claude-code-lavora-nelle-grandi-codebase","status":"publish","type":"post","link":"https:\/\/www.fullo.net\/blog\/2026\/06\/02\/come-claude-code-lavora-nelle-grandi-codebase\/","title":{"rendered":"Come Claude Code lavora nelle grandi codebase"},"content":{"rendered":"\n

mmagina di assumere una persona molto in gamba e di lasciarla da sola dentro l’archivio di un’azienda enorme: stanze su stanze, faldoni ovunque, documenti di vent’anni fa accanto a quelli di stamattina. Quanto sar\u00e0 brava non dipende solo da quanto \u00e8 sveglia. Dipende soprattutto da come hai organizzato l’archivio, dai cartelli che hai appeso e dagli strumenti che le hai messo in mano.<\/p>\n\n\n\n

\u00c8 esattamente la situazione di Claude Code dentro una grande codebase. L’articolo originale raccoglie i pattern ricorrenti nelle aziende che lo usano bene su larga scala. Qui te lo racconto con parole semplici, esempi e qualche disegno.<\/p>\n\n\n\n\n\n\n\n

\"\"<\/a><\/figure>\n\n\n\n

Come si muove dentro al codice<\/h2>\n\n\n\n

Claude Code esplora il codice come farebbe uno sviluppatore in carne e ossa: apre cartelle, legge file, usa\u00a0grep<\/code>\u00a0per cercare ci\u00f2 che gli serve e segue i riferimenti da un file all’altro. Questa parte, la\u00a0ricerca e la lettura dei file<\/strong>, avviene sulla tua macchina, e non c’\u00e8 alcun “indice” del codice da costruire, mantenere o caricare su un server esterno.<\/p>\n\n\n\n

\n

? Attenzione<\/strong>

Si dice spesso che Claude Code “lavora in locale”. \u00c8 una mezza verit\u00e0 da maneggiare con cura:\u00a0locale \u00e8 l’agente che cerca e legge i file<\/strong>;\u00a0remota \u00e8 l’elaborazione<\/strong>. Per ragionare sul codice, le porzioni rilevanti vengono inviate via API (Application Programming Interface<\/em>, l’interfaccia con cui due programmi si parlano) ai server di Anthropic, dove gira il modello. Il codice\u00a0a riposo<\/em>\u00a0resta da te; il codice\u00a0nel momento del ragionamento<\/em>\u00a0viaggia.<\/p>\n<\/blockquote>\n\n\n\n

Serve per\u00f2 chiarire un equivoco comune, perch\u00e9 sotto la sigla “RAG” finiscono cose molto diverse. RAG significa\u00a0Retrieval-Augmented Generation<\/em>\u00a0e si compone di tre pezzi che possono stare ciascuno in locale o in remoto: il modello di\u00a0embedding<\/strong>\u00a0(che trasforma il codice in vettori), il\u00a0database vettoriale<\/strong>\u00a0dove quei vettori vivono, e l’LLM<\/strong>\u00a0che genera la risposta. A seconda di dove metti questi pezzi ottieni sistemi profondamente diversi.<\/p>\n\n\n\n

\n

? Due famiglie di RAG<\/strong><\/p>\n\n\n\n

Un\u00a0RAG fully-local<\/strong>\u00a0(embedding, database vettoriale e un LLM open-weight tutti sulla tua macchina) fa\u00a0davvero<\/em>\u00a0tutto in casa: il codice non esce mai. Un\u00a0RAG API-driven<\/strong>\u00a0usa embedding o LLM remoti: indicizza in locale, ma poi manda fuori i chunk recuperati, esponendo spesso\u00a0pi\u00f9<\/em>\u00a0codice di Claude Code, perch\u00e9 ha indicizzato tutto in anticipo.<\/p>\n<\/blockquote>\n\n\n\n

Distinguere questi due assi \u00e8 la chiave per non confondersi. Il difetto classico del RAG,\u00a0l’indice che invecchia<\/strong>, non dipende dal locale contro il remoto. Dipende dal fatto che l’indice \u00e8\u00a0precalcolato<\/em>: appena committi codice nuovo, l’indice \u00e8 vecchio, che sia su un database vettoriale nella tua sala server o su un servizio in cloud. La ricerca agentica evita questo perch\u00e9 rilegge la versione viva ogni volta. Stiamo quindi rispondendo a\u00a0due domande diverse<\/strong>, che conviene tenere separate:<\/p>\n\n\n\n

\n \n <\/rect>\n Due domande diverse, non una<\/text>\n \n \n <\/rect>\n <\/line>\n <\/line>\n \n \n INFERENZA LOCALE<\/text>\n INFERENZA REMOTA<\/text>\n ? dove gira il modello? (il codice esce o no)<\/text>\n \n \n RICERCA DAL VIVO<\/text>\n INDICE PRECALCOLATO<\/text>\n \n \n agente con LLM<\/text>\n open-weight locale<\/text>\n privacy alta \u00b7 capacit\u00e0 limitata<\/text>\n \n \n <\/rect>\n CLAUDE CODE<\/text>\n cerca vivo in locale,<\/text>\n ragiona in remoto<\/text>\n \n \n <\/rect>\n RAG FULLY-LOCAL<\/text>\n DB vettoriale +<\/text>\n LLM locale \u00b7 nulla esce<\/text>\n \n \n <\/rect>\n RAG API-DRIVEN<\/text>\n embedding\/LLM remoti \u00b7<\/text>\n indice che invecchia<\/text>\n <\/svg>\n
L’asse orizzontale \u00e8 la
privacy<\/b> (il codice esce?); quello verticale \u00e8 la freschezza<\/b> (l’indice invecchia?). Sono indipendenti: un RAG fully-local protegge i dati ma il suo indice invecchia comunque.<\/figcaption>\n <\/figure>\n\n\n\n

Ne esce un quadro pi\u00f9 giusto. Se la tua priorit\u00e0 \u00e8 la\u00a0riservatezza assoluta<\/strong>, un RAG fully-local vince su Claude Code, ma paghi un prezzo: in locale non puoi far girare i modelli di frontiera, quindi rinunci a buona parte della capacit\u00e0 di ragionamento. Se la priorit\u00e0 \u00e8\u00a0freschezza e qualit\u00e0 del ragionamento<\/strong>, la ricerca agentica di Claude Code evita l’indice che invecchia e usa modelli potenti, ma il codice rilevante deve uscire. Ogni architettura \u00e8 un compromesso tra riservatezza e capacit\u00e0: la scelta giusta dipende da cosa conta di pi\u00f9 nel tuo contesto.<\/p>\n\n\n\n

E la sostenibilit\u00e0?<\/h3>\n\n\n\n

C’\u00e8 un terzo asse che il dibattito locale-contro-remoto quasi sempre dimentica: l’impronta energetica e ambientale<\/strong>. E qui l’intuito inganna. “Locale” suona pi\u00f9 sobrio, “cloud” suona dispendioso, ma spesso \u00e8 il contrario.<\/p>\n\n\n\n

\n

? Locale e remoto<\/strong><\/p>\n\n\n\n

Un grande datacenter ottimizzato raggiunge valori di efficienza (il\u00a0PUE<\/strong>,\u00a0Power Usage Effectiveness<\/em>, cio\u00e8 il rapporto tra energia totale ed energia utile al calcolo) vicini a 1,1-1,2, sfrutta hardware condiviso ad altissimo utilizzo e pu\u00f2 attingere a energia a basse emissioni. Una GPU (Graphics Processing Unit<\/em>, il processore grafico usato anche per l’AI) che gira un modello locale su una workstation tipicamente lavora a utilizzo basso, senza recupero di calore, su una rete elettrica qualsiasi: per token, pu\u00f2 emettere\u00a0di pi\u00f9<\/em>.<\/p>\n<\/blockquote>\n\n\n\n

Ma anche qui non c’\u00e8 una risposta secca, e vale la pena tenere insieme pi\u00f9 fattori prima di concludere. Conta la dimensione del modello<\/strong> (un piccolo modello locale per un compito semplice pu\u00f2 battere l’invio di tutto a un modello di frontiera enorme), l’intensit\u00e0 di carbonio della rete elettrica<\/strong> nel luogo e nell’ora in cui il calcolo avviene, l’energia incorporata<\/strong> nell’hardware che acquisti contro quella di infrastruttura condivisa, e, non ultimo, il numero di tentativi<\/strong>: un modello pi\u00f9 capace che azzecca la risposta al primo colpo pu\u00f2 consumare meno di uno debole che ci riprova cinque volte. La domanda utile, allora, \u00e8 un’altra: qual \u00e8 il modello pi\u00f9 piccolo che svolge davvero il compito, alimentato dall’energia pi\u00f9 pulita disponibile, con il minor numero di ripetizioni?<\/em> \u00c8 lo stesso principio del “do less, better” applicato al calcolo.<\/p>\n\n\n\n

C’\u00e8 per\u00f2 un compromesso onesto da dichiarare: l’approccio agentico funziona benissimo se Claude ha abbastanza contesto per sapere dove guardare<\/strong>. Chiedergli di trovare un pattern vago in una codebase da un miliardo di righe lo far\u00e0 sbattere contro i limiti della finestra di contesto prima ancora di iniziare. Ecco perch\u00e9 chi investe nella preparazione della codebase ottiene risultati molto migliori.<\/p>\n\n\n\n

L’imbragatura conta pi\u00f9 del motore<\/h2>\n\n\n\n

L’errore pi\u00f9 comune \u00e8 pensare che le capacit\u00e0 di Claude Code dipendano solo dal modello. Si guardano i benchmark, si confrontano i punteggi nei test. Ma nella pratica conta di pi\u00f9\u00a0l’ecosistema costruito attorno al modello<\/strong>: quello che l’articolo chiama\u00a0harness<\/em>, l’imbracatura.<\/p>\n\n\n\n

\n

? Una analogia<\/strong><\/p>\n\n\n\n

Il modello \u00e8 il motore<\/strong>. L’harness \u00e8 il resto dell’automobile<\/strong>: volante, cruscotto, navigatore, freni. Un motore potentissimo senza sterzo non ti porta da nessuna parte; un motore onesto dentro una macchina ben fatta ti fa arrivare ovunque.<\/p>\n<\/blockquote>\n\n\n\n

L’harness si costruisce a strati, e\u00a0l’ordine conta<\/strong>: ogni strato si appoggia sul precedente. Si parte dalle basi (i file di contesto) e si sale verso le estensioni pi\u00f9 sofisticate.<\/p>\n\n\n\n

\n \n \n Gli strati dell’harness<\/text>\n si costruiscono dal basso verso l’alto<\/text>\n \n \n \n \n 1 \u00b7 CLAUDE.md<\/text>\n i bigliettini di benvenuto su ogni scrivania<\/text>\n \n \n 2 \u00b7 Hooks<\/text>\n i riflessi automatici e i controlli di qualit\u00e0<\/text>\n \n \n 3 \u00b7 Skills<\/text>\n gli specialisti chiamati solo quando servono<\/text>\n \n \n 4 \u00b7 Plugins<\/text>\n la cassetta degli attrezzi pronta all’uso<\/text>\n \n \n 5 \u00b7 MCP server<\/text>\n le linee telefoniche verso l’esterno<\/text>\n \n \n \n + LSP<\/text>\n il navigatore con indirizzi esatti<\/text>\n \n \n + Subagent<\/text>\n lo scout mandato in avanscoperta<\/text>\n <\/svg>\n
Cinque
punti di estensione<\/b> pi\u00f9 due capacit\u00e0 aggiuntive (LSP<\/b> e subagent<\/b>) completano il quadro.<\/figcaption>\n <\/figure>\n\n\n\n

Cosa fa ciascun pezzo, con un esempio<\/h3>\n\n\n\n

CLAUDE.md, vengono per primi.<\/strong> Sono file di contesto che Claude legge in automatico a ogni sessione: uno alla radice per il quadro generale, altri nelle sottocartelle per le convenzioni locali. Esempio:<\/em> nel file della cartella pagamenti\/<\/code> scrivi “qui i test si lanciano con make test-payments<\/code>, non con la suite intera”. Siccome si caricano sempre, vanno tenuti snelli: solo ci\u00f2 che vale in generale e le trappole critiche.<\/p>\n\n\n\n

Hooks, rendono il setup capace di migliorarsi da solo.<\/strong> Molti li vedono solo come “blocchi” che impediscono errori, ma il loro uso pi\u00f9 prezioso \u00e8 automatico e continuo. Esempio:<\/em> un hook di fine sessione pu\u00f2 riflettere su cosa \u00e8 successo e proporre un aggiornamento al CLAUDE.md finch\u00e9 il contesto \u00e8 fresco. E per linting e formattazione, un hook applica le regole in modo deterministico, pi\u00f9 affidabile che sperare che Claude se le ricordi.<\/p>\n\n\n\n

Skills, competenza a richiesta senza appesantire ogni sessione.<\/strong> In una codebase con decine di tipi di compiti, non serve avere tutto sempre presente. Esempio:<\/em> una skill di “security review” si attiva solo quando Claude valuta vulnerabilit\u00e0; una skill per la documentazione si attiva quando una modifica al codice richiede di aggiornare i documenti. Le skill si possono anche legare a percorsi specifici: il team dei pagamenti aggancia la propria skill di deploy a quella cartella, cos\u00ec non si attiva mai altrove.<\/p>\n\n\n\n

Plugins, distribuiscono ci\u00f2 che funziona.<\/strong> Il rischio nelle grandi aziende \u00e8 che le buone configurazioni restino “tribali”, note solo a chi le ha inventate. Un plugin impacchetta skill, hook e configurazioni MCP in un unico pacchetto installabile. Esempio:<\/em> un’azienda retail ha costruito una skill che collega Claude alla propria piattaforma di analytics interna e l’ha distribuita come plugin, cos\u00ec ogni nuovo collega ha le stesse capacit\u00e0 dal primo giorno.<\/p>\n\n\n\n

LSP, d\u00e0 a Claude la stessa precisione di un IDE<\/strong> (Integrated Development Environment<\/em>, l’ambiente di sviluppo). Il Language Server Protocol \u00e8 ci\u00f2 che, nell’editor, fa funzionare “vai alla definizione” e “trova tutti i riferimenti”. Esempio:<\/em> cercare una funzione con un nome comune via testo restituisce migliaia di risultati e Claude brucia contesto aprendo file a caso; con l’LSP ottiene solo i riferimenti che puntano davvero allo stesso simbolo. Per codebase multi-linguaggio (C, C++\u2026) \u00e8 uno degli investimenti a pi\u00f9 alto valore.<\/p>\n\n\n\n

MCP server, estendono tutto.<\/strong> MCP sta per Model Context Protocol<\/em>: \u00e8 il modo con cui Claude si collega a strumenti interni, fonti dati e API che altrimenti non raggiungerebbe: documentazione interna, sistemi di ticketing, piattaforme di analytics. I team pi\u00f9 maturi costruiscono server MCP che espongono una ricerca strutturata come strumento chiamabile direttamente.<\/p>\n\n\n\n

Subagent, separano l’esplorazione dalla modifica.<\/strong> Un subagent \u00e8 un’istanza isolata di Claude, con la propria finestra di contesto: prende un compito, lo svolge e restituisce solo il risultato finale. Esempio:<\/em> un subagent in sola lettura mappa un sottosistema e scrive le sue scoperte in un file; poi l’agente principale modifica il codice avendo gi\u00e0 il quadro completo, senza essersi intasato il contesto con l’esplorazione.<\/p>\n\n\n\n

Componente<\/th>In una frase<\/th>Quando si carica<\/th>Errore tipico<\/th><\/tr><\/thead>
CLAUDE.md<\/td>File di contesto letto in automatico<\/td>Ogni sessione<\/td>Usarlo per competenze riusabili (che andrebbero in una skill)<\/td><\/tr>
Hooks<\/td>Script che scattano a momenti chiave<\/td>Su evento<\/td>Usare istruzioni “a voce” per cose che dovrebbero girare da sole<\/td><\/tr>
Skills<\/td>Istruzioni impacchettate per tipi di compito<\/td>A richiesta, quando servono<\/td>Infilare tutto nel CLAUDE.md<\/td><\/tr>
Plugins<\/td>Skill, hook e MCP in un pacchetto<\/td>Sempre, una volta configurato<\/td>Lasciare che i buoni setup restino “tribali”<\/td><\/tr>
LSP<\/td>Intelligenza di codice in tempo reale<\/td>Sempre, una volta configurato<\/td>Darlo per scontato come automatico<\/td><\/tr>
MCP server<\/td>Ponti verso strumenti e dati esterni<\/td>Sempre, una volta configurato<\/td>Costruirli prima che funzionino le basi<\/td><\/tr>
Subagent<\/td>Istanze separate per compiti specifici<\/td>Quando invocati<\/td>Esplorare e modificare nella stessa sessione<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

\u00abNon \u00e8 il modello da solo a fare la differenza, ma tutto ci\u00f2 che gli costruisci intorno.\u00bb<\/p>Anthropic’s blog<\/cite><\/blockquote><\/figure>\n\n\n\n

Tre mosse che funzionano sempre<\/h2>\n\n\n\n

Pur cambiando ogni codebase, tre pattern sono emersi con costanza nei progetti riusciti.<\/p>\n\n\n\n

1. Rendere la codebase navigabile<\/h3>\n\n\n\n

La capacit\u00e0 di Claude \u00e8 limitata dalla sua capacit\u00e0 di trovare il contesto giusto. Troppo contesto in ogni sessione ne degrada le prestazioni; troppo poco lo lascia a navigare alla cieca. In mezzo c’\u00e8 il punto giusto:<\/p>\n\n\n\n