Scrivere un brief tecnico che l'AI può seguire davvero

Nella lezione precedente abbiamo visto come chiarire un'idea con ChatGPT prima di aprire Lovable: cosa fa il prodotto, per chi è, qual è l'unica azione che conta nella prima versione. Quel riassunto è un buon punto di partenza, ma da solo si perde facilmente, ogni nuova conversazione con Lovable riparte da zero se non gli dai un posto dove ricordarsi le cose. Questa lezione trasforma quel riassunto in un brief strutturato che puoi riusare, e che Lovable può leggere come contesto stabile del progetto.

## In breve

Un brief tecnico efficace per Lovable non è un documento tecnico pieno di gergo: è un insieme ordinato di informazioni, cosa fa il prodotto, chi lo usa, quali sono le regole di business, cosa non deve cambiare, scritto in modo che l'AI possa seguirlo senza doverlo indovinare. Lovable ha già uno strumento pensato apposta per questo: il Knowledge file, un campo di testo persistente che l'agente considera a ogni messaggio. Un buon brief è, in pratica, la prima bozza di quel file.

Che cos'è (e cosa NON è)

Un brief tecnico per l'AI è un documento breve che raccoglie il contesto che Lovable non può indovinare da solo: cosa deve fare l'applicazione, chi la usa, quali sono i vincoli, cosa non va toccato. Non è un capitolato con diagrammi UML o schemi di database scritti a mano, quello, nella maggior parte dei casi, Lovable lo genera da solo a partire da una descrizione in linguaggio naturale, come vedremo anche nel prossimo modulo dedicato alle API.

Non è nemmeno un documento scritto una volta e mai più toccato. La documentazione ufficiale di Lovable è chiara su questo: il Knowledge file va aggiornato ogni volta che lo stack o l'architettura cambiano, "così Lovable non continua a seguire pattern superati." È un documento vivo, non un contratto firmato all'inizio.

Come funziona

Lovable distingue due livelli di contesto persistente: la project knowledge, specifica di un singolo progetto, e la workspace knowledge, condivisa tra tutti i progetti di uno stesso spazio di lavoro (utile soprattutto in team, per regole comuni di stile o architettura). Entrambe sono semplici campi di testo, fino a 10.000 caratteri, e vengono lette da Lovable insieme al codice del progetto prima di generare qualsiasi modifica.

Secondo la stessa documentazione, una buona project knowledge include tipicamente:

• cosa fa l'applicazione;
• chi sono gli utenti o i profili target;
• lo schema del database o le tabelle principali, se già esistono;
• le decisioni di architettura prese finora;
• la terminologia specifica del dominio (come si chiamano le cose, nel tuo settore);
• eventuali vincoli specifici del progetto;
• linee guida di design (colori, tipografia, layout);
• link a riferimenti importanti, come documentazione di API esterne;
• eventuali requisiti di sicurezza o compliance.

Il consiglio pratico di Lovable è di scriverlo "come se stessi facendo onboarding a un nuovo sviluppatore che entra nel team": abbastanza dettagliato da evitare che rifaccia scelte già prese, abbastanza sintetico da restare leggibile. Le istruzioni specifiche battono le indicazioni generiche, "abilita sempre la modalità strict di TypeScript" funziona meglio di "scrivi codice pulito", per fare l'esempio che la stessa documentazione usa per il caso più tecnico.

## Perché conta

Senza un brief, ogni conversazione con Lovable riparte dalle informazioni contenute in quel singolo scambio di messaggi. Se il contesto del progetto non è mai stato scritto da qualche parte, tocca a te ripeterlo ogni volta, e prima o poi qualcosa si perde, con il risultato che Lovable propone soluzioni già scartate o cambia elementi che avevi deciso di non toccare.

Lovable stesso lo definisce così nella sua guida principale: il Knowledge file "è la cosa più impattante che puoi impostare" per un progetto. Non è un dettaglio opzionale per utenti avanzati: è la differenza tra un agente che ricostruisce il contesto ogni volta da zero e uno che lavora dentro un quadro stabile che tu hai definito una volta sola.

## Esempio lampante

### Contesto ipotetico

una piccola associazione culturale vuole un sito dove i soci possano iscriversi agli eventi in programma.

INPUT. Il prompt di partenza, scritto senza pensarci troppo: "Fammi un sito per iscriversi agli eventi della nostra associazione."

ANALISI. Manca praticamente tutto quello che serve a costruire bene: quanti eventi ci sono di solito, se c'è un limite di posti, se i soci pagano una quota diversa dai non soci, se serve un elenco visibile di chi si è già iscritto, che tono deve avere il sito (istituzionale? informale?).

