Regras como guardrails

No Pathrule, uma regra não é uma anotação que o assistente lê depois. Ela é um guardrail que chega antes de o assistente agir. A maior parte da documentação conta o que deu errado depois que foi para produção. Um guardrail pode barrar a mudança antes que ela seja aplicada.

Esta página explica a diferença entre o contexto que informa um turno e uma regra que pode bloqueá-lo. Para entender como os hooks entregam contexto, leia primeiro Como os hooks funcionam. Aqui o assunto é o que uma regra estrita faz depois que esse contexto já está disponível.

No pull, o assistente pede. No push, o contexto chega.

O modelo antigo é pull. O assistente precisa se lembrar de pedir suas convenções, chamar uma ferramenta e ler o resultado antes de editar qualquer coisa. Se esquecer, edita às cegas, e você só descobre o problema na revisão.

O modelo de hooks é push. No Claude Code e no Codex, o contexto chega sem que o assistente peça, quando você envia um prompt e logo antes de o assistente usar uma ferramenta. O Cursor e o GitHub Copilot não têm hook de envio de prompt, então neles o hook de início de sessão leva o bootstrap e os hooks de ferramenta levam as regras do caminho em questão. De qualquer forma, quando o assistente está prestes a gravar um arquivo, as regras vinculadas àquele caminho já estão diante dele. O Windsurf não tem hooks: ele lê o arquivo de regras do Pathrule e pede mais ao servidor MCP local, então no Windsurf as regras informam, mas não bloqueiam.

Dois níveis: consultivo e bloqueante

Nem toda regra deve interromper o assistente. O Pathrule trata as regras em dois níveis.

• Regras consultivas seguem junto como contexto. Elas aparecem ao lado do arquivo que o assistente vai alterar, com a respectiva prioridade, para que o assistente as leve em conta. Elas não impedem nada. A maioria das regras é consultiva, em qualquer prioridade.
• Regras estritas podem bloquear. Uma regra se torna estrita quando tem um padrão de bloqueio aprovado por uma pessoa: uma forma proibida no conteúdo, como um import, um identificador, um nome de classe ou uma declaração CSS, um local proibido para um arquivo, ou ambos. Quando o assistente está prestes a editar ou gravar um arquivo de um jeito que corresponde ao padrão, o hook interrompe a chamada de ferramenta antes que o arquivo seja gravado e devolve o motivo. O assistente lê o motivo e tenta de novo, desta vez dentro da restrição.

Prioridade e bloqueio são independentes. A prioridade (alta, média, baixa) define o destaque com que uma regra aparece e quais regras entram quando falta espaço. Ela não decide o bloqueio: todas as regras estritas do caminho são verificadas, seja qual for a prioridade.

Como uma regra se torna estrita

Um assistente não consegue ativar um padrão de bloqueio sozinho.

1. A regra é escrita primeiro em linguagem comum, por você ou por um assistente a seu pedido.
2. Um assistente pode propor um padrão de bloqueio para ela usando as ferramentas MCP de escrita e atualização de regras. A forma preferida indica o texto proibido exatamente como a regra o escreve, com exemplos reais que precisam ser detectados e quase acertos que não podem ser. O Pathrule constrói o padrão a partir disso e o testa contra os dois conjuntos; se algum falhar, a proposta é recusada com o motivo, em vez de ser enfraquecida.
3. A proposta fica armazenada com a regra e não é aplicada.
4. Só depois que uma pessoa a aprova o hook começa a bloquear, e a correção escrita para ela vira o "faça isto em vez disso" que o assistente vê.

Uma regra também pode ter uma verificação obrigatória: um comando de verificação que precisa ter passado antes de o turno terminar, como a suíte de testes de um pacote. Assim como um padrão de bloqueio, ela é proposta e só é aplicada depois que uma pessoa a aprova. Depois de aprovada, no Claude Code e no Codex o hook mantém o turno aberto, com o comando exato a executar, até que ele passe.

