Un buon incarico per un agente IA dice a chi è destinata l'applicazione, quale problema risolve e da quali casi concreti capisci che funziona. Se i tuoi primi tentativi con Claude Code o Codex ti hanno deluso, spesso la causa non sta tanto nello strumento quanto in un incarico che lascia aperti questi tre punti.
L'agente riempie i vuoti con delle supposizioni. Più vuoti ci sono, più supposizioni fa, e più il risultato si allontana da quello che avevi in mente. Questo articolo mostra come costruire un incarico, come scomporlo in passi intermedi e come si presenta il tutto con l'esempio di una lista contatti.
Perché un incarico breve raramente ti dà quello che vuoi
Un tipico primo tentativo suona più o meno così: «Fammi un'app per i miei contatti.» L'agente consegna qualcosa. Forse una lista con nomi e numeri di telefono, forse un modulo con venti campi, forse una pagina di login che non hai mai chiesto. Dal punto di vista tecnico non è sbagliato. Semplicemente non si adatta al tuo lavoro.
Il problema: tu sai chi userà l'app, quanti contatti ci sono e che cosa deve succedere dopo un colloquio. L'agente no. Tira a indovinare. E siccome prima non hai stabilito come misurare il successo, ti resta solo una sensazione: qualcosa non va. Poi arriva il tentativo successivo, di nuovo vago, di nuovo a tentoni.
Un incarico con destinatari chiari, un problema chiaro e casi verificabili spezza questo circolo. Puoi confrontare ogni risultato con i tuoi casi e dire esattamente che cosa manca.
Le tre componenti di un buon incarico
Destinatari: per chi è l'app?
Descrivi la persona che lavora con l'app e la sua situazione. «Per una piccola azienda» è un inizio. Meglio: «Per una persona addetta alla vendita in una piccola azienda, che gestisce potenziali clienti raccolti a fiere e tramite richieste e che il lunedì vuole sapere chi deve richiamare.» Da questa frase l'agente può dedurre che l'uso deve essere semplice, che le date contano e che nessuno ha bisogno di un'interfaccia di amministrazione per cento utenti.
Problema: che cosa deve migliorare?
Indica il problema, non la soluzione. «Voglio una tabella con dei filtri» descrive una soluzione. «I follow-up vengono dimenticati perché sono sparsi tra appunti ed e-mail» descrive il problema. Se l'agente conosce il problema, può prendere decisioni sensate che non hai previsto esplicitamente. E più tardi puoi verificare se la soluzione affronta davvero il problema.
Casi di accettazione: da cosa capisci che funziona?
I casi di accettazione sono situazioni brevi e concrete con un risultato atteso. Una forma collaudata è: situazione di partenza, azione, risultato atteso. Per esempio: «C'è un contatto con data di follow-up ieri. Quando apro la lista, questo contatto è segnato come scaduto.»
Casi del genere hanno due vantaggi. L'agente capisce con più precisione che cosa intendi. E tu hai una lista di controllo da ripercorrere dopo ogni modifica, invece di affidarti a un'impressione. I casi di accettazione si possono poi tradurre in test automatici. A quel punto basta un comando per verificare che tutto sia ancora a posto.
Pensa anche ai casi di errore: che cosa succede se un campo obbligatorio resta vuoto, se un indirizzo e-mail non contiene la @, se la lista è vuota? Proprio questi casi si dimenticano al primo tentativo, ed è proprio lì che nascono gli errori che più tardi ti fanno perdere tempo.
Come scomporre l'incarico in passi intermedi
Anche un buon incarico è troppo grande se descrive l'intera app in una volta. L'agente produce allora molto codice in un colpo solo e, se qualcosa non va, non sai dove cercare. Conviene suddividere il lavoro in piccoli passi, ognuno verificabile da solo.
Ecco come procedere:
- Scrivi l'obiettivo dell'intera app in due o tre frasi: destinatari e problema.
- Raccogli tutto quello che l'app deve saper fare in una lista libera.
- Ordina i punti in modo che ognuno si basi sul precedente. Prima visualizzare, poi salvare, poi modificare, poi collegare.
- Formula per ogni passo da due a quattro casi di accettazione, di cui almeno un caso di errore.
- Dai all'agente un solo passo alla volta e verifica i casi prima di andare avanti.
- Annota che cosa ha contribuito l'agente e che cosa hai modificato tu.
L'ultimo punto sembra secondario. Ti aiuta però a spiegare più tardi come è nata la tua app e ad attribuire più in fretta gli errori.
Un buon passo è abbastanza piccolo da permetterti di verificare il risultato in pochi minuti. Se per verificare un passo ti serve mezz'ora, era troppo grande.
Esempio: un incarico per una lista contatti
Ecco come potrebbe presentarsi un incarico per la prima fase di un'app per contatti e follow-up:
Destinatari: una persona addetta alla vendita in una piccola azienda.
Gestisce potenziali clienti e vuole vedere chi deve contattare per primo.
Problema: i follow-up vengono dimenticati perché contatti e passi
successivi sono annotati in posti diversi.
Questo passo: una lista contatti e una vista di dettaglio con dati di esempio.
Ancora nessun salvataggio, nessuna modifica, nessun login.
Casi di accettazione:
1. Ci sono cinque contatti di esempio. Quando apro l'app,
li vedo tutti e cinque con nome, azienda e stato.
2. Quando clicco su un contatto, si apre la vista di dettaglio
con tutti i dati e la prossima data di follow-up.
3. Quando nella vista di dettaglio clicco su «Indietro», vedo
di nuovo la lista.
4. Non ci sono contatti. Quando apro l'app, vedo l'avviso
«Ancora nessun contatto» invece di una superficie vuota.
Nota che cosa esclude esplicitamente l'incarico. «Ancora nessun salvataggio, nessun login» impedisce all'agente di inserire funzioni che in questo passo non potresti nemmeno verificare.
I passi successivi
Solo quando i quattro casi funzionano arriva l'incarico successivo. L'ordine potrebbe essere questo:
- Salvare i contatti e verificare gli inserimenti: un nuovo contatto senza nome viene rifiutato, con un messaggio comprensibile.
- Cambio di stato: un contatto passa da «nuovo» a «contattato» e la lista mostra subito il nuovo stato.
- Filtri: se filtro per «scaduto», vedo solo i contatti con una data di follow-up nel passato.
- Interfaccia: se il servizio non risponde o segnala un errore, l'app mostra un avviso invece di bloccarsi.
Ognuno di questi passi riceve di nuovo i propri casi di accettazione. Così l'app cresce a piccoli pezzi, sotto controllo.
Da cosa capisci che il tuo incarico non basta ancora
Prima di inviarlo, passa in rassegna queste domande:
- C'è scritto chi usa l'app e in quale situazione?
- È descritto il problema e non soltanto una funzione desiderata?
- Ci sono almeno due casi di accettazione concreti con un risultato atteso?
- C'è almeno un caso di errore, per esempio un inserimento vuoto o una lista vuota?
- C'è scritto che cosa non va costruito in questo passo?
- Riesci a verificare il risultato in pochi minuti?
Se una risposta è no, completa l'incarico prima di inviarlo. Ti costa qualche minuto e ti risparmia diversi giri di correzioni.
E se il risultato continua a non andare: confrontalo con i tuoi casi di accettazione. Di' all'agente esattamente quale caso non è soddisfatto e che cosa succede invece. «Il caso 3 non funziona: dopo il clic su Indietro la vista di dettaglio resta aperta» è un riscontro con cui l'agente può lavorare. «Non funziona» non lo è.
Come il corso Vibe Coding Foundation allena questo metodo
Nel corso Vibe Coding Foundation costruisci proprio questa app per contatti e follow-up, passo dopo passo, con Claude Code o Codex. La formulazione dell'incarico è una missione a sé: nella Mission 1 descrivi per chi è pensata l'app e che cosa deve saper fare. Il tempo previsto è di due ore. Scomporre un compito di lavoro in passi verificabili e descriverli come casi di accettazione è una delle quattro competenze che il programma attesta.
Su questa base si costruiscono le missioni successive: la lista contatti con vista di dettaglio, la verifica degli inserimenti con cambi di stato e filtri, un'interfaccia simulata con risposte vuote, errori e tempi di attesa. Ogni missione ha un obiettivo, criteri sotto forma di test e suggerimenti in tre livelli, nel caso ti blocchi. Sul tuo computer un comando verifica i criteri, così vedi subito se il tuo incarico ha portato al risultato voluto. In parallelo tieni un protocollo IA, in cui annoti che cosa ha contribuito l'IA e che cosa hai modificato tu.
Tutte le missioni con i loro obiettivi si trovano nella panoramica del corso (in tedesco). Se vuoi vedere come si comincia, la Mission 0 per configurare gli strumenti è liberamente consultabile. Come si svolge il corso nel suo insieme lo spiega la sezione Svolgimento della pagina iniziale. Alla fine c'è un esame scritto sul progetto. Come viene valutato lo mostra la rubrica d'esame.