Ho letto il codice sorgente di Claude Code così non devi farlo tu

la maggior parte delle persone apre claude code, scrive un prompt, aspetta la risposta, ne scrive un altro.

è come comprare una ferrari e guidarla solo in prima marcia.

volevo capire perché alcune persone sembrano ottenere 10 volte di più da claude code rispetto ad altre. così ho fatto quello che qualsiasi persona ragionevole farebbe: ho letto tutto il codice sorgente (quando dico "io", intendo claude code, ovviamente).

11 livelli di architettura. migliaia di righe. una piattaforma di orchestrazione di agenti travestita da chat su terminale.

ecco cosa rivela il codice sorgente su come usare davvero questo strumento.

1. CLAUDE.md viene caricato a ogni singolo turno. ogni. singolo. turno.

questa è la cosa a più alta leva che puoi fare e quasi nessuno la fa bene.

la maggior parte delle persone o non ha nulla nel file CLAUDE.md, oppure ci ha scritto la bibbia.

il codice sorgente mostra che claude code legge i tuoi file CLAUDE.md a ogni iterazione della query. non all'inizio della sessione. ogni turno. significa che ogni volta che invii un messaggio, rilegge le tue istruzioni.

c'è un'intera gerarchia:

• ~/.claude/CLAUDE.md — globale (il tuo stile di codifica, le tue preferenze)

• ./CLAUDE.md — a livello di progetto (decisioni architetturali, convenzioni)

