Guida completa a Claude Code 2.0 per sviluppatori: dalle domande secondarie alla code review multi-agente

Claude Code 2.0 si comprende meglio se lo si considera un sistema di lavoro, non una gigantesca casella di autocompletamento. Il vero salto di qualità risiede nel modello operativo attorno all'agente: domande secondarie che non inquinano il thread principale, controlli ripetuti in background mentre si lavora, regolazione dell'effort (lo sforzo del modello) per adeguare il ragionamento al rischio, skill che caricano le procedure solo quando servono, una memoria che sopravvive alle nuove sessioni e agenti di revisione in grado di ispezionare una pull request da diverse angolazioni.

A partire dall'11 agosto 2026, la versione locale di Claude Code verificata per questa guida è la 2.1.227. Il changelog ufficiale di Claude Code indica la v2.1.227 come release corrente nella documentazione, con correzioni all'affidabilità per i feature flag, l'esecuzione di Bash per le GitHub Action, /tui, il comportamento del menu dei comandi slash e le performance. Il prodotto evolve rapidamente, quindi considerate questo documento come una guida all'implementazione per l'attuale linea 2.1.x, non come un manuale statico.

Se state ancora valutando se un workflow di coding agentico sia adatto al vostro team, partite dalle basi: Claude Code può leggere una repo, eseguire comandi, modificare file e verificare i risultati all'interno del loop di un agente. La domanda non è più "sa scrivere codice?". La domanda è se avete un processo sufficiente attorno ad esso per mantenere utile quel loop. Questo è lo stesso motivo per cui separiamo l'implementazione dell'agente dalla sperimentazione dei prompt nella nostra guida all'implementazione di agenti AI e nel nostro lavoro sui workflow di coding agentico.

Il modello mentale: proteggere il thread principale

L'errore centrale con gli agenti di coding è trattare la conversazione come un blocco appunti infinito. Ogni domanda secondaria, log incollato, tentativo fallito, piano abbozzato e richiesta "già che ci sei" compete per il contesto. Claude Code 2.0 offre agli sviluppatori più modi per suddividere quel lavoro:

• Usa /btw quando la risposta non deve entrare a far parte della cronologia principale.
• Usa un subagente (subagent) quando serve utilizzare tool, leggere file o esplorare in un contesto separato.
• Usa /loop quando un controllo deve ripetersi senza che tu debba sollecitarlo manualmente.
• Usa le skill quando un workflow è abbastanza ripetibile da meritare una procedura locale.
• Usa la memoria quando una regola o una correzione deve sopravvivere alla prossima nuova sessione.

Questo è il cambiamento pratico. Un buon setup di Claude Code non è "un gigantesco file CLAUDE.md". È un insieme di canali piccoli e ben circoscritti, adatti al giusto tipo di contesto.

/btw: chiedere senza inquinare la cronologia

Il riferimento ufficiale ai Comandi descrive /btw [domanda] come una rapida domanda secondaria che non si aggiunge alla conversazione. La documentazione sulla Modalità Interattiva rende la distinzione più netta: /btw vede l'intera conversazione ma non ha accesso ai tool, mentre un subagente ha i tool ma parte con un contesto vuoto.

Questo rende /btw perfetto per domande come:

/btw cosa abbiamo deciso sull'ordine di migrazione?
/btw questo errore deriva probabilmente dal test runner o dal database?
/btw riassumi in un paragrafo le parti rischiose del diff finora

Usa /btw quando hai bisogno di una risposta basata su ciò che Claude sa già. Non usarlo per analizzare un file, ispezionare log, chiamare un'API o verificare un'affermazione. Quello è lavoro da subagente. La regola d'oro è semplice: se l'inciso non dovrebbe cambiare il piano e non ha bisogno di tool, usa /btw. Se la risposta potrebbe influenzare l'implementazione, riportala nel thread principale o assegna un subagente.

Questo è importante per le sessioni lunghe. Claude Code ora può riaprire il recente overlay di /btw senza una nuova domanda, rendendo il canale secondario una sorta di taccuino leggero per ragionamenti transitori. Non è un sostituto per la memoria di progetto, ma un modo per evitare che il tuo log di lavoro diventi un cassetto delle cianfrusaglie.

/loop: rendere l'attesa esplicita

Lo stesso riferimento ai comandi definisce /loop [intervallo] [prompt] come una funzione che esegue ripetutamente un prompt mantenendo la sessione aperta. L'intervallo è opzionale; Claude può autoregolarsi. Il prompt è opzionale se è disponibile la manutenzione autonoma o il file .claude/loop.md. L'alias è /proactive.

I loop utili sono noiosi:

