Come funziona il brief con l’AI: dal problema in parole tue alla specifica
· 9 min · ai, brief, agentic-coding, edge
Il punto da cui parte ogni progetto del lab. Racconti un problema, l’AI ti aiuta a spremerlo in requisiti che poi diventano la specifica contro cui lavora un agente.
Prima di scrivere una riga di codice serve sapere cosa si sta costruendo. Ovvio a dirsi, quasi mai vero nella pratica: si parte da un’idea a metà e la si scopre mentre la si scrive. Il wizard su /request è un tentativo di spostare quel lavoro di scoperta prima, e di farlo fare a due teste: quella di chi scrive e quella del modello. Niente modulo da compilare: una conversazione guidata che finisce con un documento contro cui poi si lavora.
Si parte dal problema, non dal settore
La prima schermata chiede una cosa sola: qual è il problema, con parole tue. Niente menù a tendina di categorie, niente “scegli il tuo settore fra 40”. Scrivi che gestisci un poliambulatorio e le prenotazioni ti arrivano su tre canali diversi, e da lì l’AI deduce il settore da sola. Lo fa con l’azione analyze della funzione edge: legge il testo libero e ne tira fuori il campo, il tono, il tipo di prodotto. Se sbaglia si corregge dopo, ma nella quasi totalità dei casi parte già inquadrata bene, e questo cambia tutte le domande che vengono dopo.
Chi non ha voglia di scrivere può dettare: il wizard usa il riconoscimento vocale del browser (Web Speech), quindi la trascrizione avviene sul dispositivo, senza che l’audio passi dal lab. È una comodità tenuta apposta perché toglie l’attrito iniziale: la schermata vuota è il punto in cui la gente molla.
Le domande di contesto, una per schermata
Una volta capito il campo, il wizard fa qualche domanda di contesto: chi sono gli utenti, cosa devono poter fare, cosa esiste già. Una domanda per schermata, mai un questionario lungo che intimidisce. Il ritmo è quello di una chat, non di un modulo. Le risposte non finiscono in un cassetto: diventano il materiale grezzo da cui l’AI, nel passo dopo, prova a dedurre i requisiti veri.
La fase requisiti: l’AI propone, tu decidi
Qui sta il cuore. L’AI non ti chiede “elenca i requisiti”: chiederlo a un cliente è il modo più veloce per avere una lista sbagliata. Li propone lei: con l’azione propose_requirements guarda il problema e il contesto e butta giù una prima lista di cose che il sistema dovrebbe fare. Tu leggi e reagisci: questo sì, questo no, questo è quasi giusto ma il pagamento va a fine mese non all’ordine. Ogni tua correzione torna al modello con refine_requirement, che riformula quel singolo requisito e te lo ripropone più preciso. Si gira così finché la lista non ti suona giusta.
Il punto da difendere è che il modello non chiude mai la porta. Puoi aggiungere un requisito che non aveva pensato, toglierne uno, spaccarne uno in due. L’AI riformula, non impone. È un loop con l’umano dentro nel punto che conta: la decisione su cosa il sistema deve davvero fare resta tua, l’AI fa il lavoro di stenografia intelligente intorno.
Il conto si fa prima del modello
Dietro c’è una funzione edge sola, generate-brief, con quattro azioni: analyze, propose_requirements, refine_requirement, generate_brief. Ognuna ha il suo slot di modello (l’analisi iniziale può girare su un modello economico, il brief finale merita quello buono) così un compito piccolo non paga un modello grosso. E c’è una regola imparata a proprie spese: il rate limit si conta prima di chiamare il modello, non dopo. Se rifiuti dieci volte di seguito un requisito e l’AI riformula dieci volte, quelle chiamate contano; ma una richiesta respinta dal limite non deve bruciare budget che non ha speso. All’inizio era fatto al contrario, e un pomeriggio di test a vuoto aveva mangiato il tetto giornaliero senza aver prodotto niente.
Il brief: requisiti congelati, milestone, tempi
Quando la lista è ferma, l’azione generate_brief compila il documento. I requisiti si congelano: restano quelli che hai approvato, verbatim, non una parafrasi che il modello si inventa in fondo. Sopra ci mette una proposta di milestone, una roadmap a fasi e una stima di tempi realistica, con una nota su quale parte è più incerta. Il brief è un accordo su cosa si costruisce e in che ordine, e nessun preventivo.
Perché è lo stesso inquadramento di ogni progetto
La ragione per cui questo passo conta va oltre /request. È esattamente il modo in cui parte ogni progetto del lab, anche quando il progetto è del lab stesso. Prima di mettere un agente a scrivere codice, si scrive l’inquadramento: cosa deve fare, i vincoli veri, cosa non deve rompere. Il brief, requisiti più roadmap, è quella specifica. È il documento contro cui l’agente implementa e contro cui si legge il risultato: se il comportamento non torna, il confronto è con il brief, non con il ricordo di cosa si voleva fare.
È questo passaggio umano→AI che rende affidabile il resto. Un agente lasciato senza specifica scrive qualcosa di plausibile, e ti accorgi tre giorni dopo che ha risolto il problema sbagliato. Con un brief chiaro davanti, l’agentic coding smette di essere una scommessa e diventa un lavoro con un metro. Il brief con l’AI è il primo anello della catena con cui si costruisce tutto il resto.
Sviluppi futuri
Cosa non fa ancora, e sarebbe utile. Oggi il brief nasce dalle parole: non guarda un sito esistente, un foglio di calcolo, lo screenshot del gestionale che già usi. Servirebbe poter partire da materiale reale (“ecco com’è ora, ecco cosa non va”) invece che dalla sola descrizione. Poi c’è la memoria: ogni brief nasce da zero, ma molti problemi si somigliano, e una libreria di requisiti ricorrenti (login, pagamenti, ruoli) potrebbe accorciare la parte noiosa. E infine l’anello che oggi si collega a mano: dal requisito approvato ai test che lo verificano. Il giorno in cui ogni requisito del brief nasce già con il suo controllo, il confronto “il codice fa quello che era stato detto?” lo fa la macchina. Nessuna di queste è promessa con una data; sono le direzioni allo studio.