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à brava non dipende solo da quanto è sveglia. Dipende soprattutto da come hai organizzato l’archivio, dai cartelli che hai appeso e dagli strumenti che le hai messo in mano.
È 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.
Come si muove dentro al codice
Claude Code esplora il codice come farebbe uno sviluppatore in carne e ossa: apre cartelle, legge file, usa grep per cercare ciò che gli serve e segue i riferimenti da un file all’altro. Questa parte, la ricerca e la lettura dei file, avviene sulla tua macchina, e non c’è alcun “indice” del codice da costruire, mantenere o caricare su un server esterno.
? Attenzione
Si dice spesso che Claude Code “lavora in locale”. È una mezza verità da maneggiare con cura: locale è l’agente che cerca e legge i file; remota è l’elaborazione. Per ragionare sul codice, le porzioni rilevanti vengono inviate via API (Application Programming Interface, l’interfaccia con cui due programmi si parlano) ai server di Anthropic, dove gira il modello. Il codice a riposo resta da te; il codice nel momento del ragionamento viaggia.
Serve però chiarire un equivoco comune, perché sotto la sigla “RAG” finiscono cose molto diverse. RAG significa Retrieval-Augmented Generation e si compone di tre pezzi che possono stare ciascuno in locale o in remoto: il modello di embedding (che trasforma il codice in vettori), il database vettoriale dove quei vettori vivono, e l’LLM che genera la risposta. A seconda di dove metti questi pezzi ottieni sistemi profondamente diversi.
? Due famiglie di RAG
Un RAG fully-local (embedding, database vettoriale e un LLM open-weight tutti sulla tua macchina) fa davvero tutto in casa: il codice non esce mai. Un RAG API-driven usa embedding o LLM remoti: indicizza in locale, ma poi manda fuori i chunk recuperati, esponendo spesso più codice di Claude Code, perché ha indicizzato tutto in anticipo.
Distinguere questi due assi è la chiave per non confondersi. Il difetto classico del RAG, l’indice che invecchia, non dipende dal locale contro il remoto. Dipende dal fatto che l’indice è precalcolato: appena committi codice nuovo, l’indice è vecchio, che sia su un database vettoriale nella tua sala server o su un servizio in cloud. La ricerca agentica evita questo perché rilegge la versione viva ogni volta. Stiamo quindi rispondendo a due domande diverse, che conviene tenere separate:
Ne esce un quadro più giusto. Se la tua priorità è la riservatezza assoluta, 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à di ragionamento. Se la priorità è freschezza e qualità del ragionamento, la ricerca agentica di Claude Code evita l’indice che invecchia e usa modelli potenti, ma il codice rilevante deve uscire. Ogni architettura è un compromesso tra riservatezza e capacità: la scelta giusta dipende da cosa conta di più nel tuo contesto.
E la sostenibilità?
C’è un terzo asse che il dibattito locale-contro-remoto quasi sempre dimentica: l’impronta energetica e ambientale. E qui l’intuito inganna. “Locale” suona più sobrio, “cloud” suona dispendioso, ma spesso è il contrario.
? Locale e remoto
Un grande datacenter ottimizzato raggiunge valori di efficienza (il PUE, Power Usage Effectiveness, cioè il rapporto tra energia totale ed energia utile al calcolo) vicini a 1,1-1,2, sfrutta hardware condiviso ad altissimo utilizzo e può attingere a energia a basse emissioni. Una GPU (Graphics Processing Unit, 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ò emettere di più.
Ma anche qui non c’è una risposta secca, e vale la pena tenere insieme più fattori prima di concludere. Conta la dimensione del modello (un piccolo modello locale per un compito semplice può battere l’invio di tutto a un modello di frontiera enorme), l’intensità di carbonio della rete elettrica nel luogo e nell’ora in cui il calcolo avviene, l’energia incorporata nell’hardware che acquisti contro quella di infrastruttura condivisa, e, non ultimo, il numero di tentativi: un modello più capace che azzecca la risposta al primo colpo può consumare meno di uno debole che ci riprova cinque volte. La domanda utile, allora, è un’altra: qual è il modello più piccolo che svolge davvero il compito, alimentato dall’energia più pulita disponibile, con il minor numero di ripetizioni? È lo stesso principio del “do less, better” applicato al calcolo.
C’è però un compromesso onesto da dichiarare: l’approccio agentico funziona benissimo se Claude ha abbastanza contesto per sapere dove guardare. Chiedergli di trovare un pattern vago in una codebase da un miliardo di righe lo farà sbattere contro i limiti della finestra di contesto prima ancora di iniziare. Ecco perché chi investe nella preparazione della codebase ottiene risultati molto migliori.
L’imbragatura conta più del motore
L’errore più comune è pensare che le capacità di Claude Code dipendano solo dal modello. Si guardano i benchmark, si confrontano i punteggi nei test. Ma nella pratica conta di più l’ecosistema costruito attorno al modello: quello che l’articolo chiama harness, l’imbracatura.
? Una analogia
Il modello è il motore. L’harness è il resto dell’automobile: 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.
L’harness si costruisce a strati, e l’ordine conta: ogni strato si appoggia sul precedente. Si parte dalle basi (i file di contesto) e si sale verso le estensioni più sofisticate.
Cosa fa ciascun pezzo, con un esempio
CLAUDE.md, vengono per primi. 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: nel file della cartella pagamenti/ scrivi “qui i test si lanciano con make test-payments, non con la suite intera”. Siccome si caricano sempre, vanno tenuti snelli: solo ciò che vale in generale e le trappole critiche.
Hooks, rendono il setup capace di migliorarsi da solo. Molti li vedono solo come “blocchi” che impediscono errori, ma il loro uso più prezioso è automatico e continuo. Esempio: un hook di fine sessione può riflettere su cosa è successo e proporre un aggiornamento al CLAUDE.md finché il contesto è fresco. E per linting e formattazione, un hook applica le regole in modo deterministico, più affidabile che sperare che Claude se le ricordi.
Skills, competenza a richiesta senza appesantire ogni sessione. In una codebase con decine di tipi di compiti, non serve avere tutto sempre presente. Esempio: una skill di “security review” si attiva solo quando Claude valuta vulnerabilità; 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ì non si attiva mai altrove.
Plugins, distribuiscono ciò che funziona. Il rischio nelle grandi aziende è 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: un’azienda retail ha costruito una skill che collega Claude alla propria piattaforma di analytics interna e l’ha distribuita come plugin, così ogni nuovo collega ha le stesse capacità dal primo giorno.
LSP, dà a Claude la stessa precisione di un IDE (Integrated Development Environment, l’ambiente di sviluppo). Il Language Server Protocol è ciò che, nell’editor, fa funzionare “vai alla definizione” e “trova tutti i riferimenti”. Esempio: 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++…) è uno degli investimenti a più alto valore.
MCP server, estendono tutto. MCP sta per Model Context Protocol: è 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ù maturi costruiscono server MCP che espongono una ricerca strutturata come strumento chiamabile direttamente.
Subagent, separano l’esplorazione dalla modifica. Un subagent è un’istanza isolata di Claude, con la propria finestra di contesto: prende un compito, lo svolge e restituisce solo il risultato finale. Esempio: 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à il quadro completo, senza essersi intasato il contesto con l’esplorazione.
| Componente | In una frase | Quando si carica | Errore tipico |
|---|---|---|---|
| CLAUDE.md | File di contesto letto in automatico | Ogni sessione | Usarlo per competenze riusabili (che andrebbero in una skill) |
| Hooks | Script che scattano a momenti chiave | Su evento | Usare istruzioni “a voce” per cose che dovrebbero girare da sole |
| Skills | Istruzioni impacchettate per tipi di compito | A richiesta, quando servono | Infilare tutto nel CLAUDE.md |
| Plugins | Skill, hook e MCP in un pacchetto | Sempre, una volta configurato | Lasciare che i buoni setup restino “tribali” |
| LSP | Intelligenza di codice in tempo reale | Sempre, una volta configurato | Darlo per scontato come automatico |
| MCP server | Ponti verso strumenti e dati esterni | Sempre, una volta configurato | Costruirli prima che funzionino le basi |
| Subagent | Istanze separate per compiti specifici | Quando invocati | Esplorare e modificare nella stessa sessione |
«Non è il modello da solo a fare la differenza, ma tutto ciò che gli costruisci intorno.»
Anthropic’s blog
Tre mosse che funzionano sempre
Pur cambiando ogni codebase, tre pattern sono emersi con costanza nei progetti riusciti.
1. Rendere la codebase navigabile
La capacità di Claude è limitata dalla sua capacità 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’è il punto giusto:
- CLAUDE.md snelli e a strati: radice per il quadro d’insieme, sottocartelle per i dettagli locali. La radice contiene solo puntatori e trappole critiche.
- Avviare nelle sottocartelle, non alla radice: Claude lavora meglio quando è circoscritto alla parte rilevante. Risale comunque l’albero e carica ogni CLAUDE.md che trova, quindi il contesto della radice non si perde.
- Comandi di test e lint per sottocartella: lanciare l’intera suite per una modifica a un solo servizio causa timeout e spreca contesto.
- File
.ignoree regole versionate per escludere file generati, artefatti di build e codice di terze parti, così tutti hanno la stessa riduzione di rumore. - Mappe della codebase quando la struttura delle cartelle non basta: un semplice file markdown alla radice con una riga di descrizione per ogni cartella di alto livello.
- Server LSP attivi per cercare per simbolo, non per stringa.
2. Manutenere i CLAUDE.md man mano che i modelli evolvono
Le istruzioni scritte per il modello di oggi possono lavorare contro quello di domani. Esempio dal pezzo: una regola che diceva “spezza ogni refactoring in modifiche a un solo file” aiutava un modello più vecchio a non perdersi, ma impedirebbe a uno più nuovo di fare le modifiche coordinate su più file che ormai gestisce bene. Allo stesso modo, hook e skill nati per compensare vecchi limiti diventano peso morto quando quei limiti spariscono. Consiglio pratico: una revisione della configurazione ogni 3–6 mesi, e comunque dopo ogni rilascio importante di modello.
3. Assegnare una responsabilità chiara
La configurazione tecnica da sola non basta a guidare l’adozione. I rollout più rapidi avevano un investimento dedicato prima dell’accesso diffuso: un piccolo team, a volte una sola persona, che cabla gli strumenti così che, quando gli sviluppatori toccano Claude per la prima volta, sia già integrato nel loro flusso. La prima esperienza è produttiva invece che frustrante, e da lì l’adozione si diffonde.
Sta emergendo una figura nuova, l’agent manager: un ibrido tra PM (project manager) e ingegnere dedicato a gestire l’ecosistema Claude Code. Ma ridurlo a “chi coordina e configura” è limitante. La parte più sottile e più preziosa del ruolo è un’altra: saper leggere gli output con occhio critico e fare adversarial check degli errori. Non basta che Claude produca una risposta plausibile e ben scritta; qualcuno deve chiedersi «è davvero corretta, o solo verosimile?» e provare a smontarla finché non regge. È esattamente la differenza tra accettare “Claude Code lavora in locale” e accorgersi che no: locale è solo la ricerca, l’inferenza è remota. Un agent manager senza questo istinto distribuisce in fretta configurazioni che sembrano funzionare ma propagano errori sottili a tutta l’organizzazione.
Per chi non ha un team dedicato, la versione minima è un DRI (Directly Responsible Individual, la persona direttamente responsabile): qualcuno con la responsabilità (e l’autorità) su configurazione, permessi, marketplace dei plugin e convenzioni dei CLAUDE.md, e con il compito di verificare la qualità di ciò che Claude produce prima che diventi standard. L’adozione dal basso genera entusiasmo, ma senza qualcuno che centralizzi e verifichi criticamente ciò che funziona, la conoscenza resta tribale e gli errori si sedimentano silenziosamente.
C’è un’abilità sotto tutto questo, ed è la più facile da trascurare: per fare bene da agent manager bisogna prima di tutto saper pensare bene. Lo strumento amplifica chi lo guida: se il pensiero è solido, l’LLM lo potenzia; se è pigro, lo rispecchia e lo conferma. La postura giusta è pensare-con il modello, non delegargli il pensiero: tenerlo come interlocutore da interrogare e contraddire, mai come oracolo da firmare. È questa la differenza tra uscire da una sessione più bravi e uscirne solo più veloci.
Da dove partire
Claude Code è pensato per ambienti di sviluppo convenzionali: ingegneri come contributori principali, repository su Git, struttura di cartelle standard. Setup non tradizionali (motori di gioco con grandi asset binari, controllo di versione insolito, non-ingegneri che contribuiscono) richiedono lavoro di configurazione aggiuntivo. Ecco una sequenza di partenza ragionevole:
- Scrivi i primi CLAUDE.md: uno alla radice (snello), poi nelle sottocartelle dove lavori davvero.
- Aggiungi hook per linting/formattazione e per catturare gli apprendimenti di fine sessione.
- Sposta le competenze riusabili in skill, agganciate ai percorsi giusti.
- Attiva l’LSP per il tuo linguaggio: cercare per simbolo invece che per stringa.
- Impacchetta tutto in plugin e dai una ownership chiara (un DRI o un agent manager).
Per le aziende grandi, soprattutto in settori regolati, le domande di governance arrivano presto: chi controlla quali skill e plugin sono disponibili? come si evita che migliaia di ingegneri ricostruiscano la stessa cosa? come si garantisce che il codice generato dall’AI passi dalla stessa revisione di quello umano? La risposta suggerita è partire con un set definito di skill approvate, revisione del codice obbligatoria e accesso iniziale limitato, allargando man mano che cresce la fiducia.n set definito di skill approvate, revisione del codice obbligatoria e accesso iniziale limitato, allargando man mano che cresce la fiducia.
Nota. Questo è un articolo divulgativo in italiano, sintesi e rielaborazione con parole, esempi e diagrammi miei, basato sull’articolo Anthropic «How Claude Code works in large codebases: Best practices and where to start» (blog Claude, 14 maggio 2026).
Originale: claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start