Claude Code: best practice — Pianificazione, trasferimento del contesto, TDD

Claude Code premia un tipo di disciplina che la maggior parte degli strumenti per sviluppatori non richiede. Se lo usi da un po’, avrai notato che alcune sessioni producono esattamente ciò che vuoi, mentre altre bruciano token senza andare da nessuna parte. Il team di Anthropic ha riscontrato che i tentativi senza guida riescono circa il 33% delle volte, e il creatore dello strumento abbandona il 10-20% delle sessioni. 

La differenza dipende dai pattern che costruisci attorno allo strumento, non dai prompt che digiti.

Questo articolo mostra come appaiono questi pattern nella pratica, prendendo spunto dai flussi produttivi di aziende come Abnormal AI, incident.io e Trail of Bits. 

Se ti serve un ripasso su setup e funzionalità di base, la nostra guida su Claude Code 2.1 fa al caso tuo. Qui di seguito diamo per scontato che tu conosca già le basi e voglia ottenere di più dallo strumento.

Per una panoramica più ampia su come ragionano gli agenti e su dove si inseriscono i pattern di questo tutorial, consiglio vivamente di iscriverti al nostro percorso AI Agent Fundamentals, che copre tutti i principi sottostanti.

Perché la disciplina nella pianificazione cambia tutto

Ogni decisione che Claude prende senza guida può avere un’alta accuratezza, il che suona accettabile per una singola scelta, ma cumulata lungo una funzionalità con molti punti decisionali, la probabilità di azzeccarle tutte diminuisce. Se ipotizzi l’80% di accuratezza per 20 decisioni, ottieni 0,8^20, quindi circa solo l’1% di probabilità di un’implementazione completamente corretta.

La pianificazione comprime quelle 20 decisioni ambigue in una specifica revisionata, in cui ognuna si avvicina al 100% perché la scelta l’hai già presa tu.

Pianificare con il workflow a ciclo di annotazione

Il workflow di pianificazione che funziona meglio su larga scala è un ciclo di annotazione, come suggerisce Boris Tane. Fai redigere a Claude un plan.md, lo apri nel tuo editor e aggiungi note in linea ovunque Claude abbia scelto male o lasciato ambiguità: "usa drizzle:generate, non SQL grezzo" oppure "qui deve essere PATCH, non PUT." 

Poi rimandi il piano annotato con la frase di guardia "address all notes, don't implement yet." Quella frase è importante perché senza di essa Claude salta il piano e inizia subito a scrivere codice. Il ciclo si ripete finché non resta più ambiguità, momento in cui Claude implementa con molti meno errori di percorso perché ogni decisione è già stata presa.

# plan.md — annotation cycle
 
## Step 3: Database migration
Create a new migration for the users table.
> NOTE: use drizzle:generate, not raw SQL
> NOTE: add created_at with default NOW()
 
## Step 4: API endpoint
Add PUT /users/:id endpoint.
> NOTE: this should be PATCH, not PUT. Partial updates only.
 
# After annotating, send back with:
# "address all notes, don't implement yet"

Usare la modalità piano di Claude Code

Se i cicli di annotazione ti sembrano pesanti, la modalità piano integrata di Claude Code è un’opzione più leggera: 

1. Premi Shift+Tab due volte.
2. Itera il piano in conversazione.
3. Passa all’accettazione automatica con Shift+Tab una volta. 

I piani vengono salvati in ~/.claude/plans/, quindi sopravvivono a compattazioni e riavvii di sessione, rendendo la modalità piano integrata un’ottima impostazione predefinita per la maggior parte dei task. Per funzionalità molto grandi, funziona bene anche scrivere una specifica completa all’inizio: uno sviluppatore ha passato due ore su una specifica in 12 passaggi e ha stimato di aver risparmiato 6-10 ore di implementazione. 

Spingersi oltre nella pianificazione

A prescindere dall’approccio, incollare buon codice open source insieme alla richiesta di piano migliora visibilmente l’output perché Claude lavora meglio con un riferimento funzionante che con descrizioni astratte.

La pianificazione scala anche orizzontalmente tramite i git worktrees. Gli ingegneri di incident.io eseguono 4-5 sessioni Claude in parallelo su branch separati, ciascuna con il proprio piano. Un ingegnere ha speso 8$ di credito Claude e ha prodotto un’implementazione che ha migliorato del 18% i tempi di generazione dell’API, risparmiando 30 secondi su uno strumento usato quotidianamente da tutto il team. 