/loop 5m verifica se il deploy di preview è terminato e segnalalo solo se lo stato cambia
/loop 10m riesegui il test instabile (flaky) e fermati dopo un'esecuzione pulita
/loop controlla la repo per evidenti lavori non finiti prima che io torni

I loop pessimi sono vaghi:

/loop migliora il progetto
/loop continua a ottimizzare questo codice

Un loop ha bisogno di una condizione di uscita. Altrimenti avrai creato uno stagista instancabile senza una definizione di "Fatto" (Definition of Done). La versione pigra da senior engineer consiste nel chiedere il più piccolo controllo ripetuto che elimini la necessità di fare polling manuale. Osserva un deploy. Riesegui un singolo test. Controlla se una lunga migrazione ha finito. Non trasformare /loop in un product manager in background.

Per i sistemi di agenti in produzione, questo è lo stesso pattern che usiamo nei servizi di automazione AI: i controlli ripetibili sono utili quando lo stato è osservabile e l'azione è limitata. Sono pericolosi quando l'obiettivo è sfocato.

/effort: adeguare il ragionamento al rischio

/effort [level|auto] ti permette di impostare lo sforzo computazionale (effort) del modello. La documentazione elenca low, medium, high, xhigh, max e ultracode, con disponibilità a seconda del modello. Può essere modificato tramite uno slider interattivo e ha effetto immediato.

Usa i livelli di effort come le marce di un motore ingegneristico:

Non lasciare ogni task al massimo dell'effort. Non è sinonimo di rigore, ma solo un'impostazione predefinita costosa. L'abitudine migliore è alzare l'effort solo quando la superficie decisionale si allarga. Se un task tocca questioni finanziarie, autenticazione, potenziale perdita di dati, deployment o pacchetti multipli, aumenta l'effort. Se il task è meccanico e i test sono veloci, tienilo basso e procedi alla verifica.

/dataviz: i grafici richiedono regole di design, non solo SVG

La documentazione descrive /dataviz [richiesta] come una skill per diagrammi, grafici e dashboard. Sceglie il tipo di grafico, assegna i colori in base al ruolo, valida le palette per la sicurezza dei daltonici e per il contrasto, e applica regole di marcatura, interazione e accessibilità.

La parola chiave è "skill". /dataviz non è un senso estetico magico per i grafici. È una procedura pacchettizzata che aiuta Claude a prendere decisioni migliori su tipo di grafico, colore e accessibilità. Usala per report tecnici, dashboard di rilascio, riepiloghi di regressioni, curve di costo, confronti di benchmark e timeline degli incidenti.

Una buona richiesta si presenta così:

/dataviz trasforma questo CSV sulla latenza in un grafico prima/dopo per una code review tecnica. Mostra p50, p95 e p99. Rendi ovvia la regressione senza usare solo il rosso/verde.

Una pessima richiesta è "fai un grafico figo". Il vincolo utile è la decisione che il grafico dovrebbe supportare. Se una visualizzazione non cambia ciò che un lettore comprende o farà dopo, non farla.

Agent Skills: spostare il lavoro ripetibile fuori dalla chat

La documentazione sulle Skill spiega il meccanismo di base: una skill è un file SKILL.md con istruzioni che Claude può caricare quando pertinenti o quando invocate direttamente. A differenza della memoria sempre caricata, il corpo di una skill si carica solo quando viene utilizzata. I comandi personalizzati e le skill sono effettivamente conversi: un file di comando e una skill possono entrambi creare un comportamento di comando slash.

Questa è un'ottima notizia per i team. Significa che potete smettere di incollare la stessa checklist in ogni sessione:

• "Come facciamo la review delle migrazioni" diventa una skill per la review delle migrazioni.
• "Come prepariamo le note di rilascio" diventa una skill per le release note.
• "Come eseguiamo il debug dei webhook di pagamento" diventa una skill per il debug dei pagamenti.
• "Come facciamo i controlli di regressione visiva" diventa una skill di verifica.

Tieni le skill brevi all'inizio e metti esempi corposi, template e script in file di supporto. La documentazione supporta esplicitamente template, esempi, script e documentazione di riferimento accanto a SKILL.md. Questo ti fornisce un pattern pulito: è la skill a decidere cosa caricare, non il tuo system prompt.

Per una strategia più profonda a riguardo, vedi il nostro articolo context engineering per agenti AI. Il principio è lo stesso: il contesto è un budget. Spendilo solo quando cambia l'azione successiva.

Memoria: CLAUDE.md non è una discarica

La documentazione sulla Memoria dice che ogni sessione di Claude Code inizia con una context window vuota. La continuità deriva da due meccanismi: i file CLAUDE.md e l'auto-memory. CLAUDE.md contiene istruzioni e regole scritte dall'utente a livello di progetto, di utente o di organizzazione. L'auto-memory contiene apprendimenti e pattern scritti da Claude, memorizzati per repository e condivisi tra worktree, con le prime 200 righe o 25KB caricati in ogni sessione.