O que o assistente vê

Uma edição bloqueada volta com o nome da regra, uma prévia curta da regra, a correção aprovada e uma indicação de onde está a regra completa. Para uma regra chamada "No direct database client in UI components", fica assim:

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.

O Claude Code, o Codex, o Cursor e o GitHub Copilot recebem isso como uma negação da chamada de ferramenta, no formato de hook de cada cliente. O Windsurf não tem hooks, então nada é bloqueado nele. O bloqueio vale para edições e gravações de arquivos; um comando de shell continua recebendo a regra como contexto.

Essa divisão é intencional. Bloquear uma edição de baixo risco desperdiça o turno do assistente e o seu. O bloqueio fica reservado às regras em que uma violação é uma regressão real e alguém aprovou exatamente o que conta como violação.

Antes e depois

Pense em uma regra que diz que segredos nunca entram em arquivos versionados, com um padrão de bloqueio aprovado para o formato de chave usado pelo seu provedor.

O mesmo vale para qualquer regra que já custou caro para a equipe em produção: uma política de acesso a dados que precisa filtrar por usuário, uma convenção de migração, um arquivo gerado que não pode ser editado à mão. A regra deixa de ser um comentário que alguém espera que o assistente tenha lido e passa a ser uma verificação que roda antes de a edição ser aplicada. Um padrão de bloqueio detecta as formas para as quais foi aprovado, então ele complementa a revisão em vez de substituí-la.

Nomes de arquivo trazem a memória certa

Nem sempre é preciso esperar uma chamada de ferramenta. No Claude Code e no Codex, quando seu prompt menciona um arquivo ao qual uma memória vinculada se refere, o hook de prompt pode trazer o conteúdo dessa memória antes de o assistente abrir qualquer coisa. Muitas vezes, mencionar o arquivo em que você está trabalhando já basta para colocar o contexto certo diante do assistente no primeiro turno. Quando mais de uma memória corresponde ao mesmo nome de arquivo, o hook mostra as candidatas em vez de tentar adivinhar.

Falha aberta por design

Um guardrail que trava seu fluxo de trabalho quando quebra é pior do que nenhum guardrail. O Pathrule falha de forma aberta. Se o hook não conseguir avaliar uma regra, der erro ou estourar o tempo limite, ele não bloqueia seu trabalho. A mudança segue em frente. A aplicação é uma rede de segurança, não uma barreira em que você pode ficar preso.

O controle continua com você. Se quiser desligar os hooks por completo, basta um arquivo.

Confira você mesmo

Você não precisa acreditar no comportamento sem ver.

Para saber quais hooks o seu cliente de IA registrou, leia o arquivo de configurações dele. No Claude Code, o Pathrule registra os hooks no projeto:

cat .claude/settings.json

O Cursor usa .cursor/hooks.json, o Codex usa .codex/hooks.json e o GitHub Copilot usa .github/hooks/pathrule.json.

Para desligar todos os hooks do Pathrule na hora (o kill switch), crie um arquivo:

touch ~/.pathrule/kill-hooks

A próxima chamada de ferramenta passa direto, sem nenhuma participação do Pathrule. Remova o arquivo para religar os hooks:

rm ~/.pathrule/kill-hooks

Para confirmar que uma regra está mesmo vinculada a um caminho, execute pathrule rule list na pasta ou abra a área de contexto do Pathrule do assistente no seu editor. A regra aparece com a respectiva prioridade antes de o assistente agir naquele caminho, e uma regra estrita mostra o bloqueio na primeira vez em que uma edição corresponde a ela.

O que ler em seguida

• Como os hooks funcionam, para a mecânica de entrega e o comportamento quando não há contexto.
• Como escrever regras, para saber como criar uma regra que valha a pena aplicar.
• Visão geral do MCP, para o caminho aprofundado que o assistente usa quando o hook não basta.