PathruleLe regole come guardrail
Come una regola di Pathrule con un pattern di blocco approvato può fermare una modifica non conforme prima che venga applicata, mentre tutte le altre regole accompagnano il lavoro come contesto.
In questa pagina
In Pathrule una regola non è un appunto che l'assistente leggerà più avanti. È un guardrail che arriva prima che l'assistente agisca. La maggior parte della documentazione ti dice cosa è andato storto dopo il rilascio. Un guardrail può fermare la modifica prima che venga applicata.
Questa pagina spiega la differenza tra il contesto che informa un turno e una regola che può bloccarlo. Per i meccanismi con cui gli hook consegnano il contesto, leggi prima Come funzionano gli hook. Qui vediamo cosa fa una regola vincolante una volta che quel contesto è disponibile.
Il pull chiede. Il push arriva.
Il vecchio modello è di tipo pull. L'assistente deve ricordarsi di chiedere le tue convenzioni, chiamare uno strumento e leggere il risultato prima di modificare qualcosa. Se se ne dimentica, modifica alla cieca e il problema lo scopri in revisione.
Il modello degli hook è di tipo push. Su Claude Code e Codex il contesto arriva senza che l'assistente lo chieda, quando invii un prompt e subito prima che l'assistente usi uno strumento. Cursor e GitHub Copilot non hanno un hook all'invio del prompt, quindi lì è l'hook di avvio sessione a portare il bootstrap e sono gli hook degli strumenti a portare le regole del percorso interessato. In entrambi i casi, quando l'assistente sta per scrivere un file, le regole legate a quel percorso sono già davanti a lui. Windsurf non ha hook: legge il file delle regole di Pathrule e chiede altro al server MCP locale, quindi su Windsurf le regole informano ma non bloccano.
Due livelli: consultivo e bloccante
Non tutte le regole devono interrompere l'assistente. Pathrule gestisce le regole su due livelli.
- Le regole consultive accompagnano il lavoro come contesto. Compaiono accanto al file che l'assistente sta per toccare, con la loro priorità, così l'assistente può tenerne conto. Non fermano nulla. La maggior parte delle regole è consultiva, a qualunque priorità.
- Le regole vincolanti possono bloccare. Una regola diventa rigida quando ha un pattern di blocco approvato da una persona: una forma vietata nel contenuto, come un import, un identificatore, un nome di classe o una dichiarazione CSS, una posizione vietata per un file, oppure entrambe. Quando l'assistente sta per modificare o scrivere un file in un modo che corrisponde al pattern, l'hook ferma la chiamata allo strumento prima che il file venga scritto e ne restituisce il motivo. L'assistente lo legge e riprova, questa volta rispettando il vincolo.
Priorità e blocco sono indipendenti. La priorità (alta, media, bassa) decide quanto una regola viene messa in evidenza e quali regole rientrano quando lo spazio è poco. Non decide il blocco: ogni regola vincolante del percorso viene controllata, qualunque sia la sua priorità.
Come una regola diventa rigida
Un assistente non può attivare da solo un pattern di blocco.
- La regola viene scritta prima in linguaggio naturale, da te o da un assistente a cui l'hai chiesto.
- Un assistente può proporre un pattern di blocco tramite gli strumenti MCP di scrittura e aggiornamento delle regole. La forma preferita indica il testo vietato esattamente come lo scrive la regola, con esempi reali che devono essere intercettati e casi simili che non devono esserlo. Pathrule costruisce il pattern a partire da questi e lo verifica su entrambi gli insiemi; se uno dei due test fallisce, la proposta viene rifiutata con il motivo, invece di essere indebolita.
- La proposta viene salvata insieme alla regola e non viene applicata.
- Solo dopo l'approvazione di una persona l'hook inizia a bloccare, e il rimedio scritto per il pattern diventa il "fai invece così" che l'assistente vede.
Una regola può anche avere un controllo obbligatorio: un comando di verifica che deve essere passato prima che il turno finisca, come la suite di test di un pacchetto. Come un pattern di blocco, viene proposto e non viene applicato finché una persona non lo approva. Una volta approvato, su Claude Code e Codex l'hook tiene aperto il turno, indicando il comando esatto da eseguire, finché il controllo non è passato.
Cosa vede l'assistente
Una modifica bloccata torna indietro con il nome della regola, una breve anteprima della regola, il rimedio approvato e un riferimento alla regola completa. Per una regola chiamata "No direct database client in UI components", appare così:
Pathrule blocked: "No direct database client in UI components"
UI components never import the database client. Data goes through the data layer hooks.
Do this instead: call the data layer hook for this resource.
Your edit matches this rule's forbidden pattern. Read the full rule via pathrule_read_rule(<id>) and retry without the violation.
Claude Code, Codex, Cursor e GitHub Copilot lo ricevono come diniego della chiamata allo strumento, nel formato di hook proprio di ciascun client. Windsurf non ha hook, quindi lì non viene bloccato nulla. Il blocco si applica alle modifiche e alle scritture di file; un comando di shell riceve comunque la regola come contesto.
La separazione è voluta. Bloccare una modifica poco rischiosa spreca il turno dell'assistente e il tuo. Il blocco è riservato alle regole per cui una violazione è una vera regressione e qualcuno ha approvato esattamente cosa conta come violazione.
Prima e dopo
Considera una regola secondo cui i segreti non finiscono mai nei file committati, con un pattern di blocco approvato per il formato di chiave usato dal tuo provider.
| Senza il guardrail | Con il guardrail | |
|---|---|---|
| L'intenzione dell'assistente | Aggiungere una chiave API a un file di configurazione per far funzionare una funzionalità | Uguale |
| Cosa succede | La modifica viene applicata | L'hook blocca la chiamata allo strumento corrispondente prima che il file venga scritto |
| Quando te ne accorgi | Più tardi, in revisione (o mai) | Nello stesso turno. L'assistente vede il testo della regola e passa a una variabile d'ambiente |
| Risultato su disco | Un segreto committato | La modifica corrispondente non è stata scritta |
Lo stesso schema vale per qualsiasi regola che un team ha imparato a caro prezzo in produzione: una policy di accesso ai dati che deve filtrare per utente, una convenzione per le migrazioni, un file generato che non va modificato a mano. La regola smette di essere un commento che si spera l'assistente abbia letto e diventa un controllo che viene eseguito prima che la modifica sia applicata. Un pattern di blocco intercetta le forme per cui è stato approvato, quindi affianca la revisione invece di sostituirla.
I nomi dei file richiamano la memoria giusta
Non sempre devi aspettare una chiamata a uno strumento. Su Claude Code e Codex, quando il tuo prompt nomina un file a cui si riferisce una memoria collegata, l'hook del prompt può mostrare il contenuto di quella memoria prima che l'assistente apra qualsiasi cosa. Spesso basta nominare il file su cui stai lavorando per mettere il contesto giusto davanti all'assistente fin dal primo turno. Quando più memorie corrispondono allo stesso nome di file, l'hook mostra i candidati invece di tirare a indovinare.
Fail-open per progettazione
Un guardrail che blocca il tuo flusso di lavoro quando si guasta è peggio di nessun guardrail. Pathrule è fail-open. Se l'hook non riesce a valutare una regola, va in errore o va in timeout, non blocca il tuo lavoro. La modifica prosegue. L'applicazione delle regole è una rete di sicurezza, non un cancello dietro cui puoi restare bloccato.
Il controllo resta a te. Se vuoi disattivare completamente gli hook, basta un file.
Verificalo da solo
Non devi fidarti sulla parola.
Per vedere quali hook ha registrato il tuo client di IA, leggi il suo file di impostazioni. Per Claude Code, Pathrule registra i suoi hook nel progetto:
cat .claude/settings.json
Cursor usa .cursor/hooks.json, Codex usa .codex/hooks.json e GitHub Copilot usa .github/hooks/pathrule.json.
Per disattivare all'istante tutti gli hook di Pathrule (l'interruttore di emergenza), crea un file:
touch ~/.pathrule/kill-hooks
La chiamata successiva a uno strumento passa direttamente, senza alcun intervento di Pathrule. Elimina il file per riattivare gli hook:
rm ~/.pathrule/kill-hooks
Per verificare che una regola sia davvero legata a un percorso, esegui pathrule rule list nella cartella, oppure apri nell'editor la vista del contesto Pathrule dell'assistente. La regola compare con la sua priorità prima che l'assistente agisca su quel percorso, e una regola vincolante mostra il suo blocco la prima volta che una modifica corrisponde al pattern.
Cosa leggere dopo
- Come funzionano gli hook per i meccanismi di consegna e il comportamento quando non c'è contenuto.
- Scrivere regole per capire come scrivere una regola che valga la pena applicare.
- Panoramica di MCP per il percorso di approfondimento che l'assistente usa quando l'hook non basta.