Come usare la modalità piano di Claude Code prima delle modifiche

Chiedi di aggiungere un campo a un form. Claude Code apre tre file, nota che il dato attraversa anche il database e propone una modifica. A quel punto puoi lasciarlo procedere oppure fermarti e chiedere che cosa succederà alla validazione, ai record esistenti e ai test. La seconda scelta richiede qualche minuto in più, ma può evitare di scoprire l'impatto quando il codice è già cambiato.

La modalità piano serve proprio a separare osservazione ed esecuzione. Claude esplora il progetto, raccoglie informazioni e descrive un percorso prima di toccare i file sorgente. Tu puoi controllare se ha capito il problema, quali decisioni sta assumendo e come intende provare il risultato.

Non è un rito da applicare a ogni correzione. È utile quando l'incertezza è più costosa del tempo impiegato a mapparla.

Prima mappa, poi modifica

Una richiesta apparentemente semplice può nascondere tre tipi di incertezza: non sai dove vive davvero il comportamento, non sai quanti componenti dipendono da quel punto oppure non hai ancora scelto tra alternative con conseguenze diverse.

Se parti subito con l'esecuzione, queste domande vengono risolte mentre i file cambiano. Il diff diventa anche il luogo dell'esplorazione. Se parti con un piano, invece, puoi discutere le decisioni prima che si mescolino con l'implementazione.

La differenza non è tra pensare e fare. Claude ragiona in entrambi i casi. La differenza è nel confine autorizzato: durante il piano l'obiettivo è produrre una mappa controllabile, non accumulare modifiche da correggere dopo.

Che cosa blocca la modalità piano

La documentazione sui permission mode descrive la modalità piano come un assetto di sola lettura per l'esplorazione del progetto. Nel normale perimetro, Claude può leggere e cercare, ma non modificare i file sorgente. Al termine puoi rivedere il piano e decidere come continuare.

Questo confine è utile, ma va interpretato correttamente. Non è una sandbox completa e non sostituisce le regole di permesso. Se una cartella, un segreto o un comando deve essere inaccessibile, quel limite va applicato con il controllo tecnico adatto. Il piano disciplina la fase del lavoro, non concede una garanzia universale sull'ambiente.

Quando il piano ripaga il tempo

Usalo quando almeno una di queste condizioni è vera:

• la modifica attraversa più moduli o livelli dell'applicazione;

• il requisito ammette due soluzioni ragionevoli;

• non conosci ancora il punto di ingresso corretto;

• un errore potrebbe alterare dati, permessi o comportamento pubblico;

• il repository contiene convenzioni che devono essere scoperte;

• serve concordare prove e criteri di accettazione prima di scrivere codice.

È particolarmente utile su migrazioni, refactoring, bug senza causa nota e funzioni che toccano interfaccia, server e persistenza. Le best practice di Claude Code raccomandano di pianificare quando la soluzione richiede esplorazione o coinvolge più file.

Il test di ingresso in quattro domande

Prima di attivare la modalità piano, rispondi a quattro domande:

1. So indicare con sicurezza il file o il componente da cambiare?

2. Esiste una sola soluzione plausibile con conseguenze locali?

3. Posso descrivere ora la prova che dimostra il risultato?

4. Un errore è facile da rilevare e da annullare?

Se tutte le risposte sono sì, puoi probabilmente chiedere direttamente una modifica circoscritta. Se una risposta è no, il piano ha un compito preciso. Non deve produrre una relazione generica: deve chiudere quella lacuna.

Per esempio, se non conosci il punto di ingresso, chiedi di tracciare il flusso dalla UI alla persistenza. Se non sai quale prova serve, chiedi di trovare i test esistenti e indicare quale comportamento non coprono.

Fai osservare lo stato prima della soluzione

Un piano affidabile parte dall'evidenza del repository. Chiedi a Claude di identificare:

• i file che definiscono il comportamento attuale;

• i chiamanti e i consumatori coinvolti;

• i test esistenti;

• le convenzioni dichiarate nel progetto;

• eventuali modifiche locali già presenti;

• i punti che restano incerti.

Una richiesta utile può essere: «Esplora il flusso di salvataggio del profilo. Non modificare file. Riporta percorso dei dati, validazioni, test esistenti e due rischi da risolvere prima dell'implementazione».

Qui l'output non è ancora una soluzione. È la fotografia da cui la soluzione deve discendere. Se Claude propone subito nuovi componenti senza mostrare dove vive il comportamento corrente, chiedi di tornare all'evidenza.

Gli otto campi del piano

Un piano pronto per l'approvazione dovrebbe contenere otto campi:

1. Obiettivo osservabile: che cosa sarà diverso per l'utente o per il sistema.

2. Stato attuale: dove e come viene prodotto oggi il comportamento.

3. File coinvolti: percorsi precisi, con il ruolo di ciascun file.

4. Decisioni: scelte che cambiano contratto, struttura o comportamento.

5. Passaggi: ordine minimo delle modifiche.

6. Rischi e limiti: dati, compatibilità, concorrenza, sicurezza o casi non coperti.

7. Prove: test, comandi e controlli manuali pertinenti.

8. Fuori perimetro: ciò che non verrà cambiato.

Se manca lo stato attuale, il piano può essere una soluzione immaginata. Se mancano i fuori perimetro, l'approvazione non ha un confine. Se manca la prova, hai approvato attività, non un risultato.

Collega file, decisioni e prove

Un elenco di file non basta. Per ogni modifica importante crea una catena leggibile:

Questa mappa rende visibili i buchi. Un file senza decisione potrebbe essere rumore. Una decisione senza prova è un'assunzione non verificata. Una prova senza collegamento al cambiamento rischia di essere solo un comando eseguito perché esiste.

Puoi applicare lo stesso principio con la checklist di verifica degli output AI: ogni affermazione di completamento deve avere un riscontro pertinente.

Chiedi alternative vere

«Proponi tre alternative» produce spesso tre varianti della stessa idea. Chiedi invece opzioni che spostino davvero una decisione: intervento locale o componente condiviso, migrazione immediata o compatibilità temporanea, calcolo al volo o persistenza.

Per ogni alternativa chiedi:

• quale problema risolve meglio;

• quale complessità aggiunge;

• che cosa rende più difficile cambiare in futuro;

• quali prove richiede;

• perché una delle opzioni viene raccomandata.

Non serve moltiplicare le possibilità quando il repository indica già una convenzione. In quel caso il piano deve mostrare la convenzione trovata e spiegare perché viene seguita.

Approva il confine, non la prosa

Un piano può sembrare convincente e restare ambiguo sul perimetro. Prima di approvarlo, verifica quattro elementi concreti: risultato, file o aree coinvolte, decisioni irreversibili e prove finali.

Puoi rispondere con un'approvazione condizionata: «Procedi con i passaggi 1-4. Non cambiare lo schema. Mantieni compatibilità con i record esistenti. Esegui il test del contratto e mostrami il diff finale».

Questa frase non corregge lo stile del piano. Definisce il contratto dell'esecuzione. Se un punto importante resta aperto, risolvilo prima di passare alla modifica.

Dall'approvazione all'esecuzione

Quando continui, conserva il piano come riferimento ma lascia che l'evidenza lo corregga. Durante l'implementazione Claude può trovare una dipendenza non visibile in lettura iniziale. La risposta corretta non è seguire ciecamente l'elenco: è fermarsi, spiegare il nuovo fatto e aggiornare il confine se cambia una decisione approvata.

Chiedi aggiornamenti basati su risultati: passaggio completato, prova eseguita, deviazione necessaria. Non servono resoconti continui di ogni file aperto. Serve sapere quando il lavoro incontra una condizione che rende vecchio il piano.

Verifica il delta finale

Il piano descrive l'intenzione; il diff mostra ciò che è successo. Alla fine confrontali.

Controlla:

• quali file sono cambiati rispetto a quelli previsti;

• se ogni decisione approvata è visibile nel risultato;

• se sono comparsi cambiamenti collaterali;

• se le prove previste sono state davvero eseguite;

• se resta un limite da dichiarare.

La guida al controllo delle modifiche nei workflow AI approfondisce questo passaggio: una consegna verificabile separa il piano, il delta reale e l'esito delle prove.

Quando saltare il piano

Non usare la modalità piano per dare solennità a un compito già chiaro. Correggere un refuso in un file noto, aggiornare una stringa concordata o aggiungere un test a un caso già isolato può partire con un incarico diretto, un perimetro stretto e una prova esplicita.

Puoi anche chiedere una breve ispezione senza formalizzare otto campi. Il criterio è proporzionare la preparazione al rischio e all'incertezza. Un piano utile riduce domande costose. Un piano superfluo ripete ciò che hai già deciso.

Porta un cambiamento reale in modalità piano

Scegli una modifica che hai rimandato perché attraversa più file. Fai prima osservare lo stato, poi chiedi gli otto campi e approva soltanto un confine che sai verificare. Alla fine confronta piano e diff.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi applicare questo metodo ai tuoi flussi, con richieste, permessi e prove calibrati sul lavoro reale. Il valore non sta nell'avere un documento in più. Sta nel rendere visibile una decisione prima che diventi una modifica.