Definire il manifest di progetto e i confini architetturali per l'LLM
Come scrivere il manifest di progetto e i confini architetturali per l'LLM: cosa può toccare, cosa no, e come tenerlo allineato tra una sessione e l'altra.
Nella guida sull’architettura di un progetto vibe-coded, la cartella docs/ è il cervello a lungo termine del progetto. Al centro c’è un file specifico: lo SPEC.md, o manifest di progetto.
Quando usi un assistente IA, il problema non è solo fargli scrivere una funzione che oggi gira. È evitare che, tra tre giorni, per aggiungere un bottone in UI possa riscrivere la logica del database.
Qui ti mostro cosa mettere nel manifest e come fissare i confini architetturali (chi parla con chi, cosa si può toccare) prima del primo pezzo di codice.
Che cos’è davvero un manifest per l’LLM
Il manifest non è un README commerciale. Il README parla a un umano (installazione, scopo). Il manifest (SPEC.md / MANIFEST.md) è un contratto operativo tra te e l’assistente.
Tra una sessione e l’altra l’IA non «ricorda» le decisioni di ieri, a meno che non le rilegga. Se restano implicite, può scegliere la scorciatoia più breve — spesso la peggiore per sicurezza e debito tecnico — per la sola richiesta del momento.
A cosa serve:
- ridare le regole a ogni nuova chat;
- limitare dipendenze inutili;
- segnare file/moduli da non toccare;
- definire quando un compito è finito (Definition of Done).
Le sezioni fondamentali del manifest
Un manifest buono si legge in pochi secondi. Nei miei setup uso sei blocchi fissi.
| Sezione dello SPEC.md | Status | Cosa scrivere (e perché) |
|---|---|---|
| Obiettivo Visione breve | Obbligatorio | Una o due frasi di perimetro. Es.: «Script Python locale per rinominare fatture PDF dal testo, senza API esterne.» |
| Stack Linguaggi e tool | Obbligatorio | Elenco rigido + versioni dove conta (es. Python 3.12, solo libreria X). Riduce allucinazioni di pacchetti. |
| Flusso dei dati Dove vive lo stato | Obbligatorio | SQLite? JSON? Solo memoria? Se non lo dici, l’IA può spargere log e file di stato a caso. |
| Confini Chi parla con chi | Obbligatorio | Es.: «La UI non interroga il DB: passa solo da api/.» |
| Non-scope Cosa non fa | Consigliato | Es.: «Niente auth utente. Niente cronologia cloud.» Blocca la sovra-ingegnerizzazione. |
| Definition of Done Chiusura feature | Obbligatorio | Es.: «Passa lo smoke test; niente crash su input vuoti; niente secret in log.» |
Confini: regole di ingaggio
Senza isolamento, l’LLM può produrre un god-file: migliaia di righe che fanno DB + UI + auth + API. Da lì le modifiche diventano fragili e l’audit di sicurezza più difficile.
Do (imponi)
- Modularità — file separati per UI, business, dati; evita monoliti.
- Segreti — solo variabili d’ambiente; niente stringhe di connessione in chiaro.
- Input — sanitizza/valida prima di passare ai layer interni.
Don’t (proibisci)
- Dipendenze a sorpresa — niente
pip/npmnuovi senza accordo. - Violazione di livello — la UI non importa i modelli DB; passa dai controller/API.
- API pericolose — vietati
eval()/os.system()salvo richiesta esplicita nel prompt corrente.
🚨 Avviso critico — Niente segreti nello SPEC
Non mettere API key, password o path personali inSPEC.md. Quel file finisce nel contesto inviato al provider del modello. Per gli esempi usa valori palesemente finti (sk-ESEMPIO-NON-REALE).
Laboratorio: creare il file e agganciarlo
1. Creazione
Windows (CMD):
mkdir docs
type nul > docs\SPEC.mdWindows (PowerShell):
New-Item -ItemType Directory -Force docs | Out-Null
New-Item -ItemType File -Force docs\SPEC.md | Out-NullmacOS / Linux:
mkdir -p docs
touch docs/SPEC.mdCompila le sei sezioni con i dati del tuo progetto (non lasciare placeholder eterni).
2. Prompt «zero-code» (prima del codice)
Non dare lo SPEC e chiedere subito l’app intera: rischi sovrascritture e pezzi non testabili.
Apri una chat nuova e ancora il file:
Leggi docs/SPEC.md (obiettivo, stack, confini, non-scope, Definition of Done).
Non generare ancora nessun codice.
Rispondi solo con un elenco puntato dei limiti architetturali che devi rispettare,
poi attendi istruzioni sul primo modulo.💡 Consiglio pratico — Cursor
Digita@docs/SPEC.mdnella chat prima del prompt, così forzi il caricamento del file.
3. Un modulo alla volta
Quando l’assistente conferma i limiti (niente eval, stack bloccato, UI ≠ DB), chiedi solo la connessione dati. Verifica. Nuova sessione → di nuovo @docs/SPEC.md → API. Poi UI.
Manutenzione: quando aggiornare
Il manifest non è eterno. Se da «solo memoria» passi a «salva PDF su disco», lo scope è cambiato: aggiorna lo SPEC prima di chiedere l’implementazione.
Altrimenti la sessione successiva leggerà regole obsolete. Se hai sperimentato due ore e non ricordi i confini nuovi, puoi chiedere:
In base alle ultime modifiche concordate, proponi un diff per docs/SPEC.md
che rifletta i nuovi confini. Non toccare il codice applicativo.Poi valuti tu se accettare il diff.
Errori comuni
- Troppo vago — «Fai un’app Python sicura» non è un confine. Specifica moduli, hash, dipendenze ammesse.
- Solo security theater — vietare
evalnon basta: senza regole di comunicazione tra layer, la UI può comunque interrogare il DB. - Niente DoD — «migliora il codice» senza criterio → decorazioni infinite e regressioni.
Domande Frequenti (FAQ)
Cos’è un manifest di progetto per l’LLM?
Un documento locale (SPEC.md) che fissa obiettivo, stack, confini e Definition of Done. Funziona da contratto operativo tra te e l’assistente tra una sessione e l’altra.
Qual è la differenza tra README e SPEC.md?
Il README parla agli umani (uso, installazione). Lo SPEC dà istruzioni imperative all’IA su come generare e cosa non fare.
Quali confini servono anche in un progetto piccolo?
Isolamento dati (UI ≠ storage diretto), divieto di dipendenze non autorizzate, niente credenziali hardcoded. Anche in 200 righe conta.
Dove metto il file e come lo cito in Cursor?
Di solito docs/SPEC.md. In chat: @docs/SPEC.md poi il prompt. Allinea la struttura alla guida architettura vibe-coded.
Devo riscrivere il manifest a ogni feature?
No. Aggiornalo quando cambiano confini, stack o obiettivo (es. da memoria a file su disco).
Posso mettere API key o password nello SPEC?
No. Usa finti esempi e punta a .env / secret del provider. Lo SPEC finisce nel contesto remoto del modello.
Il manifest sostituisce .cursorrules?
No. Lavorano in coppia: regole editor / stile risposta vs architettura e confini di questo progetto. Un pezzo dedicato alle .cursorrules è in coda nel cluster.
