Ogni lunga sessione di Claude Code finisce allo stesso modo: perdi ore di progressi e ricominci da capo.
La soluzione non è un modello più intelligente, ma un sistema che il team di Claude Code usa internamente e per cui non ha mai scritto una guida.
La maggior parte degli sviluppatori non ce l’ha e non sa che esiste.
Ecco il sistema completo 👇
🧠Prima di immergerci, condivido note quotidiane su AI e vibe coding nel mio canale Telegram:https://t.me/zodchixquant
Cosa significa realmente ingegneria del contesto
Claude legge migliaia di righe a ogni sessione. La maggior parte è rumore, e il 5% che conta viene sepolto dopo un paio d’ore.
È allora che Claude inizia a inventare funzioni e correggere bug che non hai mai scritto. La soluzione non è un modello più grande, ma controllare cosa entra nella sessione.
Questi sono i 6 pattern che il team di Claude Code usa sul proprio monorepo.
Pattern 1: CLAUDE.md a più livelli (Passi 1-3)
Un singolo CLAUDE.md non basta. Il team di Claude Code usa tre livelli, ognuno con uno scopo diverso.
Passo 1: CLAUDE.md radice con regole di progetto
Metti un CLAUDE.md nella root del tuo repo. Tienilo sotto le 100 righe. Deve rispondere a quattro domande che Claude si fa su ogni prompt:
1# Progetto: [nome]23## Stack4- Runtime: Node 22, TypeScript 5.55- Framework: Next.js 15, React 196- Database: Postgres 16, Drizzle ORM7- Testing: Vitest, Playwright89## Convenzioni10- Import: solo percorsi assoluti da `@/`11- Componenti: file in kebab-case, export in PascalCase12- Test: co-localizzati come `[file].test.ts`13- Commit: conventional commits, senza co-author footer1415## Non toccare16- `infra/terraform/` (gestito da ops)17- `migrations/` (generato, mai modificato a mano)18- `vendor/` (dipendenze committate)1920## Predefiniti21- Esegui `npm test` prima di dichiarare un task completato22- Type-check con `tsc --noEmit` a ogni modifica23- Formatta con Prettier al salvataggio
Passo 2: CLAUDE.md in sottodirectory per contesto di modulo
Aggiungi CLAUDE.md in qualsiasi cartella in cui le regole cambiano. Claude legge quello più vicino quando lavora in quella cartella, sopra a quello radice.
Esempio, src/auth/CLAUDE.md:
1# Modulo Auth23Questo modulo gestisce la gestione delle sessioni e i flussi OAuth.45## Regole6- Non loggare mai token, nemmeno troncati7- Tutte le letture di sessione passano da `getSession()`, mai dai cookie grezzi8- I nuovi provider richiedono una revisione di sicurezza prima del merge910## File da leggere per primi11- `session.ts` per il contratto12- `providers/index.ts` per il pattern di registrazione
Passo 3: CLAUDE.md personale in ~/.claude/CLAUDE.md
Questo è il tuo livello di preferenze globali. Risiede fuori da qualsiasi repo, si applica ovunque.
1## Le mie preferenze - Spiega cosa stai per fare prima di farlo su modifiche multi-file - Opponiti se la mia richiesta rischia di rompere qualcosa - Preferisci composizione invece di ereditarietà - Lavoro in zsh su macOS
I tre livelli si sovrappongono: preferenze globali + regole di progetto + regole di modulo. Claude li legge tutti e tre a ogni prompt senza doverli ricaricare nel tuo contesto.
Pattern 2: Riferimenti file chirurgici (Passi 4-5)
Il default "lascia che Claude capisca quali file contano" è il modo più lento e stupido di usare il contesto.
Passo 4:@file con autocompletamento
Quando scrivi @ in un prompt, Claude apre un selettore fuzzy di file. Usalo invece di descrivere i file in prosa.
Male: "guarda il codice di autenticazione utente e l'helper di sessione"
Bene: "guarda
@src/auth /session.ts e
@src/auth /providers/google.ts, correggi il refresh del token"
I riferimenti chirurgici caricano esattamente quei file. Le descrizioni in prosa costringono Claude a cercare, leggere 4-5 file candidati e scegliere quello sbagliato la metà delle volte.
Passo 5: /focus per circoscrivere un intero flusso di lavoro
Per task più lunghi, circoscrivi l'intera sessione di Claude a cartelle specifiche:
1/focus src/auth src/api/auth-routes
Ora ogni ricerca, grep e lettura opera solo in quelle due cartelle.
Riduce l'uso del contesto del 60-80% su task focalizzati, e Claude smette di leggere "utili" file irrilevanti per un contesto che non serve.
Esegui /focus clear per resettare.
Pattern 3: Compattazione e continuazione (Passi 6-8)
Le sessioni lunghe raggiungono il limite di contesto e crashano. Il trucco non è evitare sessioni lunghe, ma gestirle tramite compattazione controllata.
Passo 6: Tieni d'occhio il contesto con /stats
Esegui /stats periodicamente.
Quando superi il 70% di utilizzo del contesto, sei nella zona pericolo. Oltre l'85%, Claude inizia a scartare messaggi iniziali senza dirtelo.
Passo 7: /compact con istruzioni di conservazione
/compact da solo riassume la conversazione. Con le istruzioni, dici a Claude cosa preservare parola per parola:
1/compact preserva: piano del task corrente, tutte le decisioni sul refactoring auth, output del test fallito dal passo 3
Passo 8: /resume per sessioni che durano giorni
Se un task dura più giorni, termina ogni sessione con /compact preserva: ... e inizia quella successiva con:
1claude --resume [id-sessione]
Oppure semplicemente claude --continue per la sessione più recente. Riprende esattamente da dove hai lasciato con lo stato compattato intatto.
Pattern 4: Lettura prima di agire (Passi 9-10)
La più grande perdita di contesto è quando Claude modifica file prima di capirli. La modalità piano lo costringe a leggere prima, scrivere dopo.
Passo 9: Attiva la modalità piano su ogni task rischioso
Premi Shift+Tab per entrare in modalità piano prima di qualsiasi task che tocchi più di un file.
In modalità piano Claude può solo leggere. Spiega cosa farebbe, elenca ogni file che intende toccare e mostra le modifiche proposte. Niente viene eseguito finché non approvi.
I risparmi sono reali: una lettura, una modifica, invece di leggere 8, modificarne 3 sbagliate, annullare, rileggere, modificare di nuovo.
Passo 10: Blocca la modalità piano per percorsi sensibili tramite hook
Rendi la modalità piano obbligatoria per aree rischiose. In .claude/settings.json:
1{2 "hooks": {3 "PreToolUse": [4 {5 "matcher": "Edit(src/auth/**)|Edit(migrations/**)",6 "hooks": [7 {8 "type": "command",9 "command": "claude-require-plan-mode"10 }11 ]12 }13 ]14 }15}
Qualsiasi tentativo di modifica in src/auth/*\ o migrations/\\ *innesca un requisito di modalità piano. Claude non può bypassarlo.
Pattern 5: Isolamento del contesto con subagenti (Passi 11-13)
I subagenti sono il modo più pulito per mantenere piccolo il contesto principale. Ogni subagente gira nella propria finestra, quindi la sessione padre non vede mai il rumore.
Passo 11: Progetta subagenti con una superficie di strumenti minima
Limita gli strumenti a ciò che serve al compito.
Un code-reviewer non ha bisogno di Write o Edit.
Un doc-updater non ha bisogno di Bash. Meno superficie, meno contesto sprecato su strumenti e documentazione irrilevanti.
1---2name: code-reviewer3description: Rivedi le modifiche al codice per bug e problemi di sicurezza4tools: Read, Grep, Glob5model: sonnet6---
Passo 12: Passa solo i riferimenti file di cui l'agente ha bisogno
Non dire "rivedi le modifiche recenti." Di' "rivedi[@src/auth](https://x.com/@src/auth)/session.ts e [@src/auth](https://x.com/@src/auth)/providers/google.ts.**"
Il subagente legge solo quelli, non la sua ipotesi migliore su cosa significhi "recente".
Passo 13: Usa modelli più economici per i subagenti
Imposta il modello per ogni agente in base al compito.
Sonnet per attività di revisione e test, Haiku per aggiornamenti di documentazione e lint, Opus solo per audit di architettura o sicurezza dove serve ragionamento profondo.
Imposta globalmente se necessario:
1export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"
Subagenti più economici = più chiamate a subagenti per dollaro = più isolamento = contesto principale più piccolo.
L'avvio rapido di ingegneria del contesto in 30 minuti
10 minuti: scrivi un CLAUDE.md radice stretto con stack, convenzioni, elenco "non toccare" e valori predefiniti.
5 minuti: aggiungi CLAUDE.md in sottodirectory nei tuoi 2-3 moduli più modificati.
5 minuti: crea un CLAUDE.md personale in ~/.claude/CLAUDE.md con le tue preferenze.
5 minuti: crea una skill in .claude/skills/ per il flusso di lavoro che fai più spesso.
5 minuti: allena la memoria muscolare per Shift+Tab e inizia ogni task multi-file in modalità piano.
Fatto!
La tua prossima sessione userà il 50-70% in meno di contesto per la stessa quantità di lavoro. Alla quinta sessione i pattern diventano riflessi e smetti del tutto di raggiungere il limite.
Il contesto non è qualcosa che Claude gestisce per te. È qualcosa che tu ingegnerizzi.
Ora hai il sistema.
Grazie per aver letto!
Condivido note quotidiane su AI, finanza e vibe coding nel mio canale Telegram: https://t.me/zodchixquant
