Claude Code Plan Mode: cicli di refactoring con revisione del design prima dell’esecuzione

Molti sviluppatori iniziano a usare Claude Code nello stesso modo: incolla un task, lascialo eseguire e rivedi il diff. Funziona per piccole modifiche, ma appena si toccano più file il metodo inizia a scricchiolare. 

Ogni decisione non guidata che Claude prende potrebbe essere corretta la maggior parte delle volte, e fin qui tutto bene, finché non le sommi: ad esempio, se ipotizzi un 80% di accuratezza per decisione, su una feature con 20 punti decisionali, 0.8^20 fa scendere le probabilità a circa l’1%.

La Plan Mode cambia le carte in tavola aggiungendo una fase di sola lettura. Costringi Claude a leggere la codebase, far emergere domande e produrre un piano che tu rivedi prima che venga toccato anche solo un file. 

Questo tutorial illustra il flusso usando come esempio pratico una API di blog FastAPI disordinata, coprendo il ciclo Esplora-Pianifica-Esegui, la modifica del piano con Ctrl+G e la scalabilità verso refactor più ampi con Agent Teams. 

Il nostro tutorial sulle best practice di Claude Code approfondisce il problema degli errori composti, mentre la guida a Claude Code 2.1 ti accompagna in installazione e funzionalità se ti serve aiuto con il setup.

Per maggiori informazioni sui modelli dietro Claude Code, dai un’occhiata alle nostre guide su Claude Sonnet 4.6 e Opus 4.6, oppure segui il corso Introduzione ai modelli Claude.

Cos’è la Plan Mode di Claude Code?

La Plan Mode blocca Claude in operazioni di sola lettura. Può leggere file, cercare nella codebase e farti domande, ma qualsiasi tentativo di scrivere file, modificare codice o eseguire comandi shell viene rifiutato. Prova a chiedergli di “fare solo questa piccola correzione” mentre è in Plan Mode, e non si smuoverà.

Puoi attivarla in quattro modi:

• Shift+Tab due volte nel campo di input per scorrere tra Normal, Auto-Accept e Plan Mode

• Il comando /plan entra in Plan Mode finché non cambi modalità di nuovo

• Il flag CLI --permission-mode plan avvia una nuova sessione in Plan Mode

• Una voce settings.json sotto permissions.defaultMode imposta la Plan Mode come predefinita permanente

Quando Claude finisce di generare un piano, salva il risultato come file markdown in ~/.claude/plans/ con un nome generato casualmente (tipo dreamy-orbiting-quokka.md). 

Il file è un contratto revisionabile: persiste tra le sessioni, sopravvive sia a /clear che alla compattazione del contesto, e non viene implementato nulla finché non lo approvi. Nota che, sebbene il file del piano persista, dopo la compattazione del contesto Claude talvolta può perderne traccia, a meno che tu non lo inviti a rileggere il piano.

Se vuoi che i piani siano salvati all’interno del progetto per il controllo di versione, imposta plansDirectory in settings.json su un percorso relativo al progetto, ad esempio ./plans.

I piani relativi al progetto abilitano flussi di lavoro che ~/.claude/plans/ non può supportare:

• Rivedere i diff del piano nelle pull request prima che qualcuno inizi a scrivere codice
• Portare avanti le annotazioni tra sessioni senza dipendere dalla compattazione del contesto
• Trattare il file markdown come una specifica viva che più membri del team modificano direttamente

Per refactor di lunga durata o lavoro su più sessioni, un file di piano sotto versione ti dà più controllo rispetto al solo Ctrl+G.

Implementare un flusso Esplora-Pianifica-Esegui con Claude Code

Per vedere come le tre fasi lavorano insieme, effettueremo il refactoring di una repo fastapi-blog-api. Non include test e ha tre file che fanno ciascuno troppo: 

• main.py: tutte le route, controlli di autenticazione inline, config hardcoded, invio email

• models.py: modelli ORM, schemi Pydantic, funzioni di query, dati di seed

• utils.py: hashing password, token JWT, upload su S3, rendering markdown, caching, rate limiting, export CSV

Fase 1: Raccogli il contesto prima di tutto

Avvia il task in Plan Mode (clona prima in locale la repo GitHub). Il prompt iniziale dovrebbe dire a Claude cosa vuoi e indirizzarlo a leggere i file pertinenti:

I want to refactor this FastAPI blog API into a clean module structure with proper separation of concerns and full test coverage. Read through main.py, models.py, and utils.py first. Map out which functions belong together, flag any shared state or circular dependency risks, and identify what needs testing most.

Claude delega la ricerca della codebase a un sottagente integrato limitato agli strumenti di sola lettura. Ha letto tutti e tre i file, tracciato le importazioni tra loro e usato AskUserQuestion per far emergere le ambiguità. 

Le domande hanno coperto alcune decisioni di alto livello:

• Profondità architetturale (router piatti vs. layer di servizio completi)
• Come gestire la config hardcoded
• Se rimuovere o mantenere le funzioni utility non usate
• Quale framework di test usare

