Vibe coding con le regole: perché un CLAUDE.md batte il prompt

Il vibe coding funziona anche su un prodotto vero, a una condizione: che le regole non stiano nel prompt, ma in file che l'agente di coding rilegge all'inizio di ogni sessione. Un prompt brillante vale per una conversazione; un CLAUDE.md scritto bene vale per tutte quelle che verranno. In Sweet Pal le regole che contano davvero sono poche, ognuna nata da un errore, e ognuna porta scritto il suo perché.

Sweet Pal oggi è fatto di quattro cartelle e quattro repository: l'app iOS in SwiftUI, la dashboard amministrativa, il sito con la documentazione tecnica e la vecchia app in Expo, archiviata ma ancora funzionante. Tutti e quattro parlano con lo stesso progetto Supabase, dove convivono le tabelle di due generazioni di prodotto, con nomi abbastanza simili da trarre in inganno. Un agente di coding, per quanto capace, arriva qui senza memoria. Non sa che la cartella che sembra "l'app" potrebbe essere quella vecchia, né che il repository del sito ha un nome storico che fa pensare al progetto intero, né che una tabella chiamata meals non è quella che usa l'app di oggi. Se glielo diciamo nel prompt, lo sa per un'ora. Se lo scriviamo in un file, lo sa ogni volta.

Per questo le istruzioni stanno a strati, come le cartelle. C'è un CLAUDE.md nella cartella che contiene tutto, corto, che fa una cosa sola: orientare. Dice quale cartella è il prodotto attuale, cosa sono le altre tre, dove va in produzione ciascuna e che il database è condiviso; la prima riga che conta, in grassetto, chiede di assicurarsi di essere nella cartella giusta prima di toccare "l'app". Poi c'è un file dentro ogni progetto, che entra nel dettaglio: come si prova in locale, come si pubblica, quali variabili servono, quali trappole conosciamo. Quello dell'app iOS è il più denso, perché lì stanno le regole vincolanti.

Poche regole, tutte meccaniche

La prima è anche la più importante: prima di creare, guardare cosa c'è già. Con un database condiviso fra due generazioni, la mossa più pericolosa di un agente è anche la più naturale: creare una tabella nuova per una cosa che esiste, o modificare una tabella vecchia credendo che sia del prodotto nuovo. Accanto c'è una regola banale, ed è proprio per questo che funziona: ogni tabella nuova porta il prefisso swp_, con una sola eccezione dichiarata, users, che è condivisa. Le altre famiglie di nomi appartengono al sistema precedente, e il file lo dice chiaro. Un prefisso trasforma un dubbio in un controllo meccanico.

Poi c'è la regola che sorprende di più chi arriva da fuori: mai supabase db push. Lo storico delle migration in locale non coincide con quello remoto, e un push spingerebbe in blocco anche quelle vecchie. Così ogni modifica allo schema si prepara come SQL pronto da incollare, e la incolla una persona nel SQL Editor. La conseguenza l'abbiamo dovuta imparare: il codice arriva in produzione con un push, la migration quando qualcuno la incolla, e per qualche minuto o qualche ora uno dei due è avanti rispetto all'altro. Il 22 settembre il pannello amministrativo è rimasto rotto per qualche ora proprio così. Da allora il pannello riconosce l'errore della tabella mancante e dice quale file SQL incollare, invece di mostrare il messaggio grezzo del database.

Le chiavi dei fornitori di modelli e degli altri servizi stanno nei secret di Supabase, mai nell'app e mai nel repository; il file aggiunge un dettaglio che fa risparmiare mezz'ora di confusione, cioè che la dashboard mostra l'impronta della chiave e non il suo valore. E c'è una regola con una data, l'8 luglio. Il working tree principale ha quasi sempre lavori a metà; un giorno una modifica dell'agente è finita nello stesso file di un cantiere in corso, e un colore è stato committato insieme a una funzione che non era pronta. Da quel giorno ogni lavoro che modifica file parte da un git worktree isolato su un branch dedicato, si builda lì e alla fine entra in main con un merge fast-forward. Mai committare cantieri altrui. L'ultima è di stile: tanti file piccoli, non pochi file enormi. Con un agente conta più che con una persona, perché un file da duemila righe si legge a pezzi, e a pezzi si capisce male.

Il perché va scritto

Una regola senza motivazione viene piegata al primo caso limite. "Non usare db push" sembra una preferenza; "lo storico locale e quello remoto non coincidono, e un push spingerebbe le vecchie migration" è un fatto con cui non si discute. Per questo quasi ogni regola nei nostri file ha accanto la ragione e, quando c'è, la data e il nome di chi l'ha decisa. Lo stesso vale per le trappole tecniche: nel file della dashboard c'è un avvertimento sul middleware, che fino al 28 settembre stava nella cartella sbagliata e non girava, senza che niente lo segnalasse. Il file non si limita a dire dove deve stare, ma spiega come verificare che sia davvero attivo dopo il build. Una regola che contiene il proprio controllo è una regola che l'agente può applicare da solo.

Le istruzioni di progetto, però, non sono documentazione. Non descrivono il codice, che si legge da sé, e non raccontano lo stato dei lavori, che cambia ogni giorno e ha un posto suo: i documenti di passaggio fra sessioni, di cui parleremo in un altro articolo. Dentro ci va solo quello che un agente non può ricavare guardando i file: convenzioni, divieti, motivi, errori già fatti.

L'espressione "vibe coding" fa pensare a un modo di lavorare leggero, in cui si descrive un'idea e il codice arriva. In parte è così. Ma su un prodotto che tratta dati clinici, con un database condiviso e quattro repository, la leggerezza se la può permettere solo chi ha messo per iscritto i confini. Le regole non rallentano l'agente: gli tolgono le decisioni che non deve prendere, e gli lasciano quelle che sa prendere bene.

In sintesi:

• Il prompt vale per una sessione; un file di istruzioni nel repository vale per tutte.
• Le istruzioni stanno a strati: un file che orienta nella cartella di lavoro, uno dettagliato per progetto.
• Le regole più utili sono poche e meccaniche: guardare prima di creare, un prefisso per le tabelle nuove, migration incollate a mano, segreti fuori dal codice, un worktree per lavoro.
• Ogni regola porta il suo perché, e quando può il modo di verificarla.
• Lo stato dei lavori non va nelle istruzioni: ha bisogno di un documento suo, aggiornato a ogni sessione.