Conceitos principais

O modelo de dados do Pathrule é pequeno de propósito: três tipos de conteúdo, uma árvore de nós e um escopo baseado em caminhos. Depois que você entende esse formato, o resto do Pathrule se explica por si.

Guarde uma coisa enquanto lê esta página: os três tipos de conteúdo abaixo são a superfície de autoria. É o que uma pessoa escreve, edita e discute, e eles são entradas. O que um agente recebe depende da tarefa: apenas as entradas que se aplicam ao trabalho em questão, priorizadas e ajustadas à tarefa. A visão geral da arquitetura trata desse lado; esta página trata do que você escreve.

A árvore do espaço de trabalho

Um espaço de trabalho é uma árvore de nós. A raiz é o próprio espaço de trabalho. Os filhos são pastas ou arquivos que espelham as partes do seu repositório sobre as quais a sua equipe registra conhecimento.

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

Você não precisa criar a árvore manualmente. Quando você escreve uma memória em /apps/web/auth, o Pathrule cria sob demanda a cadeia de nós correspondente. Nós vazios não custam nada e são fáceis de apagar depois, caso o caminho deixe de ser útil.

Memórias

Uma memória é um documento curto em Markdown que alguém da equipe escreve para que o assistente possa ler depois.

• Fatos: notas sobre o schema, decisões de design, armadilhas.
• Postmortems: o que quebrou, o que aprendemos, como corrigimos.
• Convenções: o jeito que esta equipe prefere fazer determinada coisa.

Por padrão, memórias são orientativas. Elas aparecem no contexto do assistente quando o hook decide que são relevantes para o caminho em que o assistente está trabalhando.

A maioria das memórias é escrita por pessoas ou por um assistente trabalhando com você. Em um espaço de trabalho no Cloud, o Pathrule também adiciona algumas por conta própria: notas curtas sobre tecnologias na raiz do espaço de trabalho, como "TypeScript project" ou "Docker containerization", identificadas a partir dos nomes de arquivos na primeira vez que um agente pede contexto aprofundado. São memórias comuns, então você pode editá-las ou apagá-las como qualquer outra.

Regras

Uma regra é uma restrição que o assistente precisa seguir dentro de um escopo.

Regras têm:

• Um tipo de escopo. folder significa que a regra vale dentro de um diretório. file_type significa que ela vale para um glob de arquivos como *.tsx. project significa que ela vale em todo o espaço de trabalho.
• Uma prioridade. high para as restrições mais importantes, medium para orientações gerais, low para preferências de estilo. A prioridade controla o destaque com que uma regra aparece, não se ela bloqueia.
• Um modo de aplicação. Regras advisory acompanham o trabalho como contexto, e o assistente decide como aplicá-las. Uma regra strict carrega uma restrição executável aprovada por uma pessoa e pode bloquear uma alteração correspondente antes que ela seja aplicada, em clientes cujos hooks rodam antes de uma chamada de ferramenta.
• Um corpo. Uma lista curta de itens no imperativo funciona melhor.

Regras de prioridade mais alta aparecem primeiro quando o escopo delas corresponde ao caminho atual. Regras de prioridade mais baixa aparecem quando provavelmente vão ajudar.

Skills

Uma skill é um procedimento nomeado que o assistente pode invocar em vez de deduzir os passos de novo a cada vez.

Exemplos:

• replay-stripe-webhook: um checklist com o comando exato do CLI e os passos de segurança antes de executá-lo.
• regenerate-fixtures: o caminho do script, as entradas e a saída esperada.
• release-check: o checklist de pré-release que a equipe sempre quer que o assistente percorra.

Skills podem ser encontradas pelo nome. O assistente pode pedir ao Pathrule as skills vinculadas ao caminho atual e escolher a que corresponde à tarefa.

Escopo por caminho

Toda memória, regra e skill fica em um caminho de nó. O caminho define onde ela aparece.

• Uma memória em /apps/web é relevante para qualquer trabalho dentro de apps/web.
• Uma memória em / é relevante em todo lugar.
• Uma skill em /services/billing é oferecida ao assistente quando o trabalho acontece dentro do serviço de billing.

É o escopo por caminho que mantém pequena a janela de contexto do assistente. Um ajuste de UI em apps/web/dashboard não precisa ver as regras sobre migrations de banco de dados.

Prioridade e aplicação

Prioridade e aplicação são duas configurações independentes.

• Prioridade (high, medium, low) define o destaque com que uma regra aparece. Use high com moderação, para as restrições mais importantes.
• Aplicação (advisory ou strict) define o que acontece quando há uma violação. Regras orientativas aparecem como contexto e o assistente decide como aplicá-las, e toda regra nova começa como orientativa. Um agente pode propor uma restrição executável para uma regra; ela fica armazenada como proposta e não é aplicada. Depois que uma pessoa a aprova, o hook local verifica uma edição correspondente antes que ela seja aplicada, pode bloquear a alteração e mostra a regra como motivo.

O Pathrule CLI e a extensão do VS Code registram os hooks disponíveis para Claude Code, Codex, Cursor e GitHub Copilot, e o bloqueio vale onde o hook do cliente consegue interromper uma chamada de ferramenta. O Windsurf não tem hooks, e o Remote MCP não instala nenhum: ambos recebem as regras como contexto, sem nenhum evento de bloqueio do Pathrule antes da escrita.

Onde isso se encaixa

• O que o Pathrule calcula trata da camada derivada que fica em torno desses três tipos escritos.
• Como os hooks funcionam descreve como o runtime escolhe o recorte que será enviado.
• Visão geral do MCP lista as ferramentas que o assistente usa para ler e escrever nós.
• Início rápido é o jeito mais rápido de ver esse modelo em ação.