Assistenti di codice: come inquadrare bene un compito

Uno sviluppatore freelance chiede al suo assistente di codice: «Aggiungi un export CSV delle fatture». Venti minuti dopo, lo strumento ha toccato undici file, aggiunto una libreria, riformattato due moduli che non c'entravano niente e scritto un export che dimentica le note di credito. Niente si è rotto in modo visibile, eppure bisogna rileggere tutto.

Gli assistenti di codice attuali non si limitano più a completare una riga. Leggono il progetto, modificano più file, lanciano comandi e test. Più lo strumento agisce da solo, più la tua richiesta deve somigliare a un brief dato a un fornitore che non rivedrai fino alla consegna.

Cosa contiene il brief di un compito

Nella maggior parte dei casi bastano cinque elementi.

1. L'obiettivo, espresso in termini di risultato: cosa potranno fare l'utente o il sistema dopo.
2. Il perimetro: i file o le cartelle interessati, e ciò che non va toccato.
3. I vincoli: tecnologie imposte, convenzioni, dipendenze vietate.
4. Il criterio di riuscita: come capirai che è finito, preferibilmente un comando o un test.
5. Il modo di lavorare: proporre un piano prima di modificare, oppure procedere per piccoli passi.

Ecco il brief dello sviluppatore, riscritto per bene:

Obiettivo: aggiungere un export CSV delle fatture di un mese dato, accessibile dalla pagina Fatturazione.

Perimetro: puoi modificare il modulo fatturazione/ e la pagina Fatturazione. Non toccare gli altri moduli né la configurazione del progetto.

Vincoli: nessuna nuova dipendenza, usiamo il modulo CSV della libreria standard. Stesso stile degli export esistenti (vedi export_clienti).

Regole di business: l'export contiene le fatture e le note di credito del mese. Le note di credito sono in negativo. Gli importi sono in centesimi nel database e in euro con due decimali nel file.

Criterio di riuscita: i test esistenti passano, e aggiungi un test che verifichi un mese contenente una fattura e una nota di credito.

Prima di modificare qualunque cosa, descrivimi il tuo piano in cinque righe al massimo e aspetta il mio via libera.

L'ultima frase è la più redditizia. Un piano sbagliato si corregge in dieci secondi; un codice sbagliato si corregge in dieci minuti.

Cosa lo strumento non può indovinare

Le regole di business non sono scritte da nessuna parte nel codice, o lo sono solo in modo indiretto. Il fatto che le note di credito entrino nell'export, che gli importi siano in centesimi, che la pagina si chiami Fatturazione: l'assistente può ritrovarne una parte leggendo il progetto, ma fai prima a scriverle tu. Meglio dire una cosa ovvia di troppo che ottenere un export sbagliato ma plausibile.

Tutto ciò che ripeti da un compito all'altro (convenzioni, comandi di test, cartelle da evitare) può andare in un file di istruzioni letto automaticamente dallo strumento. Il nome del file e la sua posizione dipendono dall'assistente che usi. L'articolo sulle istruzioni per agenti IA spiega come scriverlo senza farne un romanzo.

Una modifica alla volta

La tentazione, quando lo strumento è veloce, è accumulare le richieste: l'export, poi un filtro, poi un rifacimento della pagina, tutto nella stessa sessione. Ogni aggiunta rende il risultato più difficile da rileggere. Prendi l'abitudine di suddividere, come per una catena di prompt:

• un compito, un obiettivo, un risultato verificabile;
• un salvataggio del tuo lavoro (un commit) prima di ogni compito, per poter tornare indietro;
• una sessione nuova quando l'argomento cambia, perché la conversazione si appesantisce e lo strumento finisce per perdere dettagli dell'inizio.

Se il compito è troppo grosso per un brief di una pagina, chiedi prima una suddivisione:

Voglio migrare l'autenticazione dell'applicazione verso [NUOVO METODO]. Per ora non modificare niente. Scorri il progetto, elenca i file interessati e proponi una suddivisione in passi indipendenti, ciascuno testabile da solo. Per ogni passo, indica il rischio principale.

Scegli poi il passo da lanciare e ne scrivi il brief.

Rileggere il risultato

Il lavoro non finisce quando lo strumento dice «fatto». Quattro controlli, in quest'ordine.

Prima il diff. Guarda l'elenco dei file modificati prima di aprirne uno solo. Se contiene file fuori perimetro, chiedi perché, oppure annulla.

Poi i test, lanciati da te se possibile. Un assistente può affermare che i test passano senza averli eseguiti correttamente, o modificare un test per farlo passare. Verifica che i test esistenti non siano stati cambiati senza motivo.

I casi limite. Riprendi le regole di business del tuo brief e provale a mano: il mese senza fatture, la nota di credito più grande della fattura, il valore a zero.

Le aggiunte discrete. Una nuova dipendenza, un file di configurazione, la cancellazione di un pezzo di codice che riteneva inutile: chiedi allo strumento di elencarli se non l'ha fatto.

Riassumi ciò che hai modificato, file per file, in una riga ciascuno. Indica cosa hai eliminato, aggiunto come dipendenza o cambiato al di fuori del perimetro richiesto. Elenca poi i casi limite che non hai testato.

Questo riassunto non sostituisce la tua rilettura del diff, perché lo strumento può dimenticare di menzionare una modifica. Ti indica semplicemente dove guardare.

Quando non funziona

Se l'assistente gira a vuoto, correggi la causa invece di ripetere la richiesta. Spesso è un contesto mancante o un'istruzione contraddittoria nel brief. Riparti da una sessione nuova con un brief corretto, invece di aggiungere «no, non così» venti volte. Per i compiti di rilettura, di debug o di generazione di test al di fuori di questo schema, l'articolo sui prompt per sviluppatori offre altri modelli, e quello su GitHub Copilot approfondisce il lavoro nell'editor.

E tieni in mano ciò che lo strumento può fare: lanciare comandi, eliminare file, accedere alla rete. Leggi ciò che il tuo assistente ti chiede di autorizzare prima di accettare, ed evita di aprirgli l'accesso a chiavi o a database di produzione per un compito che non ne ha bisogno.

Da fare prima del tuo prossimo compito

Prendi un compito che affiderai all'assistente questa settimana. Scrivi le cinque righe del brief, compreso il comando che proverà che è finito. Se non sai scrivere quel comando, il compito non è ancora abbastanza chiaro, ed è il momento di scoprirlo.