File di regole: cosa metterci

Un file di regole (AGENTS.md, CLAUDE.md, .cursor/rules/, .windsurfrules) è la “memoria” del progetto per gli agenti AI. Caricato a ogni sessione, dice al modello come deve lavorare in questo specifico repo. Senza, il modello inventa convenzioni a ogni richiesta. Con, il comportamento diventa stabile e prevedibile.

Perché questa lezione conta

Il file di regole è il singolo investimento di tempo con maggiore ROI nel vibe coding. Mezz’ora di scrittura iniziale + 5 minuti di aggiornamento periodico = ore risparmiate ogni settimana in correzioni di output. Il file fa la differenza fra “il modello capisce subito” e “devo ripetere ogni volta gli stessi vincoli”.

Obiettivo operativo

Alla fine devi saper:

1. distinguere contenuti utili (vivono nel file di regole) da contenuti inutili (rumore);
2. scrivere un AGENTS.md che resta sotto le 100 righe e copre il 90% dei casi;
3. mantenerlo aggiornato senza che diventi un manuale.

Nucleo della lezione

1. Cosa va nel file di regole

Cinque categorie di contenuto utile:

Comandi essenziali:

• come avviare l’app in dev (npm run dev, bun dev);
• come buildare (npm run build);
• come testare (npm test, comando preciso, anche npm test -- --run se serve);
• come lintare/formattare (npm run lint);
• come fare check di tipi (npm run typecheck).

Il modello li usa per verificare il proprio lavoro. Senza, non sa quando il task è “fatto”.

Stack e versioni:

• linguaggio + versione (Node 20.x, Python 3.12);
• framework (Next.js 15, Astro 5);
• database (Postgres 16 via Supabase);
• librerie principali (TanStack Query, shadcn/ui).

Evita che il modello inventi API di versioni diverse.

Convenzioni del codice:

• naming (camelCase per JS, snake_case per Python, kebab-case per file);
• struttura cartelle (es. “componenti UI in src/components/ui/”);
• pattern preferiti (es. “usare async/await, no .then() chain”);
• gestione errori (es. “Result<T,E> per funzioni che possono fallire”);
• commenti (es. “minimi, solo per WHY non per WHAT”);

Vincoli e divieti:

• cosa NON fare (“no nuove dipendenze senza approvazione”);
• file vietati (“non toccare configurazione, .env, lockfile, schema migration”);
• pattern da evitare (“no useEffect per data fetching, usare TanStack Query”);
• scope dei task (“un task = un comportamento, no refactor laterali”).

Riferimenti utili:

• link a docs/architettura.md;
• link a docs/decisions.md;
• link a documentazione interna importante;
• link a README per setup completo.

2. Cosa NON metterci

Anti-pattern che gonfiano il file:

• Regole ovvie: “scrivi codice corretto”, “usa Git”. Il modello già sa.
• Contraddizioni: regole che si annullano fra loro. Verifica coerenza.
• Preferenze non motivate: “preferisco tab a spazi” senza ragione → confusione se il codice esistente è diverso.
• Istruzioni troppo lunghe: paragrafi di 200 parole su singola convenzione → modello salta.
• Regole non verificabili: “scrivi codice elegante”. Né tu né il modello sapete cos’è.
• Storia del progetto: appartiene al README, non al file regole.
• Tutorial: come usare framework, ecc. Non è il posto.
• Cambiamenti temporanei: “questa settimana non aggiungere feature”. Vivono nel prompt o in TODO, non nel file di regole.

Test di pertinenza: questa regola, quando il modello la legge, cambia cosa farebbe? Sì → tienila. No → toglila.

3. Regole globali vs note temporanee

Due livelli:

• Globali (file di regole): stabili, valgono per ogni task. Stack, comandi, convenzioni, divieti.
• Note temporanee (prompt o TODO file): specifiche per una sessione/task. “Oggi lavoriamo solo su src/auth/”, “non installare nuove dipendenze in questa PR”.

Errore tipico: mettere note temporanee nel file di regole, non rimuoverle mai. File diventa archivio storico, non guida operativa.

Ciclo sano:

• nuova convenzione emersa → aggiungi al file di regole;
• decisione one-shot per un task → prompt;
• regola superata da migrazione → rimuovi dal file (verifica codebase);
• conflitto fra regole → risolvi a freddo, una vince, l’altra scompare.

Caso guidato

Repo: piccola app Astro con contenuti Markdown e pagine corso. Un file di regole troppo generico direbbe:

- Scrivi codice pulito.
- Segui best practice.
- Non fare errori.

Non serve: sono frasi non verificabili. Un file utile, invece, contiene vincoli che un agente può rispettare:

## Comandi
- Build: `npm run build`
- Non avviare dev server se il task riguarda solo contenuti Markdown.

## Contenuti
- Le lezioni stanno in `src/content/lezioni/`.
- Ogni lezione deve avere frontmatter con `titolo`, `durata`, `ordine`, `descrizione`.
- Mantenere le sezioni: Perché, Obiettivo, Nucleo, Procedura, Laboratorio, Output, Checklist, Errori, Prompt, Esercizio.

## Stile
- Italiano chiaro, esempi concreti, niente slogan.
- Ogni lezione deve produrre un artefatto verificabile.

## Limiti
- Non modificare design o routing durante task di contenuto.
- Non cambiare `ordine` senza controllare l'indice del corso.

Queste regole sono utili perché impediscono errori reali: build saltata, frontmatter rotto, sezioni mancanti, modifiche fuori scope. Ogni riga deve rispondere alla domanda: “quale errore previene?”.

Procedura pratica

Per scrivere un nuovo file di regole:

