Perché Claude Code rilegge l’intero progetto e come risolvere il problema

Documentazione di Ailoot: API, chiavi e connessione.

Perché Claude Code rilegge il progetto da zero ogni volta?#

Molti pensano che sia un bug. In realtà, Claude Code è progettato così: non dispone di un indice del progetto. Quando gli chiedi di correggere qualcosa, non ha a disposizione una mappa del codice già pronta: esplora di nuovo il progetto, individua i file pertinenti, cerca le stringhe necessarie e carica i file in memoria.

Questo approccio offre vantaggi concreti. Il codice è sempre aggiornato: non c’è un indice diventato obsoleto. Non c’è nulla da configurare. Il tuo codice non viene inviato ad alcun database.

Ma c’è uno svantaggio: ogni nuovo compito comporta un nuovo ciclo di ricerca e lettura dei file. I token vengono spesi per capire di nuovo dove si trova ogni cosa, anche se Claude l’aveva già scoperto nella sessione precedente. Più il progetto è grande, più costa questa ricognizione. È proprio questo meccanismo a dare l’impressione che l’agente stia «leggendo tutto».

Quanti token consuma davvero?#

Il costo inizia prima della tua richiesta. Una misurazione indipendente lo mostra in modo semplice: Claude Code invia circa 33.000 token di prompt di sistema e descrizioni degli strumenti prima di leggere il primo carattere del tuo messaggio. Per fare un confronto, OpenCode parte da circa 7.000.

Poi entra in gioco la rilettura. Ogni ricerca di file e ogni lettura aggiunge token al contesto. La documentazione ufficiale di Claude Code lo dice chiaramente: la lettura dei file domina l’uso del contesto. Analizzare auth.ts, che contiene 2.400 token, significa che Claude ne vede 2.400; lo stesso vale per ogni file che apre durante la ricognizione.

Per il nostro pubblico, questo si traduce in denaro e limiti. La paura numero uno di chi si avvicina al vibe coding è: «Ho pagato e ho esaurito i limiti senza motivo». Se l’agente scansiona il progetto e rilegge i file da zero a ogni compito, il contesto si consuma due volte più rapidamente: prima per i costi di sistema, poi per la ricognizione. Nella guida «Dove finiscono i token di Claude Code» ho descritto nel dettaglio dove vanno esattamente i token di Claude Code: la rilettura del progetto è uno dei nove schemi trattati.

Che cos’è la memoria persistente del codice?#

La memoria del codice colma proprio la lacuna che porta Claude a rileggere il progetto. L’idea è semplice: far scansionare tutto il codice una volta, crearne una mappa e tenerla a portata di mano. Così l’agente non deve ogni volta cercare da zero: interroga la mappa.

Dal punto di vista tecnico, funziona così. Uno strumento separato scansiona il progetto e lo suddivide in componenti: quali funzioni e classi esistono, chi chiama chi e quali file sono collegati. Questa struttura viene salvata su disco. Quando Claude deve capire dove si trova la logica dei pagamenti o cosa si romperà se si modifica una funzione, invia alla mappa una singola interrogazione mirata invece di leggere decine di file.

La mappa si collega tramite MCP, il metodo standard per associare uno strumento esterno a Claude Code (nella guida «Server MCP per Claude Code» ho descritto come collegare altri server). Lo strumento per la memoria del codice aggiunge i propri comandi di ricerca nella mappa e Claude li usa autonomamente quando ha bisogno di orientarsi nel progetto.

In pratica, la differenza è tra «leggere l’intera cartella per trovare una funzione» e «chiedere alla mappa dove si trova quella funzione». La prima opzione costa decine di migliaia di token; la seconda, centinaia.

Due approcci alla memoria del codice: quali sono le differenze?#

Gli strumenti per la memoria del codice si differenziano per ciò che ricavano dal progetto. Il modo più semplice per pensarci è questo: uno offre mani da chirurgo per le modifiche e l’altro cerca in base al significato.

I conteggi delle stelle su GitHub sono aggiornati al 15 luglio 2026 (secondo l’API di GitHub). Entrambi gli strumenti sono gratuiti e open source, funzionano con Claude Code e si collegano come server MCP.

In breve, per chi non programma: Serena è come avere mani da chirurgo: usala quando modifichi la stessa parte in tutto il progetto e la precisione è importante. claude-context è una ricerca per significato: trova il codice partendo da una descrizione, ma richiede la configurazione di un database cloud e una chiave.

Quando scegliere Serena o claude-context?#

I due strumenti non si contendono un unico premio. Ognuno ricorda cose diverse, quindi la scelta dipende dal compito.

Scegli Serena se fai spesso refactoring. Offre all’agente una navigazione del codice simile a quella di un ambiente di sviluppo intelligente: individua la definizione di una funzione e tutti i suoi punti di chiamata effettivi, poi rinomina con attenzione la funzione o ne sostituisce il corpo in tutto il progetto. L’autore descrive il vantaggio così.

