Scrivi un brief per un agente

Descrivi una modifica valutabile da un revisore

«Aggiungi l’esportazione dei clienti» lascia aperte diverse decisioni. Chi può esportare i record? Quali record e campi sono inclusi? Cosa accade se una richiesta fallisce? Un agente può colmare questi vuoti con scelte plausibili. Possono comunque essere sbagliate per l’azienda.

Parti dall’utente e dal problema. Descrivi poi il comportamento richiesto. Includi le prove che mostreranno se il risultato è accettabile.

Un brief deve ridurre l’incertezza senza fissare ogni scelta progettuale interna. Specifica il confine dei dati richiesto. Lascia che l’implementazione segua le convenzioni esistenti del repository, salvo ragioni per cambiarle.

Usa un esempio concreto

Il brief seguente riguarda un’applicazione fittizia di assistenza. È un esempio didattico, non una specifica completa per la produzione.

Risultato: Un responsabile dell'assistenza può scaricare un elenco clienti.
Soggetto: Un manager nell'organizzazione attuale.
Dati: Solo i clienti attivi di quell'organizzazione.
Campi: ID cliente, ragione sociale e stato dell'account.
Formato: CSV UTF-8 con una riga di intestazione.
Richiesta negata: Restituire l'errore di autorizzazione esistente.
Risultato vuoto: Restituire un CSV valido con la sola intestazione.
Ambito: Usare la route di esportazione e il modello di audit esistenti.
Esclusioni: Nessun nuovo ruolo, dipendenza o deployment.
Prove: Test per richieste consentite, negate, vuote e tra organizzazioni.

Il brief individua comportamenti utili e limiti. Fa anche emergere altre domande. Il sistema deve limitare la dimensione dell’esportazione? Un campo può contenere una formula per fogli di calcolo? Chi può accedere al registro di audit? Risolvi le domande con conseguenze rilevanti prima dell’implementazione. Non trattare l’esempio come una checklist universale.

Separa i requisiti dalle ipotesi

Un requisito definisce un comportamento che la modifica deve soddisfare. Un’ipotesi è un fatto non ancora verificato. Tienili separati.

Per esempio, «Usa il modello di audit esistente» presuppone che esista un modello adatto. Chiedi all’agente di trovarlo. Se il repository non ne contiene uno, l’agente deve segnalare la dipendenza mancante prima di inventare un nuovo sistema di audit.

Un vincolo può anche entrare in conflitto con il risultato. La route esistente potrebbe restituire intenzionalmente tutte le organizzazioni. L’agente deve mostrare il conflitto e proporre una correzione limitata. Non deve eliminare tacitamente il confine dei dati o estendere il compito a una riscrittura architetturale.

Includi le prove nel completamento

Richiedi un riepilogo della consegna che spieghi comportamento finale, variazioni di ambito e verifiche eseguite. Chiedi comandi e risultati esatti quando contano. Distingui una verifica superata da una che non è stato possibile eseguire.

La pull request deve conservare il motivo della modifica. Chi manterrà il codice in seguito potrebbe non avere la conversazione originale. Includi abbastanza contesto da spiegare perché l’esportazione esclude certi campi e come viene controllato l’accesso.

Le indicazioni di Google sulle descrizioni delle modifiche sono un riferimento utile. La descrizione deve spiegare la modifica e il suo scopo. Aggiornala per rispecchiare l’implementazione finale dopo le modifiche richieste in revisione.

Mantieni il brief proporzionato

Una piccola correzione di testo può avere un brief breve. Un’esportazione di dati richiede più dettagli perché gli errori possono esporre informazioni. Un nuovo flusso di pagamento richiede ancora più analisi e revisione.

Non misurare la qualità del brief dalla lunghezza. Chiediti se un revisore competente possa distinguere un risultato corretto da uno errato. Se due implementazioni ragionevoli differiscono su un comportamento con conseguenze rilevanti, chiarisci prima quel comportamento.