Convenzioni di progetto, stile, vincoli: scriverli una volta sola

Se ripeti la stessa istruzione in 5 prompt diversi, qualcosa nel sistema non funziona. Le decisioni ricorrenti devono vivere in un posto stabile (file di regole + linter + template) dove sono caricate automaticamente. Quel posto stabile è anche dove le decisioni evolvono in modo controllato.

Perché questa lezione conta

Ogni regola ripetuta a mano è una regola che prima o poi salti. Saltata una volta, codice generato si discosta. Codebase diventa misto: parti che seguono convenzione, parti che no. Refactor di consolidamento costa di più del costo originale di automatizzare la regola. Centralizzare convenzioni è investimento ad altissimo ritorno.

Obiettivo operativo

Alla fine devi saper:

1. distinguere convenzioni soft (linee guida) da hard (forzate da tooling);
2. scegliere dove vive ogni convenzione (regole AI, linter, formatter, schema, template);
3. far evolvere convenzioni senza riscrivere tutto.

Nucleo della lezione

1. Tre livelli dove vivono convenzioni

Livello 1 — File di regole AI (AGENTS.md): convenzioni “morbide” che il modello deve conoscere ma non sono enforced da tool. Naming, struttura cartelle, pattern preferiti, divieti scope. Lette dall’AI, non dal compilatore.

Livello 2 — Tool di check automatico: convenzioni enforced. Linter (ESLint, Biome, Ruff), formatter (Prettier, Biome, Black), type checker (TS, mypy), git hooks (husky, lefthook). Errori bloccano commit/merge. Non si possono saltare.

Livello 3 — Template, snippet, scaffolding: convenzioni “incarnate” in strutture pronte. Template progetto, snippet IDE, generatori (Plop, Hygen, Yeoman, comandi del framework). L’utente non deve nemmeno conoscere la convenzione: la riceve gratuita.

Ogni convenzione importante dovrebbe vivere al livello più alto possibile (3 > 2 > 1). Se una convenzione vive solo nel file di regole, prima o poi viene violata.

2. Categorie di convenzioni

Formattazione: indentazione, larghezza riga, virgolette, semicolon, trailing comma. Livello 2 (Prettier/Biome). Convenzione non discutibile dopo setup iniziale.

Naming: variabili, funzioni, file, classi, costanti. Misto: linter copre alcuni (es. ESLint naming-convention), il resto vive in regole AI + revisione PR.

Gestione errori: throw vs Result, log vs silenzio, propagazione vs cattura. Difficile enforce automatico. Vive in regole AI + esempi + revisione.

Struttura componenti: shape file (es. “props in cima, stato dopo, render in fondo”). Difficile enforce. Vive in regole AI + few-shot.

Pattern di test: nominazione (describe/it), AAA pattern (Arrange/Act/Assert), uso di mock vs stub. Vive in template test + regole AI.

Documentazione: tipi di commento ammessi, JSDoc obbligatorio o no, README per modulo. Linter parziale, regole AI per il resto.

Tono e contenuto (microcopy, errori, label): non è codice ma è convenzione. Vive in design system + regole AI per generazione.

Sicurezza minima: nessun segreto in codice (gitleaks), nessun eval, no any, validazione input. Linter + git hooks.

3. Aggiornamento controllato

Una regola non si aggiunge perché qualcuno (tu o un libro) lo dice. Si aggiunge quando previene un errore reale.

Sequenza:

1. Errore osservato: il modello ha fatto X di nuovo, è il terzo task in cui devo correggere.
2. Prevenibile: c’è una convenzione che, se rispettata, eviterebbe X?
3. Decisione livello: posso enforce con tool (livello 2)? Se no, regola AI (livello 1).
4. Aggiungi: in 1-2 righe brevi nel file di regole, oppure rule del linter.
5. Verifica: il prossimo task simile rispetta la convenzione?
6. Pulizia futura: se la convenzione è stata rispettata per 1+ mese senza errori, è interiorizzata. Se non viene mai violata da quando esiste, valuta se è ancora necessaria.

Errore: aggiungere regole “preventive” senza errore osservato. File di regole esplode, modello le ignora, tu non ricordi cosa c’è dentro.

Procedura pratica

Sequenza per consolidare convenzioni in progetto esistente:

