Guidare bene gli agenti di coding IA: come dirigere Claude Code da regista

La maggior parte delle persone usa gli agenti di coding IA come una slot machine: si butta dentro una richiesta, si tira la leva e si spera per il meglio. Per una bozza rapida può bastare. Per tutto ciò che deve funzionare in modo affidabile è una ricetta per la frustrazione. Il cambiamento decisivo: passare da utente a regista – cioè dirigere l’agente invece di guardarlo improvvisare.

Vale per Claude Code, perché al momento è lo strumento più diffuso – ma allo stesso modo per qualsiasi altro strumento di IA. E non vale solo per la programmazione: chi ha capito una volta come si guida bene un agente può usarlo per calcolare offerte, produrre report o automatizzare interi processi aziendali. Non serve un background di software engineering.

Dal „vibe coding“ al lavoro strutturato

L’errore più frequente ha un nome: „vibe coding“. Si formula una richiesta, si lascia partire l’agente e non si controlla quasi il risultato. Mancano proprio i due passaggi che fanno la serietà – la pianificazione all’inizio e la validazione alla fine.

Un’immagine semplice è la costruzione di una casa sull’albero. Prima disegna uno schizzo, valuta quanto legno Le serve e dove, e procura gli attrezzi giusti. Quando la casetta è in piedi non ci mette dentro subito i bambini – prima prova se regge. Lo stesso rigore serve nel lavorare con gli agenti di coding.

Diventa importante perché i modelli tendono all’adulazione. Se chiede „Ti sembra buono?“, arriva volentieri un „Sì“ senza che il piano sia stato davvero esaminato in modo critico. Al contrario, i modelli affermano a volte che qualcosa è finito quando non lo è. Le serve quindi un metodo proprio e indipendente per controllare entrambe le cose. Il procedimento ha quattro passi:

• Pianificare – chiarire con il contesto necessario che cosa va costruito e come si presenta concretamente il successo.
• Costruire – delegare la realizzazione all’agente il più possibile.
• Verificare – avere una via propria e chiara per controllare il risultato.
• Migliorare il sistema – il quarto passo spesso trascurato: ricavare da ogni ciclo un miglioramento duraturo.

Verifica: prova, non affermazione

In sostanza verificare significa: „Dimostrami che è davvero finito.“ Nella programmazione sono i test e il linting – ma il principio si può applicare a quasi tutto. Esempio senza codice: l’agente crea un diagramma e poi lo rende come immagine. Poiché i modelli attuali leggono benissimo le immagini, l’agente può guardare la propria opera, riconoscere le sovrapposizioni e correggerle da solo in più passaggi. Gli errori iniziali non contano; conta solo il risultato finale.

L’effetto è misurabile: senza un meccanismo di controllo il primo risultato si attesta forse su 65–70 punti su 100. Con un controllo integrato sono possibili circa 92 già al primo tentativo. Perfetto lo è raramente subito – e non è nemmeno l’obiettivo. L’obiettivo è dare all’agente un quadro con cui controlli da sé il proprio lavoro. La domanda guida è sempre: come può l’agente verificare il risultato nel modo in cui lo farebbe un utente reale? Una semplice occhiata al codice prodotto non basta mai.

Che cos’è una „harness“?

Una harness è l’involucro attorno al modello di IA – gli strumenti e il contesto a cui il modello accede per sapere su che cosa sta lavorando. Se lo immagini come un modello a strati: al centro sta il modello, il vero „cervello“. Attorno mette uno strumento come Claude Code. E sopra costruisce il Suo strato personale – configurazione, Skills, hooks e collegamenti al CRM o alla gestione dei task. È proprio questo strato più esterno che trasforma uno strumento generico nel Suo sistema.

Pianificazione: il passo sottovalutato

La maggior parte pianifica troppo poco. Con gli agenti di coding passa più tempo a pianificare che a costruire, perché la realizzazione la cede in gran parte – e così il successo dipende direttamente dalla qualità del piano. Si è dimostrato utile un unico documento che descrive l’obiettivo:

• Che cosa costruiamo – e perché?
• Come si presenta concretamente il successo?
• Da che cosa riconosce l’agente che il lavoro è finito e corretto?
• Nei compiti tecnici: quali punti del sistema esistente vanno effettivamente toccati?

Il procedimento tipico: prima raccogliere contesto e documenti rilevanti, poi fare ricerca e da lì sviluppare il piano insieme all’agente. Molto importante: lasci che l’agente faccia molte domande, così non fa innumerevoli supposizioni sul risultato desiderato. Solo dopo che ha chiesto in modo mirato, persona e agente concordano su che cosa va fatto e come va controllato.

Sentirsi sicuri anche senza saper leggere il codice

Come si fa a fidarsi di codice che non si legge? Ci sono due strade. Primo: chieda all’agente di spiegare ciò che ha scritto. All’inizio il codice intimidisce, ma superato il primo scoglio si legge quasi come inglese. Secondo, se non vuole affatto imparare a programmare: la fiducia nasce dalla strategia di validazione. È esattamente qui la differenza rispetto al vibe coding – incastra la realizzazione fra un piano accurato e un controllo altrettanto accurato, nel quale è coinvolto Lei stesso. L’agente ottiene il via libera solo quando è definito chiaramente come dimostra che il lavoro è finito.

Il contesto è scarso: la „dumb zone“

Nel pianificare la cosa più importante è governare il contesto, perché l’attenzione di un modello è una risorsa scarsa. Circola l’idea sbagliata che non conti quanto si carica sull’agente, perché i modelli attuali hanno capacità di contesto enormi. I numeri sono impressionanti – ma ci sono due limiti.

Primo, il contesto si esaurisce più in fretta di quanto si creda: se l’agente legge più Skills o grandi quantità di codice, in un attimo si consumano decine o centinaia di migliaia di token. Secondo, esiste la „dumb zone“. Nella parte iniziale della finestra di contesto il modello appare lucido e al massimo delle sue prestazioni. Quando la conversazione supera una certa soglia, la cosa si ribalta: il modello appare sovraccarico, tralascia elementi e commette errori che con contesto fresco non sarebbero mai successi.

Per questo deve valutare con cura che cosa dare all’agente in anticipo e che cosa può scoprire da sé quando serve. È proprio questo il punto di forza degli Skills: mettono a disposizione procedure e best practice, ma è il modello a decidere quando gli serve quale informazione. Non riversi tutto dentro in una volta. Molto spesso il problema non è il modello, ma il modo in cui viene riempito il contesto. La grande finestra di contesto dà quindi una sicurezza ingannevole – il punto critico sarebbe meglio non raggiungerlo affatto.

Orchestrare più sessioni

Poiché la „dumb zone“ esiste, non può buttare compiti grandi in un’unica sessione. La risposta è un workflow fatto di più sessioni di agenti: un agente pianifica, passa il documento a un secondo per la realizzazione, questo scrive un rapporto di esecuzione e un terzo valida e controlla il lavoro. Impegnativo, ma per software pronto alla produzione o automazioni critiche per il business semplicemente necessario.

L’immagine è quella di una catena di montaggio: ogni agente fa una cosa molto bene e consegna il proprio risultato in modo che il successivo abbia contesto sufficiente per capire che cosa è stato fatto, che cosa manca e qual è il suo compito attuale.

Un esempio dalla quotidianità B2B: la stesura di offerte, per esempio nell’edilizia o nella stampa. Questi calcoli sono laboriosi – stimare l’impegno, definire i materiali, cercare i prezzi, scegliere i fornitori. Qui si costruisce un workflow di agenti specializzati: uno controlla le giacenze di magazzino, uno confronta i prezzi, uno imposta il PDF. Alla fine c’è una validazione – per esempio un calcolo che verifica se il margine desiderato viene raggiunto. Chi guarda seriamente alla propria attività si accorge in fretta che si lascia scomporre in molti piccoli sotto-compiti – ed è proprio questa scomposizione a creare subito una leva enorme.

La sicurezza va nella tecnica, non nel prompt