Alcuni sviluppatori spingono oltre, eseguendo worktree concorrenti che implementano approcci diversi allo stesso problema e confrontano i risultati.

Best practice architetturali per CLAUDE.md

Il tuo file CLAUDE.md ha un budget di cui probabilmente non sei a conoscenza. L’analisi di HumanLayer sugli internals di Claude Code ha scoperto che il sistema inietta un promemoria sopra le tue istruzioni: "This context may or may not be relevant to your tasks." 

Capire il sistema di istruzioni a livelli di Claude Code

Claude filtra attivamente ciò che segue, invece di trattare tutto come un comando persistente. Inoltre, i modelli di frontiera seguono all’incirca 150-200 istruzioni prima che la compliance cali, e il system prompt di Claude Code ne occupa circa 50. Questo lascia circa 100-150 slot per le tue regole. HumanLayer mantiene il proprio file sotto le 60 righe.

Puoi osservare questo budget in azione. Aggiungi una riga al tuo CLAUDE.md dicendo "always address me as Mr. Tinkleberry" e guarda quanto in fretta Claude smette di usarlo, solitamente entro poche migliaia di token. Quando il nome scompare, le tue istruzioni vengono de-prioritizzate dal meccanismo di attenzione e tutto il resto nel tuo CLAUDE.md perde influenza insieme a loro.

Usare la divulgazione progressiva per i riferimenti alle istruzioni

Il modo per rimanere entro questo budget è la divulgazione progressiva. Il tuo CLAUDE.md radice rimane breve e focalizzato sulle regole valide ovunque. Per tutto ciò che è specifico di dominio, rimanda a un file separato senza inlined: "Quando lavori con il sistema di pagamento, leggi prima docs/payment-architecture.md." 

Claude legge il file referenziato solo quando entra in quella parte della codebase, mantenendo libero il tuo budget di istruzioni per le regole ad alta priorità. Un’azienda che consuma miliardi di token al mese struttura così il proprio CLAUDE.md del monorepo, con a ogni team assegnato un budget di token per la propria sezione:

# Monorepo CLAUDE.md — progressive disclosure
 
## Python
- Always use type hints for function signatures
- Test with: pytest -x --tb=short
 
## <Internal CLI Tool>
- <usage example>
- Always validate input before processing
- Never use raw SQL, prefer the ORM
For <complex usage> or <error> see path/to/<tool>_docs.md

I file CLAUDE.md nelle sottodirectory estendono ulteriormente questo approccio. Metti un CLAUDE.md in src/persistence/ con istruzioni specifiche per il database e un altro in src/api/ con le convenzioni sugli endpoint. 

Claude carica automaticamente i file CLAUDE.md dalla directory di lavoro verso l’alto fino alla radice del progetto, quindi i file nelle sottodirectory si attivano solo quando Claude lavora in quell’area. Questo mantiene generale il file radice offrendo a Claude indicazioni mirate esattamente dove servono.

Un errore comune: non inserire documentazione tramite @-file in CLAUDE.md. In questo modo incorpori l’intero file a ogni esecuzione, divorando il tuo budget di istruzioni prima ancora che la conversazione inizi.

Gestione del contesto in Claude Code

Claude Code ti dà 200K token di contesto, ma la finestra utilizzabile è più piccola di quanto sembri. 

Una sessione monorepo nuova di zecca brucia circa 20K token per caricare system prompt, definizioni degli strumenti e CLAUDE.md prima ancora che tu digiti qualcosa. Ogni server MCP aggiunge schemi di tool che consumano permanentemente contesto, quindi il limite pratico è circa 5-8 server prima di iniziare a togliere spazio al lavoro reale.

A peggiorare le cose c’è il calo precoce di qualità. Più praticanti, indipendentemente, sono arrivati alla stessa soglia: non superare il 60% di capacità del contesto. 

L’output di Claude inizia a degradare al 20-40% della finestra, ben prima che scatti qualunque limite, perché il meccanismo di attenzione assegna meno peso alle istruzioni iniziali man mano che il contesto si riempie. 

L’auto-compattazione scatta intorno all’83,5% ed è lossly: uno sviluppatore ha perso 3 ore di lavoro di refactoring quando ha cancellato tutte le decisioni sulle migrazioni a metà sessione, mantenendo solo circa il 20-30% dei dettagli.

Usare il pattern Document & Clear

La migliore difesa è il pattern Document & Clear. Quando il contesto si appesantisce: 

