Come tenere in carreggiata il tuo agente di coding IA: esplora, pianifica, poi costruisci

Quando le persone usano per la prima volta uno strumento di coding agentico come Claude Code o Cursor, tendono a digitare una richiesta di una riga e a sperare. A volte funziona. Spesso l'agente costruisce con sicurezza la cosa sbagliata — risolvendo un problema che non avevi posto, toccando file che non ti aspettavi, o saltando il caso limite che contava davvero.

La soluzione non è un modello più intelligente. È un workflow: prima esplora, poi pianifica, poi costruisci. È il pattern che Anthropic raccomanda nella sua guida ufficiale alle best practice di Claude Code, e la stessa idea vale per qualsiasi agente in grado di leggere il tuo repository prima di modificarlo.

Perché passare direttamente al codice fallisce

Un agente IA lavora dentro una finestra di contesto limitata — il registro corrente della tua conversazione più ogni file che legge e ogni comando che esegue. Due cose vanno storte quando salti la pianificazione:

1. L'agente indovina l'intento. Non può leggerti nel pensiero, quindi un prompt vago ottiene un'implementazione plausibile ma sbagliata.
2. Gli errori si accumulano silenziosamente. Una volta che l'agente inizia a modificare, un'ipotesi sbagliata al primo passo viene sepolta sotto altre dieci modifiche prima che tu te ne accorga.

Separare il pensare dal fare intercetta l'ipotesi sbagliata mentre è ancora economico correggerla — una frase di correzione invece di un ripristino di 12 file.

Passo 1: esplora in una modalità di sola lettura

La maggior parte degli agenti seri ha ora una modalità in cui possono leggere e analizzare ma non possono cambiare nulla. In Claude Code si chiama plan mode: uno stato di sola lettura in cui l'agente legge i file e risponde alle domande senza modificare, eseguire comandi che cambiano lo stato o committare.

Inizia chiedendo all'agente di comprendere il codice, non di cambiarlo:

Read /src/auth and explain how we handle sessions and login.
Also look at how we manage environment variables for secrets.

Stai costruendo contesto condiviso e verificando che l'agente capisca davvero il tuo codebase prima di fidarti a fargli apportare modifiche.

Passo 2: chiedi un piano, poi mettilo alla prova

Una volta che l'agente ha esplorato, chiedi un piano concreto prima di qualsiasi codice:

I want to add Google OAuth login. What files need to change?
What's the session flow? Write a step-by-step plan — don't write code yet.

L'agente restituisce un piano numerato: quali file toccherà, il nuovo flusso di sessione, dove memorizzerà i token. Ora non accettare la prima bozza. Questo è il momento più economico per correggere la rotta. Insisti sulle lacune:

• "Cosa succede se la callback OAuth fallisce a metà?"
• "Abbiamo già un helper refreshToken in src/auth/tokens.ts — riusalo invece di scriverne uno nuovo."
• "Mantieni tutto al solo flusso di login. Non toccare il codice esistente di reset della password."

Pochi minuti a raffinare il piano qui ti risparmiano un'ora a districare un'implementazione sbagliata dopo.

Passo 3: costruisci con un modo per verificare

Solo adesso lasci che l'agente scriva codice — e gli dai un modo per controllare il proprio lavoro. L'aggiunta singola più potente a qualsiasi prompt è un passo di verifica che l'agente può eseguire da solo:

Implement the OAuth flow from your plan. Write a test for the callback
handler covering the failure case, run the test suite, and fix any failures.

Senza un controllo che può eseguire — test, una build, uno screenshot da confrontare — "sembra fatto" è l'unico segnale che l'agente ha, e tu diventi il rilevatore di errori per ogni sbaglio. Con un controllo, il ciclo si chiude da solo: l'agente scrive, esegue il test, legge il risultato e itera finché non passa. Chiedigli di mostrare l'output reale del test invece di limitarsi a dichiarare il successo.

Passo 4: sapere quando saltare il piano

La pianificazione ha un costo, e non sempre ne vale la pena. Se la modifica è piccola e l'ambito è ovvio — correggere un refuso, aggiungere una riga di log, rinominare una variabile — chiedi semplicemente all'agente di farlo direttamente. Una buona regola pratica dalla guida di Anthropic: se potresti descrivere il diff in una frase, salta il piano. Riserva il ciclo esplora-pianifica-costruisci al lavoro che si estende su più file, che usa un approccio di cui non sei sicuro, o che tocca codice che non conosci bene.

Una rete di sicurezza: correggi presto la rotta e usa i checkpoint

Anche con un buon piano, gli agenti deviano. Due abitudini ti mantengono il controllo:

• Interrompi nel momento in cui esce di carreggiata. Non aspettare che l'agente finisca un approccio sbagliato. In Claude Code, Esc lo ferma a metà azione con il contesto preservato, così puoi reindirizzarlo.
• Usa i checkpoint per sperimentare liberamente. Claude Code crea uno snapshot dei tuoi file prima di ogni modifica, così puoi dire all'agente di provare qualcosa di rischioso e, se non funziona, riavvolgere (Esc Esc o /rewind) e provare un approccio diverso. (I checkpoint tracciano le modifiche dell'agente stesso, non i processi esterni — sono una comodità, non un sostituto di git.)

E se ti ritrovi a correggere lo stesso errore più di due volte, il contesto è probabilmente inquinato da tentativi falliti. Puliscilo e riparti con un prompt più affilato che incorpori ciò che hai appena imparato — una sessione pulita con un prompt migliore batte quasi sempre una sessione lunga piena di vicoli ciechi.

La conclusione

Esplora, pianifica, costruisci, verifica. Sembra più lento per il primo task e si ripaga già dal secondo. Smetti di ricevere codice sicuro-ma-sbagliato e inizi ad avere un agente che costruisce esattamente ciò che intendevi.