1. Audit: rileggi 5-10 prompt recenti. Quali istruzioni si ripetono?
2. Categorizza: ognuna è formattazione / naming / errori / struttura / test / doc / sicurezza?
3. Decidi livello: enforce automatico (linter/tool) o regole AI?
4. Setup tool mancante (se serve): Prettier, Biome, ESLint config, husky pre-commit.
5. Aggiorna AGENTS.md con regole non automatizzabili.
6. Crea template/snippet per pattern ricorrenti (es. nuovo componente, nuovo test, nuovo endpoint).
7. Verifica: prossimi 5 prompt non devono ripetere istruzioni consolidate.

Laboratorio guidato

Per il tuo progetto attivo:

Step 1: lista 10 istruzioni che hai ripetuto a mano negli ultimi prompt.

Esempi tipici:

• “Usa async/await, non .then()”.
• “Nessun any in TypeScript”.
• “I commit devono seguire Conventional Commits”.
• “Componenti UI in src/components/ui/”.
• “Test in stesso folder del file testato, suffisso .test.ts”.
• “Validazione email con validator.isEmail, non regex”.
• “Nessun segreto in codice”.
• “Errori utente in italiano, log in inglese”.

Step 2: per ognuna, scegli livello:

• “no .then()” → ESLint rule prefer-await.
• “no any” → tsconfig noImplicitAny: true + ESLint no-explicit-any.
• “Conventional Commits” → husky + commitlint.
• “componenti UI in folder X” → regole AI (difficile enforce) + template scaffold.
• “test in stesso folder” → regole AI + .vscode snippet.
• “validator.isEmail” → regole AI.
• “no segreti” → gitleaks pre-commit.
• “italiano UI / inglese log” → regole AI.

Step 3: implementa quello che è automatizzabile (linter, hook). Sposta il resto in AGENTS.md.

Step 4: prossima generazione AI, verifica: stai ancora ripetendo o no?

Output atteso

Una mappa “convenzioni → livello”: tabella con istruzioni e dove vive ciascuna (tool, file regole, template). + un AGENTS.md aggiornato e un package.json con script di check necessari.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: ridurre ripetizione nei prompt e aumentare coerenza facendo vivere le decisioni ricorrenti in un posto stabile. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Convenzioni: formattazione, naming, gestione errori, struttura componenti, pattern di test, tono dei contenuti.
• Vincoli tecnici: versioni, dipendenze consentite, browser target, accessibilità, performance e sicurezza minima.
• Aggiornamento controllato: una regola si aggiunge quando evita errori reali, non per gusto di completezza.

3. Applicazione: svolgi il laboratorio: estrarre da tre prompt ripetitivi le regole comuni e spostarle in un documento condiviso. L’output da ottenere è: una pagina di convenzioni che permette prompt più brevi e risposte più coerenti.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• ho identificato 5+ convenzioni ricorrenti nei miei prompt;
• almeno metà sono enforced automaticamente (linter, hook, type);
• l’altra metà vive in AGENTS.md o template;
• non ripeto manualmente istruzioni consolidate nei nuovi prompt.

Errori comuni

Tutto in regole AI. Niente automatizzato → modello le rispetta a singhiozzo.

Tutto in linter. Linter non sostituisce regole semantiche. “Errori utente in italiano” non è enforce automatico.

Convenzioni aggiunte senza errore osservato. File di regole gonfio, regole inutili.

Convenzioni mai aggiornate. Stack cambia, regole no. Modello applica pattern obsoleti.

Niente template. Ogni nuovo componente da zero, ogni volta diverso. Template = convenzione gratuita.

Conflitto fra livelli. Linter dice una cosa, regole AI un’altra. Modello si confonde. Allinea.

Prompt di lavoro

Aiutami a consolidare convenzioni del mio progetto.

Stack: [...]

Ti elenco 10 istruzioni che ripeto manualmente nei prompt:
1. [...]
2. [...]
...

Per ognuna:

1. Categorizza (formattazione / naming / errori / struttura / test / doc / sicurezza / altro).
2. Suggerisci dove enforce: tool automatico, file di regole AI, template/snippet.
3. Per quelle automatizzabili, indica configurazione concreta (es. ESLint rule X con opzioni Y).
4. Per quelle in regole AI, formula in 1-2 righe brevi e verificabili.

Concludi con:
- lista nuove dipendenze/tool da aggiungere
- patch suggerite a AGENTS.md
- ordine di implementazione (impatto vs costo).

Non scrivere ancora codice. Voglio prima decidere il piano.

Esercizio finale

Misura: prima di consolidare convenzioni, conta le righe ripetute negli ultimi 10 prompt. Dopo aver consolidato, conta le righe nei prossimi 10 prompt. La riduzione è il valore della lezione, espresso in tempo che hai recuperato. Spesso 30-50%.