La finestra di contesto di Claude Code è una risorsa preziosa, finita e sensibile che definisce il perimetro in cui può operare un agente CLI. Essa ospita l'intera "conversazione corrente", quindi ogni comando digitato dall'utente, le risposte che sono state fornite, il testo completo di ciascun file letto dall'agente per indagare sul codice e il log completo dei comandi eseguiti.

Anche se i modelli moderni vantano delle finestre eccezionalmente ampie, la realtà sul campo è che letture ricorsive di file o output molto ampi di comandi da terminale consumano decine di migliaia di token in pochi istanti. All'avvicinarsi della saturazione, le prestazioni degradano poi in modo spesso imprevedibile e l'agente inizia a "dimenticare" le istruzioni fornite all'inizio della sessione, registra allucinazioni in termini di logica del ragionamento e tende a modificare parti di codice non correlate al task principale.

Un prompt "Kitchen-Sink" con Claude Code

Un errore molto frequente dello sviluppatore alle prime armi consiste nel trattare Claude Code come un chatbot generico o uno strumento solo un po' più avanzato avanzato per l'autocompletamento rispetto a soluzioni già note come per esempio Visual Studio Code. Si lanciano così analisi non confinate alla codebase di riferimento che riempiono la finestra di tanto "rumore" inutile.

Analizziamo ora un prompt che potremmo definire generico e rischioso:

# Questo comando costringe l'agente a scansionare e leggere un numero enorme di file
"Esplora il nostro intero progetto Express e spiegami come abbiamo implementato i token JWT"

Un intervento correttivo efficace potrebbe essere lo scoping mirato contenente dei riferimenti espliciti:

# Vincola fisicamente la lettura dell'agente ai soli file d'interesse usando l'operatore @
"Analizza l'implementazione e la convalida dei token JWT basandoti esclusivamente su @src/auth/jwt.ts e @src/middlewares/auth.middleware.ts"

Correzione in loop infinito nello stesso thread

Quando Claude commette un errore di compilazione o logico, gli sviluppatori tendono a insistere nello stesso canale di conversazione con correzioni sequenziali molto rapide. Questo particolare tipo di approccio non fa altro che accumulare codice difettoso e approcci fallimentari nella finestra di contesto, fattore che inquina irreparabilmente la memoria attiva dell'agente.

Di seguito un possibile loop di correzione "inquinante":

# Turno 1: "L'applicazione va in crash, ripara il database"
# Turno 2: "Non funziona ancora, la variabile di connessione è indefinita"
# Turno 3: "Adesso l'errore è diverso, rimuovi il blocco try-catch di prima"

Una situazione in cui torna sicuramente utile il reset del contesto. Quindi se Claude non risolve il bug entro due tentativi, si interrompe la sessione tramite Esc, si azzera la memoria con /clear e si riparte con un prompt preciso che capitalizzi sull'errore riscontrato:

/clear
"Risolvi il crash di connessione al database in @src/config/database.ts. L'errore è causato dalla mancata risoluzione della variabile d'ambiente DB_PASSWORD. Non tentare di cablare la password nel codice (tentativo fallito in precedenza); usa invece process.env.DB_PASSWORD con un fallback di sicurezza.

Per chiarezza, "cablare la password nel codice" significa tentare di scriverla in chiaro all'interno di un file di programma e si tratta di una pratica altamente sconsigliata.

Ricerca non isolata per refactoring complessi con Claude Code

Lanciare indagini su larga scala o migrazioni di centinaia di file nella sessione principale degrada istantaneamente efficienza e produttività del flusso di lavoro.

Ecco un uso di subagenti, con esecuzione non interattiva in parallelo, che delega la parte più pesante dell'esplorazione a un subagente isolato con un contesto a sé stante per mantenere pulito il canale principale:

"Usa un subagente per esaminare in modalità di sola lettura le dipendenze obsolete del progetto e restituisci un report sintetico senza toccare il contesto della chat"

Per le attività più ripetitive effettuate su larga scala, è poi meglio evitare l'interattività e sfruttare cicli di shell non interattivi con il flag -p per suddividere il lavoro su container o checkout isolati:

# Loop non interattivo con limitazione stringente degli strumenti consentiti
for file in $(cat legacy_files.txt); do
 claude -p "Migra il file $file alla sintassi ES6. Esegui il commit e restituisci OK." \
 --allowedTools "Edit,Bash(git commit *)"
done

Infine, meglio non dimenticarsi di controlla periodicamente l'utilizzo dei token con il comando /context per monitorare la salute della sessione.