La gerarchia pratica della memoria dovrebbe essere:

1. Regole ferree: mettile in CLAUDE.md o negli hook.
2. Procedure ripetibili: mettile nelle skill.
3. Preferenze scoperte: lascia che l'auto-memory le catturi, poi sistemale se diventano importanti.
4. Fatti temporanei della sessione: tienili nella conversazione o in /btw, non nella memoria.

Non scrivere tour architettonici nella memoria se Claude può ispezionare la repo. Invece scrivi regole che non sono ovvie dal codice: "non eseguire mai lo script di ripristino distruttivo in produzione", "le offerte usano i centesimi, non gli euro", "i post di LinkedIn devono andare sulla pagina aziendale". Sono i dettagli a prevenire errori costosi.

Code review multi-agente: seconda linea, non autorità finale

La documentazione sulla Code Review descrive la funzione di managed review come un'anteprima di ricerca per Team ed Enterprise. Analizza le pull request di GitHub, pubblica commenti inline e usa una flotta di agenti specializzati per ispezionare l'intero contesto della codebase alla ricerca di errori logici, vulnerabilità di sicurezza, edge case rotti e regressioni. I risultati vengono taggati per gravità e non approvano né bloccano la PR. Su altri piani, il comando locale /code-review è comunque disponibile nel terminale.

Quest'ultimo vincolo è sano. La code review multi-agente non dovrebbe sostituire la responsabilità (ownership). Dovrebbe intercettare ciò che gli umani si lasciano sfuggire quando il diff è grande, il revisore è stanco o l'edge case è sepolto in un altro file.

Usala prima di una review umana quando:

• la modifica attraversa i confini del pacchetto,
• il branch tocca auth, pagamenti, permessi o cancellazione dati,
• il diff contiene codice generato,
• l'implementazione è stata scritta per la maggior parte da agenti,
• il revisore ha bisogno di una mappa dei rischi prima di leggere ogni riga.

Non usarla come timbro di approvazione a occhi chiusi. Un agente di review può far emergere i rischi, ma il tuo team è sempre il responsabile finale del merge.

Un setup pratico per un team

Se state adottando Claude Code 2.0 all'interno di un team, iniziate in piccolo:

1. Installate e confermate la versione con claude --version.
2. Aggiungete un CLAUDE.md minimale contenente solo le regole non ovvie.
3. Create una singola skill per il workflow più ripetuto.
4. Insegnate agli ingegneri quando usare /btw rispetto a un subagente.
5. Definite i default per l'effort in base alla categoria di rischio.
6. Aggiungete /code-review prima della review umana sui branch di grandi dimensioni.
7. Usate /loop solo per controlli osservabili con condizioni di stop chiare.

Questo è sufficiente. Non vi serve una piattaforma completa dal giorno zero. La prima vittoria è un loop più pulito: raccogli il contesto, agisci, verifica e mantieni il rumore fuori dal thread principale.

Definition of Done (Definizione di Fatto) per l'adozione di Claude Code 2.0

• CLAUDE.md esiste e contiene solo regole di progetto attuali e non ovvie.
• Almeno un workflow del team è passato da un prompt incollato a una skill.
• Gli sviluppatori conoscono la regola tra /btw e subagente.
• I livelli di effort sono documentati per compiti a basso rischio, normali e ad alto rischio.
• /code-review fa parte della checklist della PR per diff rischiosi o fortemente agentici.
• Un prompt di /loop include un intervallo concreto, una condizione osservabile e una regola di stop.
• La memoria viene rivista mensilmente affinché le regole obsolete non diventino debito tecnico nascosto.

FAQ

Claude Code 2.0 è la stessa cosa di Claude Code v2.1.227?

Non esattamente. "Claude Code 2.0" è la generazione del prodotto a cui le persone si riferiscono; v2.1.227 è la release attuale verificata per questa guida l'11 agosto 2026. Il numero di versione aumenta frequentemente — a volte giornalmente — con fix sull'affidabilità, nuovi comandi slash e modifiche ai feature flag. Verificate sempre la versione installata con claude --version e incrociate i dati con il changelog ufficiale prima di fare affidamento su una funzionalità specifica. Se state scrivendo documentazione o guide per il team, fissate la versione contro cui avete fatto i test e annotate la data di verifica.

Quando dovrei usare /btw invece di un subagente?