DECISIONE. Prima di scrivere qualsiasi prompt, l'associazione mette per iscritto un brief breve: cosa fa il sito (iscrizione a eventi con posti limitati), chi lo usa (soci e non soci, con quote diverse), la regola di business più delicata (quando i posti finiscono, il modulo deve chiudersi automaticamente), il tono (caldo, non aziendale), cosa non deve cambiare (il logo e i colori dell'associazione, già decisi altrove).

OUTPUT. Questo brief diventa sia il primo prompt su Lovable sia, subito dopo, il contenuto del Knowledge file del progetto. Ogni prompt successivo, "aggiungi un evento", "cambia il testo della conferma", eredita automaticamente quel contesto, senza doverlo riscrivere ogni volta.

Come farlo

1. Parti dal riassunto ottenuto con ChatGPT nella lezione precedente: cos'è il prodotto, per chi è, qual è l'azione chiave della prima versione.
2. Organizzalo sotto poche intestazioni fisse: cosa fa il prodotto, chi lo usa, regole di business da rispettare, cosa NON deve cambiare, tono e stile.
3. Scrivi ogni punto come un'istruzione specifica, non come un'indicazione generica: "il modulo di iscrizione si chiude da solo quando i posti finiscono" funziona meglio di "gestisci bene i posti limitati".
4. Se hai già riferimenti utili, un sito che ti piace, una palette di colori, la documentazione di un servizio esterno che userai, aggiungili come link.
5. Usa questo brief come primo prompt su Lovable, raccontato come una storia concreta (vedi la lezione precedente).
6. Copia lo stesso contenuto, o una sua versione più tecnica via via che il progetto cresce, in Project settings → Knowledge dentro Lovable, così resta contesto permanente e non solo un messaggio di chat che scorre via.
7. Aggiorna il brief quando qualcosa di importante cambia: una nuova regola di business, una decisione di design, un vincolo tecnico emerso costruendo.

## Errori comuni

### Scrivere un brief troppo lungo e generico

Un brief di due pagine pieno di indicazioni vaghe è meno utile di dieci righe specifiche. Lovable stesso consiglia di preferire elenchi puntati e regole dirette a paragrafi lunghi.

Riempirlo di dettagli tecnici che non servono ancora

Schema del database scritto a mano, nomi esatti di tabelle SQL: se il progetto non esiste ancora, questi dettagli li genera Lovable stesso a partire dalla descrizione in linguaggio naturale. Aggiungerli manualmente ha senso più avanti, quando l'architettura è già stabile.

### Dimenticare i guardrail

Dire cosa non deve cambiare è utile quanto dire cosa costruire: un brief che elenca solo cosa fare, senza dire cosa evitare, lascia a Lovable margini di interpretazione più ampi di quanto vorresti.

Scriverlo una volta e non aggiornarlo più

Un Knowledge file rimasto fermo alle prime decisioni del progetto, mentre il progetto è cambiato, rischia di guidare Lovable verso scelte ormai superate.

Quando questo lavoro conta meno

Per una modifica isolata e già chiara, cambiare un colore, correggere un testo, spostare un elemento, non serve nessun brief: un prompt diretto in Build mode basta. Anche per un prototipo veloce, buttato via dopo il test, un brief formale rallenta più di quanto aiuti. Il brief tecnico rende di più quando il progetto ha più di una schermata, coinvolge regole di business specifiche, o continuerà a crescere nelle settimane successive.

## In sintesi

Il brief tecnico è il ponte tra l'idea chiarita con ChatGPT e il progetto reale su Lovable: poche informazioni specifiche, cosa fa il prodotto, chi lo usa, cosa non va toccato, scritte come si spiegherebbero a un nuovo collega. Lovable ha già lo strumento giusto per farlo diventare contesto permanente, il Knowledge file, ed è la cosa più impattante che si può impostare in un progetto secondo la stessa documentazione ufficiale.

Chi vuole approfondire i principi generali dietro un buon prompt, ruolo, contesto, compito, formato, trova una base utile anche fuori da Lovable nella lezione sul prompt engineering per il marketing: gli stessi quattro elementi valgono, con qualche adattamento, anche quando il destinatario del prompt è un tool di vibe coding invece di un copywriter AI.

## Cosa imparare dopo

Con un'idea chiara e un brief scritto, il passo successivo è vedere come questi due elementi si trasformano in un progetto reale dentro Lovable. Nella prossima lezione seguiamo il flusso di lavoro pratico dall'idea al prototipo.

---

Vuoi provarlo?

Prova Lovable →

Link di affiliazione: se ti iscrivi da qui, ricevo una piccola commissione, a te non cambia nulla.