1. Setup iniziale (30 min): parti da template (esempio sotto). Adatta a stack e progetto.
2. Verifica coerenza: rileggi, niente contraddizioni.
3. Test pratico: una sessione AI con il file di regole. Va dove vuoi? Mancano regole? Aggiungi.
4. Aggiornamento dopo errori: ogni volta che il modello sbaglia in modo evitabile, considera se aggiungere una regola.
5. Pulizia periodica (mensile): rileggi, togli regole stale, accorcia.

Misura: file sopra 100 righe = troppo. Dovrai accorciare.

Laboratorio guidato

Esempio AGENTS.md per progetto Astro + Tailwind + Supabase:

# AGENTS.md

## Comandi essenziali
- Dev: `bun dev` (porta 4321)
- Build: `bun run build`
- Type check: `bun run astro check`
- Test: `bun test`
- Lint: `bun run lint`

## Stack
- Astro 5 (SSR su Vercel Edge)
- Tailwind CSS 4 (config in `tailwind.config.mjs`)
- Supabase (auth + Postgres)
- TanStack Query (lato client per data fetching)
- shadcn/ui (componenti React in `src/components/ui/`)

## Struttura
- `src/pages/`: route Astro
- `src/components/ui/`: primitivi shadcn
- `src/components/{feature}/`: componenti per feature
- `src/lib/`: utility, client Supabase, hook
- `src/content/`: collezioni Astro (markdown)
- `docs/`: architettura.md, decisions.md

## Convenzioni codice
- TS strict, no `any` se non motivato in commento
- File componenti: PascalCase (`Button.tsx`); util: kebab-case (`format-date.ts`)
- Async/await, no `.then()`
- Server-side fetch dentro `getStaticProps`/`load`, niente fetch in componenti server
- Errori: `Result<T, AppError>`, mai `throw` non gestito
- Commenti: solo per WHY non per WHAT

## Vincoli rigidi
- NO nuove dipendenze senza approvazione esplicita
- NO modifiche a `astro.config.mjs`, `tailwind.config.mjs`, `tsconfig.json` senza approvazione
- NO commit con `console.log`, `debugger`, codice commentato
- NO regex per validare email (usa `validator` già in deps)

## Sicurezza
- Mai esporre `SUPABASE_SERVICE_ROLE_KEY` lato client
- Validazione: lato client per UX, lato server obbligatoria per dati
- RLS abilitato su tutte le tabelle Supabase

## Riferimenti
- Architettura: `docs/architettura.md`
- Decisioni: `docs/decisions.md`
- Setup completo: `README.md`

Una pagina, sotto 100 righe, copre 90% dei casi. Adattalo al tuo progetto.

Output atteso

File AGENTS.md per il prossimo progetto reale, sotto 100 righe, organizzato in 5-7 sezioni. Salvato in root del repo.

Studio passo passo

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

1. Prima lettura: chiarisci l’obiettivo: scrivere istruzioni di progetto che guidano l’AI in modo stabile senza trasformarle in un manuale ingestibile. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Contenuti utili: comandi di build/test, stile codice, struttura cartelle, limiti di scope, convenzioni di naming.
• Cosa evitare: regole ovvie, contraddizioni, preferenze non motivate, istruzioni troppo lunghe o non verificabili.
• Differenza tra regole globali del progetto e note temporanee per un task specifico.

3. Applicazione: svolgi il laboratorio: creare un file AGENTS.md o equivalente per una repo demo con massimo venti regole ad alto valore. L’output da ottenere è: un file di istruzioni pronto per agenti AI, leggibile anche da esseri umani.

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 un file di regole per ogni progetto attivo;
• è sotto 100 righe;
• ogni regola passa il test “cambia cosa il modello farebbe”;
• non contiene contraddizioni;
• aggiornato nell’ultimo mese.

Errori comuni

File enorme. 500 righe di “best practices generiche”. Modello salta, tu non rileggi mai. Tieni breve.

Regole inverificabili. “Scrivi codice elegante”. Non aiuta nessuno.

Niente comandi. Modello non sa come testare/buildare → non verifica autonomamente.

Stack stale. File dice “Next 13” quando ora sei su 15. Modello applica pattern obsoleti.

Note temporanee mai rimosse. “Questa settimana non…”. Sei mesi dopo è ancora lì, fuori contesto.

Regole contraddittorie. Sezione 1 dice una cosa, sezione 4 l’opposto. Modello sceglie a caso. Verifica coerenza.

Niente vincoli espliciti. Senza “NO nuove dipendenze”, il modello le aggiunge a ogni richiesta.

Prompt di lavoro

Aiutami a costruire AGENTS.md per questo progetto.

Stack: [linguaggio + framework + librerie principali]
Tipo progetto: [...]
Convenzioni rigide attuali: [se ce ne sono]
Comandi: [come avvio dev, build, test, lint]

Genera AGENTS.md in 5-7 sezioni:
1. Comandi essenziali
2. Stack e versioni
3. Struttura cartelle
4. Convenzioni codice
5. Vincoli rigidi e divieti
6. Sicurezza (3-5 regole specifiche al mio stack)
7. Riferimenti

Vincoli output:
- max 100 righe
- ogni regola deve cambiare cosa l'AI farebbe (test di pertinenza)
- niente contraddizioni
- niente regole ovvie

Concludi indicando 2-3 regole che non sono ancora chiare per te e che dovresti decidere prima.

Esercizio finale

Apri il file di regole del tuo progetto principale (se non c’è, creane uno). Per ogni regola, applica il test: “cambia cosa farebbe il modello?”. Toglile quelle che non passano. Probabilmente accorci del 30-50%. File più corto = modello che lo legge per davvero.