Usa /btw quando la risposta dipende dal contesto della conversazione corrente e non necessita di tool. Ad esempio, se vuoi un rapido riassunto di ciò che è stato deciso fino a quel momento, o un controllo di validità per capire se un pattern di errore corrisponde a qualcosa di già discusso, /btw è la scelta giusta. Usa un subagente quando Claude ha bisogno di ispezionare file, eseguire comandi, cercare nei log o esplorare qualcosa senza riempire il contesto principale. Un subagente parte con una context window vuota ma ha accesso completo ai tool, il che lo rende ideale per lavori investigativi che non dovrebbero inquinare la tua cronologia di lavoro. La regola pratica: se l'inciso non cambia il piano e non ha bisogno di tool, usa /btw. Se la risposta può influenzare l'implementazione, riportala nel thread principale o assegna un subagente.

Per cosa è più indicato /loop?

/loop è ideale per controlli ripetuti e osservabili: stato del deploy, test instabili (flaky), completamento di una coda, scansioni di pulizia o manutenzione periodica. La chiave è che ogni iterazione deve avere una chiara condizione di uscita — "fermati dopo un passaggio pulito" o "segnala solo se lo stato cambia". Evita loop vaghi come "continua a migliorare questa cosa", perché creano lavoro senza un traguardo, consumando token all'infinito. Un loop ben progettato sostituisce il polling manuale: invece di controllare il deploy ogni 5 minuti da solo, deleghi la cosa a Claude e vieni notificato solo se cambia qualcosa. Per i sistemi di agenti in produzione, è lo stesso pattern che usiamo per il monitoraggio automatizzato — i controlli ripetibili sono utili quando lo stato è osservabile e l'azione è vincolata.

Quale livello di /effort dovrei usare?

Usa l'effort più basso per le modifiche meccaniche con una verifica economica — rinominazioni, formattazioni, fix semplici ai test. Alza l'effort per le decisioni di architettura, il debug di problemi complessi, la review di sicurezza, le migrazioni dei dati e qualsiasi cosa in cui una risposta sbagliata sia costosa. Lo slider dell'effort non riguarda la qualità; serve ad adeguare la profondità del ragionamento al rischio. Una rinominazione a effort max spreca token senza migliorare il risultato. Una migrazione dati a effort low risparmia token ma rischia una subdola perdita di dati. L'approccio pratico è definire i default del team per categoria di task: low per le modifiche meccaniche, medium per il normale lavoro sulle feature, high per il debugging e xhigh/max per tutto ciò che tocca auth, pagamenti o integrità dei dati. Rivedi i default mensilmente con l'evolvere del modello e dei tool.

Le Agent Skill sostituiscono CLAUDE.md?

No. CLAUDE.md serve per istruzioni e regole persistenti che si applicano a ogni sessione — standard di codice, convenzioni di progetto, regole di sicurezza. Le skill servono per procedure ripetibili che dovrebbero caricarsi solo quando pertinenti — una checklist di migrazione, un template per le note di rilascio, un workflow di debug. Se una checklist è lunga o specifica per un task, probabilmente appartiene a una skill, non alla memoria. I due meccanismi si completano a vicenda: CLAUDE.md stabilisce le regole di base e le skill forniscono procedure passo-passo che si attivano su richiesta. Pensa a CLAUDE.md come al manuale del team e alle skill come ai runbook. L'auto-memory cattura preferenze e pattern scoperti che né il manuale né i runbook coprono ancora.

La code review multi-agente può sostituire la review umana?

No. È una seconda linea di difesa, non un sostituto del giudizio umano. La review di Claude Code può far emergere bug, problemi di sicurezza, edge case e regressioni che a un revisore stanco potrebbero sfuggire su un grande diff. Ma il team detiene sempre l'ultima parola sulla decisione di fare merge. La review multi-agente dà il meglio di sé prima di una review umana quando il cambiamento attraversa i confini dei pacchetti, tocca auth o pagamenti, contiene codice generato, o è stato scritto per lo più da agenti. In quei casi, gli agenti di review producono una mappa dei rischi che aiuta il revisore umano a concentrarsi subito sulle aree a più alta criticità. Trattalo come un moltiplicatore di forza — cattura ciò che gli umani si perdono, ma non ha il contesto per decidere cosa sia accettabile per il vostro prodotto.

Fonti

• Changelog di Claude Code — Storico delle versioni e note di rilascio per la linea 2.1.x
• Riferimento Comandi di Claude Code — Documentazione ufficiale per /btw, /loop, /effort, /dataviz e altri comandi slash
• Modalità Interattiva di Claude Code — Comportamento di subagenti e /btw, regole di isolamento del contesto
• Skill di Claude Code — Formato SKILL.md, file di supporto e invocazione delle skill
• Memoria di Claude Code — Gerarchia di CLAUDE.md, auto-memory e continuità di sessione
• Code Review di Claude Code — PR review multi-agente, classificazione per gravità e funzionalità di managed review