Perché il tuo AI Coding Agent lavora meglio con un brief, non con un semplice prompt

Il problema di "andare a sentimento"

Immagina questa scena: hai un'idea chiara in mente. Apri il tuo assistente AI preferito, scrivi una richiesta veloce, e guardi mentre riscrive mezza codebase con sicurezza. Un'ora dopo, ti ritrovi davanti a una PR che risolve un problema che non volevi risolvere, e rompe cose che non volevi rompere.

Ti suona familiare? Non sei l'unico. Mentre gli agenti AI sono passati da rispondere a domande a modificare codice, molti sviluppatori si stanno accorgendo che quel approccio "casual" che funziona con le chatbot non basta quando ci sono repository condivise in gioco.

La soluzione non sono prompt più dettagliati. È un cambiamento fondamentale nel modo in cui pensiamo ai documenti che inviamo a questi agenti.

Prompts vs. Specifiche: una distinzione importante

Il fatto è questo sui prompt: sono ottimizzati per iniziare. Funzionano bene per spiegazioni rapide, script usa e getta, conversazioni esplorative. Un prompt vive in una chat session, può usare abbreviazioni, e spesso dà per scontato un contesto che solo l'autore conosce.

Questo va bene quando stai solo facendo domande.

Ma quando un agente AI sta per modificare codice condiviso, eseguire comandi terminal, e produrre branch che i colleghi revieweranno? Quel prompt casuale diventa un incarico. E gli incarichi hanno bisogno di più che buone parole — servono il contesto giusto, confini chiari, esempi concreti e criteri di validazione.

È qui che entrano in gioco le specifiche.

Una specifica non è un prompt più carino. È un documento strutturato che cattura quale problema stai risolvendo, quale comportamento deve cambiare, cosa deve rimanere uguale, e come saprai se il lavoro è riuscito. A differenza di un prompt che svanisce quando l'agente inizia a lavorare, una specifica resta visibile per tutto il workflow — guidando l'agente, informando i reviewer, e aiutando i futuri manutentori a capire perché certe decisioni sono state prese.

Cosa contiene una buona specifica per agenti AI

Non ti serve un documento di 20 pagine. Ti servono cinque elementi chiave:

1. Contesto: Perché sta succedendo questo task? Quale problema utente o debito tecnico lo sta guidando? Quali vincoli esistono nella codebase che l'agente dovrebbe conoscere?

2. Comportamento da cambiare: Quale funzionalità specifica deve essere modificata, aggiunta o rimossa? Sii concreto — "gli utenti devono ricevere email di notifica quando succede X" funziona meglio di "migliora il sistema di notifiche."

3. Vincoli da preservare: Cosa non deve assolutamente cambiare? Quale funzionalità esistente, contratti API, o caratteristiche di performance devono restare intatte?

4. Esempi di correttezza: Scenari concreti che dimostrano cosa significa "buono". Il formato Dato/Quando/Allora funziona bene qui, ma anche solo alcuni test case espliciti aiutano l'agente a capire le tue aspettative.

5. Criteri di validazione: Come farà un reviewer a sapere se il lavoro è completo? Cosa dovrebbe ispezionare? Quali domande dovrebbe farsi?

Questo framework dovrebbe suonare familiare se hai lavorato con scenari BDD, template di issue con criteri di accettazione, o design document. Il formato specifico conta meno dell'avere le informazioni giuste in una forma condivisibile e revisionabile.

Dove vivono le specifiche nel tuo workflow

Una delle cose migliori delle specifiche è la loro flessibilità. Non devono essere documenti separati che ti rallentano. Una specifica può vivere ovunque abbia senso per il tuo team:

• Una GitHub issue con criteri di accettazione espliciti
• Una descrizione PR che indica il comportamento che cambia
• Uno scenario BDD nei tuoi file feature
• Una nota di design leggera prima dell'implementazione
• Strumenti come OpenSpec o GitHub Spec Kit che formalizzano questo pattern

La chiave è rendere il contesto e i criteri di revisione visibili e persistenti. La tua specifica non dovrebbe svanire quando la sessione chat finisce. Dovrebbe viaggiare insieme al lavoro, dando ai colleghi qualcosa di concreto da valutare.

Il livello dell'incarico: separare l'intento dall'esecuzione

È qui che le cose si fanno davvero interessanti.

Le specifiche più solide si comportano come piccoli contratti comportamentali. Separano tre domande distinte:

1. Quale comportamento deve cambiare? (Il requisito)
2. Quali vincoli o esempi definiscono la correttezza? (I criteri di accettazione)
3. Quale percorso implementativo sembra appropriato adesso? (L'approccio tecnico)

Queste domande sono connesse, ma non dovrebbero collassare in un unico blocco di istruzioni.

Perché questo conta per gli agenti AI di coding? Perché quando mescoli intento e implementazione troppo presto, l'agente può ottimizzare per la cosa sbagliata. Potrebbe seguire fedelmente un dettaglio implementativo suggerito mentre perde il comportamento effettivo che ti serviva. O potrebbe produrre codice tecnicamente interessante che non risolve il problema dichiarato.

Un livello di incarico tiene il requisito stabile mentre permette all'implementazione di evolvere. Mentre l'agente legge la codebase, scopre complicazioni, e raffina il suo approccio, la specifica resta il punto di riferimento: "Il lavoro ha soddisfatto questo?"

Questo è particolarmente prezioso per codebase esistenti. La maggior parte del lavoro engineering non è su tabula rasa — stai cambiando comportamento che già esiste. Una buona specifica dice: ecco il comportamento attuale, ed ecco cosa deve cambiare. I reviewer non devono ricostruire mentalmente il tuo intento partendo dai dettagli implementativi.

Fare il cambiamento

Se sei abituato a trattare gli agenti AI come motori di ricerca supercaricati, questo potrebbe sembrare overkill. Ma considera l'alternativa: modifiche non controllate a codice condiviso, PR difficili da revisionare, e lavoro che non corrisponde esattamente a quello che avevi immaginato.

Il passaggio a collaborazione AI guidata da specifiche non riguarda la burocrazia. Riguarda dare sia agli umani che alle macchine la chiarezza di cui hanno bisogno per lavorare insieme efficacemente.

Inizia piano. La prossima volta che stai per inviare un agente AI in una repository, fermati cinque minuti per scrivere il contesto, il cambiamento comportamentale, e i criteri di successo. Mettilo da qualche parte di visibile — anche se è solo nella descrizione della PR.

Il te futuro (e i tuoi colleghi) ti ringrazieranno.

Il punto finale: Gli agenti AI di coding sono collaboratori potenti. Trattali come collaboratori. Dai loro un brief appropriato, e otterrai lavoro che vale la pena revisionare.