Quelle domande contano. La sola domanda sull’architettura sarebbe stata un lancio della moneta senza input umano. Claude tende ad adottare il pattern che ha visto più spesso nei dati di training che, per FastAPI, è di solito una struttura con router piatti. Rispondere "usa un service layer" qui ha evitato un intero giro di ri-refactoring più avanti.

Se hai un progetto di riferimento che corrisponde alla tua architettura target, includi un link nel prompt. Claude produce piani migliori quando può attingere a un esempio funzionante piuttosto che a descrizioni astratte.

Una cosa da controllare prima di accettare qualsiasi piano: le domande di Claude fanno riferimento a funzioni specifiche e dettagli a livello di riga, o solo ai nomi dei file? Se chiede del “sistema di auth” ma non menziona mai verify_jwt_token o la catena di middleware in main.py, ha dato solo un’occhiata veloce ai file invece di leggerli davvero. Spingilo a leggere con più attenzione prima di passare alla Fase 2.

Fase 2: Genera e modifica il piano

Dopo che hai risposto alle domande di Claude, genera automaticamente un piano. Non serve un prompt separato. Il piano viene salvato in ~/.claude/plans/ e include: 

• Riepilogo del contesto
• Struttura delle directory target
• Ordine di implementazione passo dopo passo
• Sezione di verifica con comandi per confermare che il refactoring funzioni

Prima di decidere come procedere, premi Ctrl+G per aprire il piano nel tuo editor di testo predefinito (impostato da $EDITOR). In alternativa, usa /plan open per aprire direttamente il file del piano attivo.

La Plan Mode si ripaga da sola in questo passaggio. Puoi annotare i passaggi con note inline, eliminare i passaggi su cui non sei d’accordo, riordinare le operazioni e salvare. Tornando al terminale, Claude recepisce ogni modifica.

Per il piano della blog API, le annotazioni potrebbero essere:

## Step 3: Extract auth module
Move JWT validation and password hashing to auth/
> NOTE: extract auth middleware BEFORE splitting routes,
> otherwise the route files will import from utils.py
> and we'll have to update imports twice
 
## Step 5: Database layer
Create a repository pattern for database operations
> NOTE: keep the SQLAlchemy session factory in a shared
> db.py, don't put it in models.py

Per piani complessi, un solo giro con Ctrl+G potrebbe non bastare. Annota, torna, dì a Claude “affronta tutte le annotazioni nel piano, non implementare ancora”, rivedi la versione aggiornata e usa di nuovo Ctrl+G. Ogni giro di annotazioni rimuove ambiguità che altrimenti si trasformerebbero in decisioni di implementazione errate.

Una volta che il contratto ti convince, Claude offre alcune opzioni: 

1. Lavorare sul piano e cancellare il contesto (utile quando la sessione è stantia), 
2. Lavorare senza cancellare (per mantenere la cronologia della conversazione), oppure 
3. Continuare a discutere del piano. 

Scegli in base a quanto contesto hai accumulato. Se sei immerso in una sessione lunga, cancellare dà a Claude una finestra pulita per eseguire.

Fase 3: Esegui il piano approvato

Scegli un’opzione di lavoro e Claude inizia a implementare passo dopo passo. Procede attraverso ogni step e si ferma quando serve un intervento manuale (come un’autenticazione interattiva nel terminale) o quando il piano è completato.

Tieni d’occhio le deviazioni. Il piano diceva di estrarre prima l’auth in un proprio modulo, ma Claude potrebbe iniziare a spostare route e logica di auth contemporaneamente perché vede una scorciatoia. È così che ci si ritrova con una codebase mezza migrata, dove alcune importazioni puntano alla vecchia posizione e altre a quella nuova. 

Altri segnali di deriva: 

• Modificare un file non menzionato nello step corrente
• Prendere di nascosto una decisione architetturale che il piano lasciava aperta
• Combinare due step che il piano teneva separati

Quando capita, fai Shift+Tab per tornare in Plan Mode. Claude legge lo stato attuale dei file, produce un piano rivisto per i passaggi rimanenti e tu lo rivedi prima di continuare. Non è una misura d’emergenza. La maggior parte dei refactor multi-file passa attraverso 2-3 revisioni di piano prima di concludersi.

Per refactor che non stanno in una sola sessione, suddividi il lavoro in piani sequenziali invece che in uno grande. Completa l’estrazione dell’auth con un suo piano, poi avvia una nuova sessione e un piano per la suddivisione delle route. 

Usa /rename per etichettare ogni sessione (ad es., "blog-api-auth-extraction") così da riprendere da dove avevi lasciato con /resume. Piani più piccoli mantengono focalizzata la finestra di contesto e ti danno un punto di controllo naturale tra le fasi.

Strategie pratiche per la Plan Mode di Claude Code

Ora che abbiamo visto l’intero processo una volta, vediamo alcune best practice per assicurarti di sfruttare al massimo la Plan Mode.

Quando usare la Plan Mode (e quando saltarla)

Non tutti i task richiedono un piano. Correzioni su una singola riga, refusi e aggiornamenti isolati di funzioni sono più rapidi senza l’overhead della pianificazione. Lo stesso vale per modifiche meccaniche, come rinominare una variabile in un file.