Serena non pubblica una percentuale precisa di risparmio e non le attribuirò una cifra inventata. Il vantaggio è diverso: quando una ricerca normale restituisce quaranta corrispondenze, insieme a commenti e stringhe, dopo di che Claude legge quattro file interi, Serena risponde con poche interrogazioni precise. Questo significa meno chiamate e meno corrispondenze errate, quindi minore rischio che l’agente modifichi la cosa sbagliata.

Scegli claude-context se ti serve una ricerca per significato e non ti spaventa la configurazione. Trasforma il codice in vettori (impronte numeriche del significato) e cerca in base a una descrizione: «trova dove si trova la nostra logica dei pagamenti», anche se non conosci i nomi delle funzioni. Questa ricerca richiede una configurazione aggiuntiva.

claude-context richiede un database vettoriale esterno, una chiave per un provider di embeddings e una versione recente di Node. Tra i due è il più impegnativo da configurare, quindi consiglio ai principianti di iniziare con qualcos’altro.

Cosa puoi fare direttamente in Claude Code senza strumenti di terze parti?#

Prima di installare strumenti di terze parti, sfrutta al massimo ciò che Claude Code include già. Questi comandi sono gratuiti e funzionano subito.

1. /context mostra una panoramica aggiornata di ciò che occupa la finestra: prompt di sistema, CLAUDE.md, memoria, strumenti e file. Il comando /mcp mostra il costo di ogni server collegato e /memory indica cosa è stato caricato all’avvio.
2. /compact comprime la cronologia della conversazione in un breve riepilogo e prosegue lo stesso compito. Puoi indicare cosa conservare aggiungendolo a /compact.
3. /clear elimina l’intera cronologia. La raccomandazione ufficiale è eseguirlo quando si passa a un compito non correlato, così la vecchia conversazione non occupa spazio che serve ai file necessari.
4. /doctor (noto anche come /checkup, introdotto l’8 luglio 2026) diagnostica la configurazione e suggerisce correzioni: rimuove i duplicati in CLAUDE.md, trova strumenti e server inutilizzati e individua gli handler lenti.

Una nota a parte su CLAUDE.md. Questo file viene caricato nel contesto all’inizio di ogni sessione e incluso in ogni messaggio. Se è eccessivamente lungo, continui a pagarlo. La raccomandazione ufficiale è mantenerlo sotto le 200 righe e spostare i dettagli di riferimento in skill caricate su richiesta. Nella guida separata «Come configurare CLAUDE.md» ho descritto come impostare correttamente CLAUDE.md.

Un’altra risorsa integrata sono i subagenti. Hanno un contesto separato, quindi puoi delegare loro la lettura intensiva e la ricognizione senza gonfiare la finestra principale. Anthropic esprime così il principio generale nella sua analisi tecnica.

Un server MCP aggiuntivo renderà il contesto ancora più grande?#

L’idea che «un altro server comporta più costi di contesto» era corretta, ma Claude Code è cambiato. Per impostazione predefinita, le descrizioni degli strumenti MCP vengono caricate in modo differito: all’avvio vengono inclusi nel contesto solo i nomi dei server e le descrizioni complete vengono caricate quando serve uno strumento specifico per il compito. La documentazione lo afferma chiaramente.

Il calcolo della memoria del codice è semplice: un costo fisso contenuto per i nomi degli strumenti contro migliaia di token risparmiati perché l’agente non rilegge più i file. Il bilancio favorisce chiaramente l’indice.

Un paio di precisazioni, per non aspettarti magie. L’indice va ricostruito occasionalmente: la mappa riflette il codice così com’era al momento della scansione e va aggiornata dopo modifiche importanti (dipende dallo strumento: alcuni lo fanno automaticamente, per altri serve un comando). Inoltre, affermazioni come «120 volte meno token» descrivono il caso migliore su domande selezionate, non quello che vedrai in ogni compito. Il risparmio reale è più modesto, ma comunque evidente. Se vuoi approfondire come evitare in generale di esaurire i limiti, ho preparato un’analisi separata: «Come evitare di consumare tutti i limiti di Claude Code».

Da dove cominciare oggi?#

Se elimini tutto il superfluo, il piano per oggi è semplice:

1. Esegui /doctor e applica i suggerimenti: rimuovi i duplicati in CLAUDE.md e gli strumenti inutilizzati.
2. Riduci CLAUDE.md a 200 righe, spostando il materiale di riferimento nelle skill.

Poi scegli in base alle tue esigenze: se fai molto refactoring, aggiungi Serena per le modifiche precise; se ti serve una ricerca per significato, configura claude-context. La memoria del codice e un contesto pulito risolvono oggi il problema principale.

Se ti serve accedere ai modelli AI tramite Ailoot, dai un’occhiata ad Ailoot.