Como escrever regras

Uma regra é uma restrição que o assistente deve seguir dentro de um escopo. As regras são o tipo de conteúdo mais forte do Pathrule: elas chegam como requisitos, não como contexto de fundo, e uma regra que carrega uma restrição executável aprovada pode barrar uma alteração correspondente antes que ela seja aplicada.

Esta página explica quando escrever uma regra, como escolher escopo e prioridade, o que significa aplicação e quais padrões evitar.

Quando escrever uma regra

Use uma regra quando houver algo que o assistente não pode fazer, ou algo que ele sempre precisa fazer, em uma parte específica da base de código.

• "Nunca use a service role key em código de navegador."
• "Todos os valores monetários são armazenados como inteiros em centavos. Nunca use floats."
• "Migrations devem rodar antes da alteração de código correspondente. Sem exceções."
• "Arquivos JSX em apps/web usam apenas classes do Tailwind. Nada de CSS modules, nada de estilos inline."

Se a resposta for "depende da situação, o assistente deve pensar a respeito", isso é uma memória, não uma regra. Regras são para o que não é negociável.

Tipos de escopo

Toda regra tem um tipo de escopo que define a quais caminhos ou arquivos ela se aplica.

• folder. Aplica-se a uma subárvore de diretórios. Ideal para regras de uma área específica: tudo o que fica em apps/api/auth, tudo o que fica em services/billing.
• file_type. Aplica-se a arquivos que correspondem a um glob como *.tsx ou **/*.test.ts. Ideal para preocupações transversais ligadas a um tipo de arquivo, e não a um diretório.
• project. Aplica-se a todo o espaço de trabalho. Use com moderação. Uma regra de projeto acompanha todos os prompts.

O escopo e o caminho do nó ao qual a regra está vinculada definem, juntos, o que o assistente vê. Uma regra folder vinculada em /apps/web cobre tudo o que está em apps/web.

Níveis de prioridade

A prioridade define com que insistência a regra aparece. Dentro de um escopo correspondente, as regras de prioridade mais alta são consideradas primeiro.

• high. Para coisas que causam bugs, regressões de segurança ou problemas de conformidade se forem violadas.
• medium. O padrão. Use para o que vale "quase sempre, mas não é crítico".
• low. Estilístico. Aparece quando há espaço e o assunto é pertinente. Use para gosto e convenção.

Prioridade alta é um orçamento. Se metade das suas regras é de prioridade alta, nenhuma delas é. Escolha as que realmente não podem ser violadas.

Aplicação: advisory e strict

A aplicação é uma configuração separada da prioridade. A prioridade define com que força uma regra aparece; a aplicação define o que acontece quando há uma violação.

• advisory. A regra é contexto. O assistente a pondera e decide como aplicá-la. As regras que você escreve pelo CLI ou pelo VS Code, e as regras que um assistente escreve, são advisory.
• strict. Uma regra se torna strict quando carrega uma restrição executável aprovada por uma pessoa: a forma exata do que é proibido, como um import, um identificador ou um local. Nesse caso, o hook pré-ferramenta pode bloquear uma edição ou escrita de arquivo que corresponda a ela antes que a alteração seja aplicada, e devolve a regra e a forma de corrigir como motivo. Um assistente pode anexar uma restrição proposta ao escrever ou atualizar uma regra (pathrule_write_rule, pathrule_update_rule), mas a proposta é armazenada como proposta e não bloqueia nada até que uma pessoa a aprove; um assistente nunca pode aprovar a própria proposta. Veja Regras como guardrails.

Reescrever uma regra mantém a aplicação honesta. Uma restrição aprovada fica ligada à frase da regra contra a qual ela foi validada. Se você reescrever a regra e essa frase deixar de existir, a restrição para de ser aplicada sozinha, então uma regra nunca continua bloqueando por um motivo que ela não declara mais. Editar outras partes da regra, ou acrescentar um parágrafo, mantém ativa uma restrição que não foi alterada.

O bloqueio depende do cliente. O Pathrule CLI instala hooks de ferramenta para Claude Code, Codex, Cursor e GitHub Copilot, e um bloqueio vale onde o hook pré-ferramenta do cliente respeita a decisão. O Windsurf não tem hooks, e o Remote MCP não instala nenhum, então nesses casos as regras chegam apenas como contexto. A entrega, por si só, não aplica nada.

Estrutura

Uma regra tem um nome e um corpo. Mantenha o corpo no imperativo e curto.

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.

No terminal, a mesma regra é um único comando. Sem --body, o CLI abre o seu editor para o corpo.

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

No VS Code, use New Rule…; um assistente escreve regras com pathrule_write_rule.

O formato que funciona melhor na prática é uma restrição por regra, com um corpo curto em tópicos. Regras longas em prosa acabam sendo lidas por cima, tanto por pessoas quanto por assistentes.

Reutilizável, não duplicada

Uma regra fica em um caminho e cobre tudo o que está abaixo dele, então uma única regra basta para uma subárvore inteira. Se a mesma restrição vale para duas pastas distantes, coloque-a no caminho comum mais próximo das duas, ou use um escopo file_type com um glob, em vez de copiar e colar o texto em duas regras. Uma regra significa uma única edição quando a restrição mudar.

O Pathrule ajuda nisso: uma nova regra cujo nome coincide com o de uma regra já existente no espaço de trabalho é recusada por padrão, e a escrita informa qual regra já existe. Você pode contornar isso de propósito (allow_duplicate via MCP) depois de verificar a regra existente. Para mudar uma regra de lugar, mova-a para outro caminho (Move… no VS Code, ou pathrule_update_rule com move_to_path).

Versionamento e edições simultâneas

As regras carregam um token de versão, assim como as memórias. Duas pessoas da equipe editando a mesma regra ao mesmo tempo geram um conflito limpo, em vez de uma sobrescrever a outra. No VS Code, o conflito oferece as mesmas opções que para uma memória: Reload, Copy My Version & Reload ou Keep Mine (Overwrite).

Como as regras chegam ao assistente

• As regras em um escopo correspondente são priorizadas pela prioridade e pela relevância para a tarefa. As mais relevantes chegam com o corpo completo; as demais são citadas pelo nome, para que o assistente saiba que existem e possa ler qualquer uma na íntegra com pathrule_read_rule.
• Uma regra strict sempre chega completa onde se aplica, porque só o nome não consegue explicar um bloqueio.
• As regras também são compiladas nos arquivos de instruções que os seus clientes leem (por exemplo, CLAUDE.md para o Claude Code e AGENTS.md para o Codex), então um cliente sem hook de prompt também parte delas.

Se uma regra pode bloquear uma alteração, em vez de apenas informar o assistente, é definido pelo modo de aplicação (advisory ou strict), não pela prioridade.

Antipadrões

• Prioridade alta para tudo. Escolha as regras que realmente importam. O resto deve ficar em medium.
• Regras que parecem memórias. "Costumamos preferir X" é uma memória. "Nunca faça Y" é uma regra.
• Regras que se sobrepõem. Duas regras de prioridade alta com redação conflitante são piores do que uma regra clara.
• Escopo de projeto usado por padrão. A maioria das regras pertence a uma pasta. Suba uma regra para project só se ela realmente se aplicar a tudo.

Criação no modo local e no Cloud

Os exemplos de add no terminal desta página são para um espaço de trabalho Cloud. No modo local, crie e edite entradas no Local Console, no VS Code ou pelo MCP local; os comandos de conhecimento do CLI listam, leem e buscam essas entradas.

O que ler em seguida

• Como escrever memórias para fatos e decisões que não são restrições.
• Como escrever skills para procedimentos reutilizáveis que o assistente pode invocar.
• Como os hooks funcionam para entender como o runtime decide quais regras exibir.