Scrivere regole

Una regola è un vincolo che l'assistente deve rispettare all'interno di un ambito. Le regole sono il contenuto più forte di Pathrule: arrivano come requisiti e non come informazioni di contorno, e una regola che porta con sé un vincolo eseguibile approvato può fermare una modifica corrispondente prima che venga applicata.

Questa pagina spiega quando scrivere una regola, come scegliere ambito e priorità, che cosa significa applicarla e quali pattern evitare.

Quando scrivere una regola

Ricorri a una regola quando c'è qualcosa che l'assistente non deve mai fare, o qualcosa che deve fare sempre, in una parte specifica del codice.

• "Non usare mai la service role key nel codice eseguito nel browser."
• "Tutti gli importi sono salvati come interi in centesimi. Non usare mai i float."
• "Le migrazioni devono essere eseguite prima della relativa modifica al codice. Nessuna eccezione."
• "I file JSX in apps/web usano solo classi Tailwind. Niente CSS module, niente stili inline."

Se la risposta è "dipende dalla situazione, l'assistente dovrebbe valutarla", allora si tratta di una memoria, non di una regola. Le regole servono per le cose non negoziabili.

Tipi di ambito

Ogni regola ha un tipo di ambito che stabilisce a quali percorsi o file si applica.

• folder. Si applica a un sottoalbero di directory. È la scelta migliore per regole specifiche di un'area: tutto ciò che sta sotto apps/api/auth, tutto ciò che sta sotto services/billing.
• file_type. Si applica ai file che corrispondono a un glob come *.tsx o **/*.test.ts. È la scelta migliore per aspetti trasversali legati a un tipo di file e non a una directory.
• project. Si applica ovunque nel workspace. Usalo con parsimonia: una regola di progetto accompagna ogni prompt.

L'ambito e il percorso del nodo a cui la regola è associata decidono insieme che cosa vede l'assistente. Una regola folder associata a /apps/web copre tutto ciò che sta sotto apps/web.

Livelli di priorità

La priorità decide con quanta insistenza la regola si fa vedere. All'interno di un ambito corrispondente, le regole con priorità più alta vengono considerate per prime.

• high. Per ciò che, se violato, causa bug, regressioni di sicurezza o problemi di conformità.
• medium. Il valore predefinito. Usalo per ciò che vale "quasi sempre, ma non è portante".
• low. Stilistica. Emerge quando c'è spazio e l'argomento è pertinente. Usala per gusti e convenzioni.

La priorità alta è un budget limitato. Se metà delle tue regole ha priorità alta, nessuna ce l'ha davvero. Scegli quelle che proprio non possono essere violate.

Applicazione: consultiva e vincolante

L'applicazione è un'impostazione distinta dalla priorità. La priorità stabilisce con quanta forza una regola emerge; l'applicazione decide che cosa succede in caso di violazione.

• advisory. La regola è contesto. L'assistente la valuta e decide come applicarla. Le regole che scrivi dalla CLI o da VS Code, e quelle scritte da un assistente, sono consultive.
• strict. Una regola diventa vincolante quando porta con sé un vincolo eseguibile approvato da una persona: la forma esatta vietata, ad esempio un import, un identificatore o una posizione. A quel punto l'hook pre-tool può bloccare la modifica o la scrittura di un file che vi corrisponde prima che venga applicata, restituendo come motivazione la regola e il relativo rimedio. Un assistente può allegare un vincolo proposto quando scrive o aggiorna una regola (pathrule_write_rule, pathrule_update_rule), ma la proposta viene salvata come tale e non blocca nulla finché una persona non la approva; un assistente non può mai approvare le proprie. Vedi Le regole come guardrail.

Riscrivere una regola mantiene l'applicazione coerente. Un vincolo approvato è legato alla frase della regola rispetto alla quale è stato verificato. Se riscrivi la regola e quella frase scompare, il vincolo smette da solo di essere applicato, così una regola non continua mai a bloccare per un motivo che non dichiara più. Modificare altre parti della regola, o aggiungere un paragrafo, lascia attivo un vincolo non toccato.

Il blocco dipende dal client. La Pathrule CLI installa gli hook sugli strumenti per Claude Code, Codex, Cursor e GitHub Copilot, e un blocco vale dove l'hook pre-tool del client rispetta la decisione. Windsurf non ha hook e Remote MCP non ne installa, quindi lì le regole arrivano solo come contesto. La sola consegna non applica nulla.

Struttura

Una regola ha un nome e un corpo. Mantieni il corpo breve e all'imperativo.

Name: No service role key in browser code

Body:
- Never import SUPABASE_SERVICE_ROLE_KEY in any file under apps/web.
- Use the anon key plus row level security.
- If you need server only access, do it from apps/api or a server action.

Dal terminale, la stessa regola richiede un solo comando. Senza --body, la CLI apre il tuo editor per scrivere il corpo.

pathrule rule add --path /apps/web --name "No service role key in browser code" --priority high --scope folder

In VS Code usa New Rule…, mentre un assistente scrive le regole con pathrule_write_rule.

La forma che in pratica funziona meglio è un solo vincolo per regola, con un corpo breve a punti elenco. Le regole lunghe e discorsive vengono lette di sfuggita sia dalle persone sia dagli assistenti.

Riutilizzabili, non duplicate

Una regola risiede in un solo percorso e copre tutto ciò che sta sotto, quindi una regola basta per un intero sottoalbero. Se lo stesso vincolo vale per due cartelle lontane tra loro, mettilo nel loro percorso comune più vicino, oppure usa un ambito file_type con un glob, invece di copiare e incollare il testo in due regole. Una sola regola significa una sola modifica quando il vincolo cambia.

Pathrule ti aiuta in questo: una nuova regola il cui nome coincide con quello di una regola già presente nel workspace viene rifiutata per impostazione predefinita, e la scrittura ti indica quale regola esiste già. Puoi forzarla deliberatamente (allow_duplicate tramite MCP) dopo aver controllato la regola esistente. Per spostare una regola altrove, trasferiscila in un altro percorso (Move… in VS Code, oppure pathrule_update_rule con move_to_path).

Versioni e modifiche simultanee

Le regole hanno un token di versione, come le memorie. Se due colleghi modificano la stessa regola nello stesso momento, si genera un conflitto pulito invece di una sovrascrittura reciproca. In VS Code il conflitto offre le stesse scelte previste per una memoria: Reload, Copy My Version & Reload oppure Keep Mine (Overwrite).

Come le regole arrivano all'assistente

• Le regole in un ambito corrispondente vengono ordinate per priorità e per pertinenza rispetto all'attività. Le più pertinenti arrivano con il corpo completo; le altre vengono solo nominate, così l'assistente sa che esistono e può leggerne una per intero con pathrule_read_rule.
• Una regola vincolante arriva sempre completa dove si applica, perché il solo nome non basta a spiegare un blocco.
• Le regole vengono anche compilate nei file di istruzioni letti dai tuoi client (ad esempio CLAUDE.md per Claude Code e AGENTS.md per Codex), così anche un client senza hook sui prompt parte da lì.

Se una regola può bloccare una modifica, invece di limitarsi a informare l'assistente, lo stabilisce la sua modalità di applicazione (advisory o strict), non la sua priorità.

Anti-pattern

• Priorità alta per tutto. Scegli le regole che contano davvero. Le altre dovrebbero essere medium.
• Regole che sembrano memorie. "Di solito preferiamo X" è una memoria. "Non fare mai Y" è una regola.
• Regole che si sovrappongono. Due regole ad alta priorità formulate in modo contraddittorio sono peggio di una sola regola chiara.
• Ambito di progetto usato di default. La maggior parte delle regole va sotto una cartella. Porta una regola a project solo se vale davvero ovunque.

Creazione in locale e su Cloud

Gli esempi da terminale con add in questa pagina si riferiscono a un workspace Cloud. In modalità locale, crea e modifica le voci in Local Console, in VS Code o tramite MCP locale; i comandi della CLI dedicati alla conoscenza servono a elencarle, leggerle e cercarle.

Cosa leggere dopo

• Scrivere memorie per fatti e decisioni che non sono vincoli.
• Scrivere skill per procedure riutilizzabili che l'assistente può richiamare.
• Come funzionano gli hook per capire come il runtime decide quali regole far emergere.