Concetti fondamentali

Pathrule ha volutamente un modello dati ridotto: tre tipi di contenuto, un albero di nodi e un ambito basato sui percorsi. Una volta chiara questa struttura, tutto il resto di Pathrule viene da sé.

Mentre leggi questa pagina, tieni presente una cosa: i tre tipi di contenuto descritti qui sotto sono la superficie di scrittura. Sono ciò che una persona scrive, modifica e discute, e sono degli input. Quello che riceve un agente dipende invece dall'attività: solo le voci pertinenti al lavoro che ha davanti, ordinate per priorità e adattate all'attività. Di questo aspetto si occupa la panoramica dell'architettura; questa pagina tratta ciò che scrivi tu.

L'albero del workspace

Un workspace è un albero di nodi. La radice è il workspace stesso. I figli sono cartelle o file che rispecchiano le parti del repository su cui il tuo team scrive conoscenza.

/                            workspace root
  /apps                      folder node
    /apps/web                folder node
      /apps/web/auth         folder node
        /apps/web/auth/login.tsx   file node

Non devi creare l'albero a mano. Quando scrivi una memoria in /apps/web/auth, Pathrule crea al momento la catena di nodi necessaria. I nodi vuoti non costano nulla e si eliminano facilmente in seguito, se il percorso smette di essere utile.

Memorie

Una memoria è un breve documento Markdown che un membro del team scrive perché l'assistente possa leggerlo in seguito.

• Fatti: note sullo schema, decisioni di design, insidie.
• Postmortem: cosa si è rotto, cosa abbiamo imparato, come abbiamo rimediato.
• Convenzioni: il modo in cui questo team preferisce fare una certa cosa.

Per impostazione predefinita le memorie sono consultive. Compaiono nel contesto dell'assistente quando l'hook stabilisce che sono pertinenti al percorso su cui l'assistente sta lavorando.

La maggior parte delle memorie viene scritta da persone o da un assistente che lavora con te. In un workspace Cloud, Pathrule ne aggiunge anche alcune di sua iniziativa: brevi note sulle tecnologie nella radice del workspace, come "TypeScript project" o "Docker containerization", riconosciute dai nomi dei file la prima volta che un agente richiede un contesto approfondito. Sono memorie normali, quindi puoi modificarle o eliminarle come qualsiasi altra.

Regole

Una regola è un vincolo che l'assistente deve rispettare all'interno di un ambito.

Una regola ha:

• Un tipo di ambito. folder significa che la regola si applica sotto una directory. file_type significa che si applica a un glob di file come *.tsx. project significa che si applica in tutto il workspace.
• Una priorità. high per i vincoli più importanti, medium per le indicazioni generali, low per le preferenze stilistiche. La priorità determina con quanta evidenza compare una regola, non se blocca.
• Una modalità di applicazione. Le regole advisory accompagnano il lavoro come contesto e l'assistente decide come applicarle. Una regola strict porta con sé un vincolo eseguibile approvato da una persona e può bloccare una modifica corrispondente prima che venga applicata, nei client i cui hook vengono eseguiti prima di una chiamata a uno strumento.
• Un corpo. Funziona meglio un breve elenco puntato di istruzioni all'imperativo.

Le regole con priorità più alta compaiono per prime quando il loro ambito corrisponde al percorso corrente. Quelle con priorità più bassa compaiono quando è probabile che siano utili.

Skill

Una skill è una procedura con un nome che l'assistente può invocare invece di ricostruire ogni volta i passaggi da zero.

Esempi:

• replay-stripe-webhook: una checklist con il comando CLI esatto e i passaggi di sicurezza da seguire prima di eseguirlo.
• regenerate-fixtures: il percorso dello script, gli input e l'output atteso.
• release-check: la checklist pre-rilascio che il team vuole sempre far seguire all'assistente.

Le skill si trovano per nome. L'assistente può chiedere a Pathrule le skill associate al percorso corrente e scegliere quella adatta all'attività.

Ambito per percorso

Ogni memoria, regola e skill risiede nel percorso di un nodo. È il percorso a decidere dove compare.

• Una memoria in /apps/web è pertinente per qualsiasi lavoro sotto apps/web.
• Una memoria in / è pertinente ovunque.
• Una skill in /services/billing viene proposta all'assistente quando il lavoro si svolge all'interno del servizio di fatturazione.

È l'ambito per percorso a mantenere ridotta la finestra di contesto dell'assistente. Una piccola modifica all'interfaccia in apps/web/dashboard non ha bisogno di vedere le regole sulle migrazioni del database.

Priorità e applicazione

Priorità e applicazione sono due impostazioni indipendenti.

• La priorità (high, medium, low) stabilisce con quanta evidenza compare una regola. Usa high con parsimonia, per i vincoli più importanti.
• L'applicazione (advisory o strict) decide cosa succede in caso di violazione. Le regole consultive vengono fornite come contesto e l'assistente decide come applicarle; ogni nuova regola parte come consultiva. Un agente può proporre un vincolo eseguibile per una regola: viene salvato come proposta e non viene applicato. Una volta approvato da una persona, l'hook locale controlla una modifica corrispondente prima che venga applicata, può bloccarla e indica la regola come motivo.

Pathrule CLI e l'estensione per VS Code registrano gli hook disponibili per Claude Code, Codex, Cursor e GitHub Copilot, e il blocco funziona dove l'hook del client può fermare una chiamata a uno strumento. Windsurf non ha hook e il Remote MCP non ne installa: entrambi ricevono le regole come contesto, senza alcun evento di blocco di Pathrule prima della scrittura.

Come si inserisce nel quadro

• Cosa calcola Pathrule tratta il livello derivato che si affianca a questi tre tipi di contenuto scritto.
• Come funzionano gli hook descrive come il runtime sceglie la porzione da inviare.
• Panoramica di MCP elenca gli strumenti che l'assistente usa per leggere e scrivere i nodi.
• Guida rapida è il modo più veloce per vedere questo modello all'opera.