• .claude/rules/*.md — regole modulari

• CLAUDE.local.md — note private (gitignorato)

hai 40.000 caratteri. è TANTO. la maggior parte delle persone ne usa forse 200.

mettici le tue decisioni architetturali. le tue convenzioni sui file. i tuoi pattern di test. le tue regole "non fare mai questo". il modello le legge a ogni singolo turno. questa è la differenza tra claude code come assistente generico e claude code come TUO assistente che conosce la TUA codebase.

se fai una sola cosa dopo aver letto questo, è questa.

2. i sottoagenti condividono la cache dei prompt (il parallelismo è praticamente gratis)

questa è la cosa che mi ha sconvolto.

quando claude code fork un sottoagente, crea una copia byte-identica del contesto genitore. l'API lo mette in cache. quindi generare 5 agenti che lavorano su parti diverse della tua codebase costa poco più di 1 agente che lo fa in sequenza.

rileggilo.

5 agenti. stesso costo di 1. perché condividono tutti la cache dei prompt.

la maggior parte delle persone usa claude code come un singolo lavoratore. un compito alla volta. aspetta che finisca. dagli il prossimo.

il codice sorgente ha letteralmente tre modelli di esecuzione per i sottoagenti:

• fork — eredita il contesto genitore, ottimizzato per la cache

• teammate — pannello separato in tmux o iterm, comunica tramite mailbox basata su file

• worktree — ottiene un proprio git worktree, branch isolato per agente

puoi dire a claude code di avviare 5 agenti: uno che fa un audit di sicurezza, uno che refactoring del modulo di autenticazione, uno che scrive test, uno che aggiorna la documentazione, uno che corregge bug. tutti contemporaneamente. tutti che condividono la cache.

l'architettura è COSTRUITA per questo. usarlo in modalità single-thread è un crimine.

3. il sistema di permessi è progettato per essere configurato, non per essere cliccato

ogni volta che claude code chiede "consentire questa azione?" e tu clicchi sì, è un fallimento di configurazione, non una funzionalità.

il codice sorgente rivela una cascata di impostazioni a 5 livelli:

1policy > flag > local > project > user

in ~/.claude/settings.json puoi impostare pattern glob per ciò che è sempre consentito:

1{
2  "permissions": {
3    "allow": [
4      "Bash(npm *)",
5      "Bash(git *)",
6      "Edit(src/**)",
7      "Write(src/**)"
8    ]
9  }
10}

ci sono tre modalità di permesso:

• bypass — nessun controllo di permesso (pericoloso ma veloce)

• allowEdits — consente automaticamente le modifiche ai file nella tua directory di lavoro

• auto (questa è nuova) — esegue un classificatore LLM su ogni azione. questo è il punto giusto.

la modalità auto ha le sue liste allow/deny che puoi configurare. il codice sorgente mostra che esegue più risolutori in parallelo: click utente, classificatore hook, bridge, e il primo che risponde vince.

ogni volta che ti fermi a cliccare "consenti" è tempo sprecato. configuralo una volta. non cliccare mai più.

4. ci sono 5 strategie di compattazione. la pressione del contesto è un problema reale

il codice sorgente ha CINQUE modi diversi per comprimere la conversazione quando diventa troppo lunga:

1. microcompact — pulizia basata sul tempo dei vecchi risultati degli strumenti

1. context collapse — riassume parti della conversazione

1. session memory — estrae il contesto chiave in un file

1. full compact — riassume l'intera cronologia

1. PTL truncation — elimina i gruppi di messaggi più vecchi

questo ci dice una cosa importante: l'overflow del contesto è un problema centrale su cui gli ingegneri hanno speso MOLTO tempo.

cosa significa per te:

• usa /compact proattivamente. non aspettare che il sistema compatti automaticamente e perda contesto che ti interessa.

• la finestra predefinita è 200K token. ma puoi optare per 1M token usando il suffisso [1m] del modello. per grandi refactor su molti file, questo conta.

• le sessioni lunghe accumulano "session memory" — riassunti strutturati di specifiche delle attività, elenchi di file, stato del workflow, errori e apprendimenti. ecco perché riprendere una sessione è meglio che iniziare da zero.

• i risultati grandi degli strumenti vengono salvati su disco con solo un'anteprima di 8KB inviata al modello. se incolli un file enorme, il modello potrebbe vedere solo una frazione. mantieni gli input focalizzati.

le persone che ottengono il massimo da claude code usano /compact come un punto di salvataggio manuale in un videogioco. preserva ciò che conta, cancella ciò che non conta, e continua.

5. il sistema di hook è la vera API di estensione (25+ eventi del ciclo di vita)

questa è la funzionalità per power user che quasi nessuno conosce.

il codice sorgente rivela 25+ eventi del ciclo di vita a cui puoi agganciarti:

• PreToolUse — viene eseguito prima che qualsiasi strumento venga eseguito

• PostToolUse — viene eseguito dopo che qualsiasi strumento viene eseguito

• UserPromptSubmit — viene eseguito quando invii un messaggio

• SessionStart / SessionEnd — ciclo di vita della sessione

• e altri 20+

con 5 tipi di hook:

• command — esegue un comando shell

• prompt — inietta contesto tramite LLM

• agent — esegue un ciclo di verifica completo dell'agente

• HTTP — chiama un webhook

• function — esegue JS

esempi reali di cosa puoi fare:

• eseguire automaticamente il linting prima di ogni scrittura di file

• eseguire i test dopo ogni modifica

• iniettare automaticamente documentazione rilevante in ogni prompt

• inviare una notifica Slack quando un'attività viene completata

• validare che i pattern di sicurezza siano seguiti prima che il codice venga distribuito

l'hook UserPromptSubmit è particolarmente folle. puoi iniettare additionalContext in ogni singolo messaggio che invii. immagina di allegare automaticamente output di test, diff git recenti o stato del progetto a ogni prompt senza doverlo scrivere.

è così che costruisci un ambiente di sviluppo personalizzato sopra claude code. non migliorando i prompt. ma agganciandoti al sistema stesso.

6. le sessioni sono persistenti e riprendibili (smetti di iniziare da capo)

ogni conversazione viene salvata come JSONL in

1~/.claude/projects/{hash}/{sessionId}.jsonl

il codice sorgente supporta:

• --continue — riprendi la tua ultima sessione

• --resume — scegli una sessione passata specifica

• --fork-session — dirama da una conversazione passata (personalmente adoro questo)

l'estrazione della memoria della sessione preserva il contesto chiave durante le compattazioni: specifiche delle attività, elenchi di file, stato del workflow, errori e apprendimenti.

la maggior parte delle persone avvia una nuova sessione ogni volta che apre claude code. è come chiudere il tuo IDE e riaprirlo da zero ogni ora. tutto il contesto su cosa stavi facendo, cosa è fallito, cosa hai imparato — sparito.

usa --continue. sempre. lascia che il contesto si accumuli. lascia che la memoria della sessione costruisca apprendimenti nel tempo. il codice sorgente ha letteralmente infrastruttura per questo. usala.

7. il sistema di strumenti esegue 60+ strumenti con batching intelligente

claude code ha 60+ strumenti integrati. ma la parte interessante è COME li esegue.

il codice sorgente suddivide le chiamate agli strumenti in due categorie:

• concurrent — operazioni di sola lettura (leggere file, cercare, globbing) vengono eseguite in parallelo

• serial — operazioni di mutazione (modifiche, scritture, comandi bash) vengono eseguite una alla volta

questo significa che quando claude code deve leggere 10 file per capire la tua codebase, li legge tutti e 10 simultaneamente. ma quando deve modificare 3 file, li fa uno alla volta per evitare conflitti.

oltre agli strumenti integrati, puoi collegare server MCP che aggiungono più strumenti. il codice sorgente usa caricamento differito. gli strumenti MCP vengono caricati solo quando necessario, quindi collegare 5 server MCP non rallenta ogni richiesta.

e c'è ToolSearch per la scoperta differita di strumenti che l'agente non conosce ancora.

il takeaway pratico: se il tuo workflow coinvolge sistemi esterni (database, provider cloud, CI/CD), collega server MCP per loro. l'architettura gestisce la complessità. tu ottieni solo più capacità.

8. l'architettura di streaming rende l'interruzione economica

l'intera pipeline utilizza generatori asincroni che emettono eventi individuali. premere Escape interrompe pulitamente lo stream corrente senza perdere il contesto precedente.

sembra una cosa piccola ma cambia come dovresti usare claude code.

non aspettare una risposta che sai sta andando male. interrompi immediatamente e reindirizza. il codice sorgente è progettato per questo. il tuo contesto precedente è preservato. la risposta interrotta viene scartata pulitamente. zero penalità.

pensalo come programmare in coppia. se il tuo compagno inizia a prendere la strada sbagliata, non aspetti che finisca. dici "in realtà, vai da questa parte". stessa energia.

9. il sistema di retry è più sofisticato di quanto pensi

il codice sorgente rivela:

• 10 tentativi con backoff esponenziale e jitter (base 500ms)

• aggiornamento automatico del token OAuth su 401/403

• fallback del modello: se Opus fallisce 3 volte con errori 529, cade automaticamente su Sonnet

• watchdog di 90 secondi su stream inattivi — se lo streaming si blocca, cade su non-streaming

• la modalità persistente ha retry infinito con backoff massimo di 5 minuti

questo significa che claude code è progettato per essere lasciato in esecuzione. gestisce intoppi dell'API, limiti di velocità e interruzioni con grazia. non devi stargli dietro. lascialo eseguire in background e torna ai risultati.

il riassunto: le azioni a più alta leva dal codice sorgente

• scrivi un vero CLAUDE.md → caricato a ogni turno. 40K caratteri. configurazione a più alta leva.

• parallelizza con i sottoagenti → il modello fork condivide la cache dei prompt. 5 agenti ≈ costo di 1.

• configura i permessi in settings.json → elimina la fatica dei clic per sempre.

• usa /compact proattivamente → 5 strategie di compattazione esistono perché la pressione del contesto è reale.

• imposta gli hook → 25+ eventi, 5 tipi. questa è la vera API di estensione.

• usa sempre --continue per le sessioni → persistenza JSONL + session memory = contesto accumulato.

• collega server MCP → caricamento differito significa costo zero finché non vengono usati.

• interrompi liberamente → i generatori asincroni significano zero penalità per il reindirizzamento.

il punto fondamentale: claude code è una piattaforma di orchestrazione di agenti con un'interfaccia a terminale.

le persone che ottengono 10x output da esso non sono migliori a scrivere prompt. lo hanno configurato. lo hanno parallelizzato. si sono agganciati ad esso. hanno lasciato che il contesto si accumulasse tra le sessioni.

il codice sorgente lo rende ovvio. ora sai cosa fa realmente sotto il cofano.

rt se hai trovato utile questo post 🫶