Come dare al tuo agente di coding IA un ciclo di feedback che cattura i propri bug

Quando un agente di coding IA scrive codice che sembra corretto ma rompe silenziosamente qualcosa, di solito il problema non è il modello: è che l'agente non ha mai visto il fallimento. Ha scritto la modifica, ha cantato vittoria ed è andato avanti, perché nulla gli ha detto che la suite di test era ora rossa. La soluzione è chiudere il ciclo: fare in modo che gli strumenti dell'agente gli riferiscano i risultati automaticamente.

Questa guida mostra come costruire quel ciclo di feedback così che il tuo agente catturi i propri errori prima di te.

L'idea di fondo: gli errori dovrebbero rifluire nel contesto

Un flusso di lavoro affidabile per un agente ha quattro tempi — esplorare, pianificare, costruire, verificare. La maggior parte delle persone si ferma a "costruire". Il passo di verifica è ciò che distingue un agente che produce codice funzionante da uno che produce codice solo all'apparenza plausibile.

Verificare significa eseguire controlli reali dopo ogni modifica — il tuo test runner, il linter e il type-checker — e restituirne l'output all'agente. Quando un controllo fallisce, il messaggio di errore finisce nel contesto dell'agente, e il modello lo tratta come qualsiasi altra istruzione: legge il fallimento e lo corregge. Nessun umano nel ciclo per i noiosi andirivieni.

Puoi farlo in due modi: chiederlo nelle istruzioni di progetto, oppure automatizzarlo così che non possa essere saltato.

Opzione 1: chiedilo e basta, nella configurazione di progetto

La versione che richiede meno sforzo è una riga nel tuo CLAUDE.md o AGENTS.md (il file di istruzioni in testo semplice che la maggior parte degli agenti legge all'avvio):

## Verification
After any code change, run `npm run typecheck && npm test`.
If either fails, fix the cause and re-run before reporting done.

Funziona sorprendentemente bene — ma è solo un consiglio. Un agente impegnato può dimenticarsene, oppure decidere che una modifica è "troppo piccola" da verificare. Per qualsiasi cosa a cui tieni, rendi la verifica deterministica.

Opzione 2: automatizzala con un hook

Gli hook di Claude Code ti permettono di eseguire un comando shell in risposta a eventi del ciclo di vita, indipendentemente dal fatto che il modello se ne ricordi. Quello rilevante qui è PostToolUse, che si attiva dopo che l'agente ha modificato un file. Come spiega una guida pratica sugli hook, PostToolUse è pensato per le reazioni — formattazione, logging, esecuzione di test — e il suo output viene iniettato di nuovo nel contesto dell'agente per influenzare il passo successivo.

Ecco un hook minimale che esegue il tuo type-checker dopo qualsiasi modifica a un file e restituisce i fallimenti all'agente. In .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run typecheck"
          }
        ]
      }
    ]
  }
}

Ora il ciclo è automatico: l'agente scrive il codice → l'hook esegue tsc → se c'è un errore di tipo, il messaggio rifluisce come contesto → l'agente lo corregge → l'hook viene eseguito di nuovo. Il riferimento sugli hook documenta come il codice di uscita diverso da zero e l'output vengano resi visibili al modello. Questo ciclo viene eseguito a ogni scrittura, senza alcun sollecito.

Mantieni il ciclo veloce e mirato

Un ciclo di feedback aiuta solo se è rapido. Alcune regole pratiche:

• Esegui i controlli economici a ogni modifica, quelli costosi meno spesso. Un type-check o un linter sul file modificato è veloce. Una suite di integrazione completa non lo è — vincolala a un hook Stop (quando l'agente termina un turno) o a un comando manuale, non a ogni battitura.
• Limitati a ciò che è cambiato. Eseguire l'intera suite di test dopo una modifica CSS di una riga spreca tempo e inonda il contesto. Dove i tuoi strumenti lo consentono, mira ai file interessati.
• Rendi i fallimenti leggibili. L'agente corregge solo ciò che riesce a leggere. Linter e type-checker con messaggi di errore chiari e localizzati (file:line: message) danno al modello esattamente ciò di cui ha bisogno; un generico "build failed" no.

Un prima-e-dopo concreto

Senza un ciclo: chiedi all'agente di rinominare una funzione. Aggiorna tre punti di chiamata, ne manca un quarto in un file che non ha aperto e riferisce di aver finito. Scopri l'import rotto a runtime un'ora dopo.

Con il ciclo: la stessa rinomina attiva typecheck al salvataggio. tsc segnala Cannot find name 'oldFn' nel punto di chiamata mancato. Quell'errore finisce nel contesto, l'agente apre il quarto file, corregge il riferimento e il controllo successivo passa — tutto prima che ti dica di aver finito.

La conclusione

Gli agenti IA sono bravi a produrre codice e poco bravi ad accorgersi quando è sbagliato. Colmi quel divario dando loro lo stesso segnale su cui ti affidi tu: un test rosso, un errore di tipo, una regola di lint fallita — recapitato automaticamente, subito dopo la modifica. Inizia con una riga nelle istruzioni di progetto, poi promuovi il tuo controllo più importante a un hook così che venga eseguito che il modello se ne ricordi o meno. Gli agenti che sembrano "intelligenti" di solito sono semplicemente quelli collegati a un ciclo di feedback ben stretto.