Una sicurezza particolarmente ingannevole riguarda i permessi. Molti credono che i loro prompt bastino come protezione. Non è così. Se dice a un agente di non cancellare mai un database, può succedere lo stesso. Se gli vieta di cancellare una cartella, può darsi che scriva uno script che fa esattamente questo.

L’unico atteggiamento di fondo sostenibile è quindi: tutto ciò che l’agente può leggere o toccare, prima o poi lo tocca davvero – anche senza che glielo si chieda. I permessi vanno imposti a livello tecnico: con chiavi dallo scope ristretto oppure rendendo certe cose semplicemente irraggiungibili. Un esempio reale mostra l’insidia: un agente ha frainteso una voce della sua lista di compiti – e ha inviato di conseguenza un’e-mail con un codice sconto a tutta la lista di distribuzione, benché non dovesse mai uscire.

Uno strumento collaudato sono gli hooks – piccoli pezzi di codice eseguiti al verificarsi di un determinato evento, per esempio subito prima che l’agente usi uno strumento. Così può controllare se un comando è delicato e bloccarlo. Gli stessi hooks si possono usare per migliorare il sistema in automatico – per esempio scrivendo alla fine di ogni sessione un riepilogo in un log giornaliero.

Da ogni errore un miglioramento permanente

La cosa forse più importante è l’evoluzione del sistema. Se si presenta un problema, non lo corregga e basta per poi andare avanti – lo usi insieme all’agente come occasione per chiedersi che cosa si può migliorare affinché non si ripeta. Forse ne nasce una nuova regola nella Sua configurazione, un documento di pianificazione in più o uno Skill adattato. Così ogni bug diventa un miglioramento permanente.

Una volta stabilito questo sistema, gli errori quasi li accoglie volentieri. E prima ancora che si verifichino aiuta una domanda semplice che quasi nessuno osa porre: „Che cosa potrebbe andare storto qui?“ Faccia costruire all’agente casi limite mirati e provare a rompere l’applicazione con input problematici. Se qualcosa si rompe, torna nel ciclo di controllo: trovare il problema, correggerlo e – molto importante – testare di nuovo. Può darsi che la correzione non abbia affatto risolto il problema.

L’atteggiamento giusto verso lo strumento

Tratti lo strumento come un mentore – la persona più intelligente del mondo che è al tempo stesso il Suo migliore amico. Non La deride se chiede qualcosa apparentemente stupido. Ma non tutto si presta come domanda: per via dell’adulazione è delicato chiedere a un modello la sua opinione. È invece eccellente per capire come funziona qualcosa, o dove esistono dati empirici – nei casi limite un’automazione con un determinato input funziona, oppure no. Nessuna zona grigia. Chi ha bisogno di una seconda prospettiva mette due modelli l’uno contro l’altro: uno costruisce, un altro fa in una sessione separata l’avvocato del diavolo, invece di lodare acriticamente.

Conclusione: pensi come un product manager

Il consiglio centrale per finire: per quanto tecnicamente preparato Lei sia – si consideri il product manager del Suo agente. Non deve descrivere come qualcosa viene costruito. Ma deve dare forma alla visione: che cosa costruiamo, e perché? Dia allo strumento il perché – incide sul come in modo sorprendentemente forte.

Questo è il nocciolo onesto al di là dell’hype: gli agenti di IA non sono una slot machine né una panacea. Sono uno strumento potente che diventa esattamente buono quanto il quadro che Lei gli dà. Piani buoni, criteri di controllo chiari e la disciplina di imparare da ogni errore – questo La porta più avanti di qualsiasi modello nuovo. Cominci in piccolo: metta per iscritto uno dei Suoi processi, lo scomponga in sotto-compiti e definisca da che cosa riconosce che il risultato è corretto. Il resto lo può delegare.

Fonte: questo articolo si basa sul video How to Build Effective Claude Code Agents in 2026 di Nate Herk | AI Automation. I contenuti sono stati rielaborati in modo autonomo e inquadrati per il pubblico di lingua italiana.