Pensare in modalità agentica
Prima dei comandi viene il metodo. In questo modulo impari a guidare un agente come un collaboratore operativo: gli dai un risultato osservabile, gli permetti solo le azioni necessarie e controlli le evidenze prima di accettare il lavoro.
Cosa affronti, passo dopo passo
Da risposta a ciclo di lavoro
Nel Modulo 0 hai visto chi propone e chi agisce. Ora facciamo un passo in più: che cosa succede quando il primo tentativo non funziona? Non si riparte alla cieca. Si usa ciò che è appena accaduto per scegliere il passo successivo.
Un chatbot produce soprattutto una risposta. Un agente di coding può invece leggere file, formulare un piano, applicare modifiche ed eseguire controlli. La differenza importante non è quanto testo genera, ma il ciclo osservabile che percorre.
Il ciclo utile è: osserva lo stato reale, pianifica una modifica limitata, agisce, verifica il risultato e riferisce prove e limiti. Se manca l’osservazione iniziale, l’agente indovina. Se manca la verifica finale, una risposta convincente può nascondere un errore.
- Osserva file, vincoli e sintomo reale.
- Pianifica la modifica più piccola che può risolvere il problema.
- Agisci entro i file e i permessi autorizzati.
- Verifica con test, output o confronto riproducibile.
- Riferisci cosa è cambiato e cosa resta incerto.
Importi un file con tre titoli e una riga vuota. Task Notes crea quattro attività, di cui una senza titolo.
- Osserva: riproduci con lo stesso file e individua il parser, cioè la parte del programma che legge ogni riga e la trasforma in un’attività.
- Pianifica: proponi di ignorare soltanto le righe che, tolti gli spazi, risultano vuote; non cambiare il formato salvato.
- Agisci e verifica: aggiungi prima un test con la riga vuota, applica la patch minima e riesegui i test di importazione.
- Riferisci: mostra il diff, l’esito prima e dopo e specifica che non sono stati controllati formati di importazione diversi da quello testato.
Risultato: Il bug non è soltanto «risolto»: è riproducibile, collegato a una causa, protetto da un test e accompagnato da un limite dichiarato.
L’incarico operativo
Un incarico operativo non è un prompt lungo: è un accordo che permette a te e all’agente di riconoscere lo stesso risultato. Le informazioni utili sono quelle che, se mancassero, potrebbero cambiare la soluzione.
Una richiesta efficace contiene quattro elementi: il risultato desiderato, il contesto necessario, i confini dell’azione e la prova di completamento. Non serve scrivere un romanzo; serve eliminare le ambiguità che cambierebbero la soluzione.
Con Task Notes, «sistema l’importazione» è troppo aperto. «Le righe vuote non devono creare attività; modifica solo il parser, conserva il formato dei dati ed esegui i test di importazione» stabilisce invece un contratto controllabile.
Task Notes importa date nel formato `AAAA-MM-GG`, ma un valore come `2026-19-40` genera un errore poco comprensibile.
- Definisci il risultato: la riga non valida viene rifiutata e il messaggio indica numero di riga e formato atteso.
- Fornisci il contesto: il parser è in `importer.py` e i record validi già salvati non devono cambiare formato.
- Stabilisci il confine: modifica parser e test di importazione, senza migrare il database né riscrivere l’interfaccia.
- Definisci la prova: aggiungi un caso non valido e uno valido; mostra che il primo produce il messaggio atteso e il secondo continua a essere importato.
Risultato: L’agente può scegliere la tecnica di validazione, ma non può dichiarare successo senza proteggere sia il nuovo comportamento sia quello esistente.
Autonomia proporzionata al rischio
Prima di concedere autonomia, fatti tre domande molto concrete: se va male, chi viene coinvolto? Posso annullarlo? L’azione esce dal mio computer? Le risposte ti dicono dove l’agente può procedere e dove, invece, serve un tuo sì esplicito.
Leggere una cartella locale e pubblicare un’app non hanno lo stesso impatto. L’autonomia va concessa in base a reversibilità, portata e destinazione dell’azione. Una modifica locale sotto Git è più facile da controllare di un invio a clienti o di una cancellazione remota.
Il principio del minimo privilegio riduce il raggio dell’errore: accesso in sola lettura durante l’analisi, scrittura soltanto nei file concordati e approvazione umana prima di azioni esterne o irreversibili.
Vuoi verificare il nuovo template su tre indirizzi di test. Il servizio collegato contiene anche la lista reale dei clienti.
- L’agente legge il template locale e genera un’anteprima con dati fittizi, senza accedere alla lista clienti.
- Autorizzi un invio soltanto all’ambiente di prova e a tre indirizzi esplicitamente elencati.
- Controlli oggetto, link e resa dell’email ricevuta; l’agente registra gli esiti senza ampliare i destinatari.
- L’invio alla lista reale resta bloccato dietro un nuovo checkpoint umano, con riepilogo di numero destinatari e contenuto finale.
Risultato: L’agente può completare preparazione e test in autonomia, mentre la conseguenza esterna più ampia rimane sotto controllo esplicito.
Le evidenze battono la sicurezza del tono
La frase «fatto» è un riassunto, non una prova. Per accettare un lavoro devi collegare ogni promessa a un’evidenza che osservi proprio quel comportamento, altrimenti stai misurando una cosa e concludendo su un’altra.
Un agente può dire «fatto» anche quando ha soltanto modificato il codice. La conclusione è affidabile solo se è accompagnata da una prova adeguata: un test che prima falliva e ora passa, un diff limitato, un output riproducibile o un controllo visivo pertinente.
Il controllo deve corrispondere alla promessa. Un controllo di sintassi non dimostra che l’app funzioni nel browser; un test del parser non dimostra che i dati siano mostrati correttamente. Chiedi sempre quale evidenza sostiene quale conclusione.
L’agente cambia il testo di un pulsante e riferisce che la build — il controllo che verifica se il progetto si compila — è riuscita. Nel browser, però, un pannello invisibile copre ancora il pulsante.
- Il diff prova che l’etichetta è stata modificata nel componente corretto e che non sono stati toccati altri file.
- Il build verde prova che il progetto si compila, ma non simula il clic né osserva gli elementi sovrapposti.
- Un test del browser apre la pagina, individua il pulsante e prova a cliccarlo; il test fallisce perché un altro elemento intercetta l’azione.
- Dopo una patch separata, lo stesso test passa e un controllo visivo conferma testo, posizione e interazione sullo schermo previsto.
Risultato: Ogni evidenza sostiene una conclusione precisa: portata del diff, compilazione, interazione e resa visiva non vengono più mescolate.
Da richiesta vaga a missione verificabile
Task Notes genera un’attività vuota quando il file contiene una riga bianca.
Obiettivo: ignora le righe vuote durante l’importazione.
Ambito: modifica solo parser.py e i relativi test.
Vincoli: non cambiare il formato JSON salvato.
Verifica: riproduci il bug, aggiungi un test e mostra il diff finale.