1. Scarica il piano e l’avanzamento attuali in un file markdown

2. Esegui /clear per resettare la sessione

3. Riparti da zero facendo leggere a Claude quel file

In questo modo ottieni una finestra intera da 200K solo con ciò che scegli di conservare, meglio di /compact perché controlli esattamente cosa sopravvive. 

Un comando personalizzato /catchup rende la transizione più fluida: dopo il clear, legge tutti i file cambiati nell’attuale branch git, così Claude riprende da dove eri rimasto senza la vecchia cronologia della conversazione.

<!-- .claude/commands/catchup.md -->
Rebuild context after a /clear. Read all files modified on the
current branch compared to main. For each file, understand the
changes made. Then summarize what's been implemented so far and
what work remains.
 
Changed files on this branch:
$ git diff --name-only main

Trasferire il contesto con skill personalizzate di Claude Code

Uso una /transfer-context skill che va oltre. Quando una sessione inizia a degradare, il comando scarica un file di passaggio di consegne strutturato con lavoro completato, decisioni aperte, trappole da evitare e percorsi file rilevanti. La sessione successiva legge quel file e riprende da dove l’ultima aveva lasciato, con solo le informazioni che contano e senza il gonfiore della conversazione.

Altre best practice per risparmiare contesto

Puoi anche risparmiare contesto in modo proattivo caricando gli strumenti in modo lazy. Un progetto ha recuperato circa 15.000 token per sessione usando hook UserPromptSubmit per iniettare le definizioni delle skill solo quando il prompt dell’utente attivava parole chiave rilevanti, invece di pre-caricare tutto all’avvio.

La regola più semplice alla base di tutto: un task per conversazione. Ripartire costa 20K token, nulla rispetto alla perdita di qualità di una sessione inquinata.

Hook di Claude Code come guardrail deterministici

Anche un CLAUDE.md ben strutturato viene seguito solo circa il 70% delle volte. Per preferenze di stile del codice va bene. Per regole di sicurezza come "non fare push su main" o "non cancellare dati di produzione" no. I hook colmano quel gap fino al 100% eseguendo script shell in punti specifici del workflow di Claude.

Ci sono due tipi da conoscere. Gli hook Block-at-Submit girano come eventi PreToolUse e bloccano le azioni sul nascere: il codice di uscita 2 blocca l’azione e costringe Claude a tentare altro. Gli hook di tipo hint forniscono feedback non bloccante, come eseguire un linter dopo ogni modifica e rimandare l’output senza interrompere il flusso di Claude.

La configurazione pubblica di hook più completa fa quanto segue:

• Blocca i comandi rm -rf (suggerendo trash in alternativa), 

• Impedisce push diretti su main, 

• Logga tutte le mutazioni con timestamp, e 

• Esegue un gate anti-razionalizzazione. 

Quel gate usa Haiku per rivedere le risposte di Claude e scovare scuse come "problemi preesistenti" o "fuori scope". Quando sorprende Claude a dichiarare vittoria prematura, rigetta la risposta con feedback specifico e lo costringe a continuare a lavorare. Una configurazione più leggera esegue automaticamente Prettier e i check TypeScript dopo ogni modifica file:

{
  "hooks": {
	"PostToolUse": [
  	{
    	"matcher": "Edit|Write",
    	"hooks": [
      	{
        	"type": "command",
        	"command": "prettier --write \"$CLAUDE_FILE_PATHS\""
      	}
    	]
  	}
	]
  }
}

Una trappola da evitare: non bloccare mai gli strumenti Edit o Write a metà piano. Bloccare in fase di scrittura interrompe il ragionamento multi-step perché Claude perde il filo. Lascialo finire di scrivere, poi valida tramite hook PostToolUse o check pre-commit. Il nostro tutorial sugli hook di Claude Code copre altri pattern se vuoi costruirci sopra.

Test-Driven Development come strategia ottimale di coding agentico

Senza test, l’unico modo per Claude di verificare il proprio lavoro è il suo stesso giudizio, che degrada man mano che il contesto si riempie. I test creano un oracolo esterno che resta accurato a prescindere da quanto a lungo giri la sessione. 

Ogni ciclo da rosso a verde dà a Claude un feedback non ambiguo, e può iterare su tutta la suite senza intervento umano, rendendo il test-driven development (TDD) il pattern più forte in assoluto per lavorare con strumenti di coding agentico.

Il workflow che consiglia Anthropic segue una sequenza specifica:

1. Write tests first
   > "Write tests for the auth module using pytest.
  	TDD approach, no mock implementations."
 
2. Confirm tests fail
   > "Run the tests. They should all fail."
 
3. Commit the failing tests as a checkpoint
 
4. Implement until green
   > "Write the implementation. Do not modify the tests.
  	Keep going until all tests pass."

Quell’ultima istruzione conta più di quanto sembri. A volte Claude cambia i test per farli passare invece di correggere l’implementazione. Fare il commit dei test in anticipo ti dà una rete di sicurezza: se Claude li modifica, il diff mostra esattamente cosa è cambiato e puoi ripristinare.

Per il frontend funziona bene una variante visiva di questo loop: se dai a Claude un mock di design più un server MCP Puppeteer, fa uno screenshot dopo l’implementazione, lo confronta con il mock e itera. Questo ciclo di verifica produce un miglioramento di qualità di 2-3x quando Claude può controllare il proprio output rispetto a un target visivo.

Economia dei costi di Claude Code e scelta del modello

I dati ufficiali di Anthropic riportano un costo medio di 6$ al giorno per sviluppatore con pricing API, con il 90% degli sviluppatori sotto i 12$/giorno. Su base mensile, si tratta di circa 100-200$ per sviluppatore con Sonnet 4.6.

Il piano in abbonamento Max cambia completamente l’equazione. Uno sviluppatore ha tracciato 8 mesi di utilizzo per circa 10 miliardi di token e ha scoperto che il suo costo equivalente API superava i 15.000$, mentre il costo reale dell’abbonamento Max era circa 800$: un risparmio del 93%. 

Oltre il 90% dei suoi token erano letture da cache, motivo per cui il pricing a consumo dell’API pesa molto di più rispetto a un abbonamento flat. Il punto di pareggio per il piano Max si colloca intorno ai 100-200$/mese di utilizzo equivalente API, una soglia che qualsiasi utente quotidiano supera rapidamente.

La scelta del modello è un’ottimizzazione a sé. La modalità "opusplan" di Claude Code instrada Opus 4.6 per la pianificazione e commuta automaticamente su Sonnet 4.6 per la generazione del codice, ottenendo il ragionamento di qualità Opus dove conta di più, usando le tariffe 5x più economiche di Sonnet per i token di implementazione. 

Sonnet 4.6 è stato preferito a Opus 4.5 dal 59% degli utenti di Claude Code nei test interni di Anthropic e tende a produrre codice più pulito con meno over-engineering. Per workflow ricchi di subagent, CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929" esegue i subagent su Sonnet mantenendo Opus per l’orchestratore.

Assicurati di evitare le tre principali fonti di spreco di token: 

• Non azzerare il contesto tra un task e l’altro 

• Letture di file ridondanti dovute a una struttura CLAUDE.md carente

• Prompt vaghi che spingono Claude in loop di tentativi ed errori

Correggere solo queste tre cose in genere dimezza l’uso di token.

Troubleshooting di Claude Code

Prima di chiudere, vediamo i problemi comuni che gli sviluppatori incontrano lavorando con Claude Code e come affrontarli.

Perdita di contesto

La modalità di fallimento più impattante è la perdita di contesto. Il pattern Document & Clear introdotto nella sezione sulla gestione del contesto esiste proprio per questo motivo: non lasciare mai che una sessione lunga sia l’unico registro di ciò che hai deciso. Fai commit frequentemente, scarica i progressi su file e tratta ogni sessione come usa e getta.

Allucinazioni con tecnologie di nicchia

Claude genera anche codice sicuro di sé e plausibile per tecnologie che non conosce bene. Se lavori in un linguaggio o framework che non puoi verificare personalmente, ogni output richiede un controllo extra. Come ha detto uno sviluppatore: "Mi sono cacciato in un MUCCHIO di guai usando LLM con tecnologie che non conosco. Ma con qualcosa che conosco, gli LLM hanno migliorato enormemente la mia velocità."

Over-engineering

L’over-engineering è una tendenza frequente. Claude scrive astrazioni extra, funzioni helper non richieste e refactoring prematuro se non gli dici di evitarlo. Aggiungere "usa l’approccio più semplice possibile" al tuo CLAUDE.md aiuta, e organizzare la codebase per domini di problema invece che per layer tecnici riduce il carico cognitivo sia per Claude che per gli umani.

Perdita di dati critici