Una buona regola: se la modifica tocca tre o più file, o non riesci a descrivere il cambiamento completo in una sola frase, pianifica prima. Tre file è circa la soglia in cui gli errori composti iniziano a mordere, perché ogni file aggiunge il suo set di decisioni che Claude deve azzeccare.

Task che traggono sempre beneficio dalla Plan Mode:

• Refactor che spostano codice tra file o rinominano interfacce condivise
• Nuove feature che toccano moduli esistenti
• Aggiornamenti di dipendenze con breaking change nelle API
• Qualsiasi task in cui non sei sicuro di come la codebase gestisca un caso specifico
• Sessioni di brainstorming in cui vuoi iterare su un approccio con Claude senza alcun rischio di modifiche premature

Riconoscere i piani deboli prima che costino caro

Un piano che sembra strutturato non è sempre un buon piano. Con le versioni attuali di Claude Code, riferimenti a file allucinati e vaghi step “aggiorna se necessario” sono rari. Il problema più probabile è un piano che mette tutti i passaggi di implementazione all’inizio e aggiunge “scrivi i test” alla fine.

Piani strutturati così danno risultati peggiori del previsto. Senza test durante l’implementazione, Claude non ha modo di verificare il proprio lavoro a metà sessione. Per il refactoring della blog API, un piano che dice “Step 1-6: estrai tutti i moduli, Step 7: scrivi i test” significa sei passaggi di codice senza loop di feedback. 

Un piano più solido usa il TDD e interseca test e implementazione: scrivi i test per auth/ prima di estrarre le funzioni di auth, conferma che passino, poi scrivi i test per posts/ prima di estrarre le route. Ogni test superato dà a Claude un segnale chiaro che il refactoring è sulla buona strada. 

Aggiungere le convenzioni TDD al CLAUDE.md del progetto fa includere a Claude i passaggi di test per default. I Claude Code Hooks possono automatizzare questo tipo di enforcement eseguendo script di validazione che verificano la qualità del piano prima di approvare l’esecuzione.

Scalare grandi refactor con Agent Teams

I piani che toccano sette o più file iniziano a perdere qualità perché la finestra di contesto si riempie durante l’esecuzione. Il refactoring della blog API raggiunge questa soglia se conti route, modelli, servizi, config, test e una nuova struttura di directory.

Agent Teams è una funzionalità sperimentale che distribuisce questo tipo di lavoro tra più istanze di Claude Code. Una sessione funge da team lead mentre i compagni hanno ciascuno una propria finestra di contesto indipendente. 

Per la blog API, potresti suddividere in tre compagni: uno per l’estrazione delle route, uno per il layer database e modelli, e uno responsabile della copertura dei test. Il lead assegna i task, i compagni li prendono in carico e li completano, e i task bloccati (come “aggiorna le importazioni” che dipende da “estrai i moduli”) si sbloccano automaticamente quando le dipendenze finiscono. 

La stessa suddivisione funziona tra repository: se la tua API dipende da una libreria condivisa, un compagno può refactorizzare la libreria mentre un altro aggiorna il modo in cui l’API la consuma.

La configurazione migliore per la Plan Mode è richiedere l’approvazione del piano per i compagni. Dì al lead: “Avvia tre compagni per il refactoring della blog API. Richiedi l’approvazione del piano prima che facciano qualsiasi modifica.” 

1. Ogni compagno pianifica in modalità sola lettura
2. Il lead rivede e approva o respinge con feedback
3. Solo i piani approvati vengono eseguiti

Puoi guidare il giudizio del lead fornendo criteri: “approva solo piani che includono copertura di test” o “respingi piani che modificano direttamente lo schema del database”. Attiva Agent Teams aggiungendo "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" al blocco env del tuo settings.json.

Per una parallelizzazione più semplice senza il flag sperimentale, i worktree di git ti permettono di eseguire sessioni di Plan Mode separate su branch diversi, ognuna con il proprio piano indipendente.

Se una sessione di lunga durata subisce compattazione del contesto, fai in modo che i compagni riaprano e rileggano esplicitamente i propri file di piano per evitare derive.

Il tutorial sui plugin di Claude Code copre ulteriori pattern per gestire lavori in più fasi.

Conclusione

Il valore della Plan Mode si riduce a una cosa: rivedere prima di eseguire. Ogni giro di annotazioni che aggiungi, ogni domanda che Claude pone invece di indovinare, rimuove una decisione che altrimenti sarebbe andata storta. 

Inizia con la tua prossima modifica su più file, forza Claude a pianificare per primo ed edita quel piano con Ctrl+G prima di concedere l’accesso in scrittura. Per la configurazione di CLAUDE.md, la gestione del contesto e i guardrail basati su hook, il tutorial sulle best practice riprende da dove questo si ferma. 

Per una visione più ampia del coding assistito dall’AI, ti consiglio di dare un’occhiata al nostro skill track AI for Software Engineering, che ti insegna i concetti fondamentali e ti dà esperienza pratica con strumenti simili come GitHub Copilot, Windsurf o Replit.