Il fallimento più eclatante registrato: mentre si costruiva un’app di fonetica, Claude ha cancellato ogni file audio di fonemi per i quali uno sviluppatore aveva ottenuto personalmente l’autorizzazione d’uso e li ha sostituiti con suoni generati dall’IA. Ha rinominato file, si è "convinto di aver etichettato male, pur non essendo affatto in grado di distinguere i fonemi rilevanti." 

La lezione: fai sempre commit o backup dei file insostituibili prima di dare a Claude accesso ad essi.

Sessioni improduttive

Il consiglio di Anthropic per le sessioni che deragliano è sorprendentemente onesto: salva lo stato prima di far lavorare Claude, lascialo procedere, poi accetta il risultato o riparti da zero invece di accanirti con correzioni. 

Quanto fidarti di Claude con i commit dipende dalla copertura dei test e dalla tua tolleranza al rischio. Alcuni sviluppatori eseguono commit via slash command decine di volte al giorno, con la revisione PR come gate. Per codebase di produzione con utenti paganti, vale la pena rivedere ogni diff.

Mettere le mani in pasta con Claude Code

Per maggiori dettagli, la panoramica di Claude Code di Anthropic è la fonte canonica a monte su cui si basa la maggior parte dei contenuti della community. Se vuoi approfondire quanto trattato qui e fare pratica con diverse funzionalità di Claude Code, ecco alcuni dei nostri tutorial da leggere:

• Guida a Claude Code 2.1 — scopri le novità della versione 2.1, configura Claude Code ed esegui una serie di esperimenti mirati
• Tutorial sugli hook di Claude Code — approfondisci l’automazione basata su hook e impara a usarli per attività come test, formattazione e notifiche
• Usare Claude Code con i modelli locali di Ollama — esegui GLM 4.7 Flash in locale con Claude Code e Ollama per evitare il lock-in del fornitore e il trasferimento dati sul cloud
• Come creare plugin per Claude Code — scopri come installare estensioni, scegliere tra skill e MCP e creare un plugin personalizzato per il logging di sessione
• Claude Code Docker — impara a eseguire Claude Code in Docker per costruire ambienti isolati e padroneggiare pratiche di coding sicuro per agenti IA
• Claude Code Router — scopri come usare Claude Code Router per collegarti a più provider di modelli e usare l’LLM giusto per ogni task

Diversi progetti open source includono inoltre le pratiche discusse in questo articolo in configurazioni pronte all’uso:

• obra/superpowers — un framework di skill componibili che include enforcement del TDD, brainstorming socratico, pianificazione granulare e code review automatica tra i task. Ora è un plugin ufficiale nel marketplace di Anthropic.

• github/spec-kit — il toolkit ufficiale di GitHub per lo sviluppo guidato da specifica. Struttura il lavoro come Constitution → Specify → Plan → Tasks, rendendo la specifica l’unica fonte di verità per qualsiasi agente di coding.

• bmad-code-org/BMAD-METHOD — un framework agile completo con 12+ personae di agenti (Architect, QA, Scrum Master) e 34+ workflow che coprono l’intero ciclo di sviluppo.

• wshobson/commands — 57 slash command pronti per la produzione da inserire in .claude/commands/, inclusi 15 workflow multi-agente.

• awesome-claude-code — la directory di riferimento dell’ecosistema per skill, hook, comandi, agenti e plugin. Parti da qui se vuoi esplorare ciò che è disponibile.

Conclusione

Ogni pattern in questo articolo punta alla stessa idea: vincola Claude con decisione prima dell’esecuzione, poi dagli un modo per verificare il proprio output. La pianificazione elimina l’ambiguità. CLAUDE.md e gli hook fissano i confini. I test forniscono la verifica. L’igiene del contesto mantiene tutto funzionante tra le sessioni.

Se devi partire da un solo cambiamento, scegli Document & Clear. Il costo del marciume di contesto tra le sessioni supera di gran lunga i 20K token necessari per ripartire da zero. Dopo di che:

• Aggiungi un hook pre-commit che blocca i commit quando i test falliscono

• Inizia ogni task multi-file con un piano prima di toccare il codice

• Tieni il tuo CLAUDE.md sotto le 100 istruzioni e usa file nelle sottodirectory per regole specifiche di dominio

Abbiamo aggiunto di recente un nuovo skill track su AI Engineering with LangChain. I contenuti del corso sono nativi per l’IA, così puoi imparare insieme al tuo agente tutor personale. Ti consiglio di darci un’occhiata per diventare davvero esperto nell’ingegnerizzare workflow di IA.