Promotor de Regras
Visão Geral
Regras do CLAUDE.md são conselhos: Claude pode racionalizá-las. Um hook é uma imposição (enforcement). Esta skill lê o CLAUDE.md do projeto, identifica as regras que um hook pode realmente impor, escreve-as em um arquivo de regras reforçado por um motor pequeno e testado, prova que cada regra bloqueia uma violação, e instala os hooks após o usuário confirmar. Ela é executada apenas quando o usuário solicita. Hooks são barreiras de proteção, não uma fronteira de segurança: uma solução alternativa determinada (um script auxiliar, sh -c) pode contornar um padrão. Informe isso.
Arquivos (no diretório base desta skill, mostrado quando a skill carrega)
scripts/rule_hook.py: o motor. Copie para.claude/hooks/rule_hook.pyno projeto.python rule_hook.py selftestprova cada regra;checké o ponto de entrada do hook.scripts/settings_merge.py:launcherescolhe um comando Python que funcione;planmostra o diff das configurações;applyescreve.
Execute ambos com um comando Python 3 que funcione nesta máquina (tente python3, python, py -3). Coloque os caminhos entre aspas.
Processo
-
Ler. Encontre
CLAUDE.md,.claude/CLAUDE.mdeCLAUDE.local.mdno projeto. Liste cada regra com seu arquivo e linha. Se não houver nenhuma, informe e pare. -
Classificar cada regra exatamente em um dos:
- um tipo de motor (abaixo) com parâmetros concretos;
taste(gosto), com uma razão de uma linha;needs input(precisa de entrada), com a pergunta específica a fazer (por exemplo "qual comando executa seus testes?").
Uma regra é aplicável apenas se nomeia ferramentas, caminhos, comandos ou padrões de texto concretos, e uma violação é detectável a partir de uma única chamada de ferramenta ou do código de saída de um comando no final do turno. Quando estiver em dúvida, marque como
needs inpute pergunte; nunca adivinhe um padrão para uma regra vaga. Nunca invente um tipo de regra. -
Revisar. Mostre uma tabela: regra, tipo, padrão ou comando, uma violação de exemplo, uma aprovação de exemplo, e o risco de falso positivo. Mostre cada comando
stop_checkliteralmente. Peça ao usuário para remover ou ajustar linhas. Não escreva nada ainda. -
Provar. Após aprovação, crie
.claude/hooks/e copiescripts/rule_hook.pypara lá, escreva.claude/rules.json, então executepython .claude/hooks/rule_hook.py selftesta partir da raiz do projeto. Mostre a saída. Uma regra cuja prova falha não é instalada: corrija seu padrão ou remova-a, e informe qual. -
Instalar. Execute
settings_merge.py launcher --script .claude/hooks/rule_hook.py, depoissettings_merge.py plan --settings .claude/settings.json --launcher "<launcher>" [--pretool] [--stop](--pretoolse existirem regras de caminho, comando ou conteúdo;--stopse existirem regrasstop_check). Mostre o diff e peça um sim. Apenas após um sim, execute o mesmo comando comapply. Se reportar JSON de configurações inválido ou chave duplicada, pare e informe o usuário; não edite o arquivo manualmente. O auxiliar remove apenas suas próprias entradasrule_hook.pye deixa todos os outros hooks intactos. Se a verificação de ponta a ponta abaixo mostrar que o hook não disparou emboraselftestpasse edisableAllHooksnão esteja definido, algumas versões do Claude Code não possuemargsno formato exec: reexecuteplaneapplycom--shell-form. -
Verificar de ponta a ponta. Se você puder executar
claude -pno projeto, teste com uma regraprotected_pathoubanned_contentcontra um arquivo descartável (por exemplo, peça para editartmp-rule-check.txtsob um glob protegido), nunca com umblocked_commandoustop_checkque realmente executaria algo, e desfaça qualquer alteração depois. VerifiquedisableAllHooksnas configurações do projeto, local e do usuário antes de concluir qualquer coisa. Confirme que a saída mostra a mensagem do blocoRule <id>:, e mostre-a. Se você não puder executar uma sessão aninhada, informe e diga que a instalação é verificada apenas porselftest. -
Relatar. Liste as regras promovidas, as regras ignoradas com motivos, e uma limitação: Claude ainda pode editar
.claude/rules.json,.claude/hooks/e.claude/settings.json. Ofereça-se para adicionar uma regraprotected_pathpara eles, e informe que isso também bloqueia a reexecução desta skill até que a regra seja desabilitada. Depois, informe como desativar: defina"enabled": falseem uma regra no.claude/rules.json, ou remova as entradasrule_hook.pyde.claude/settings.json.
Nunca escreva rules.json, arquivos de hook ou settings.json antes que o usuário tenha revisado a tabela. Nunca escreva settings.json antes de mostrar o diff e obter um sim.
Se o usuário adicionar uma regra ou alterar um padrão após a tabela, ou se você precisar alterar um padrão porque ele é inválido ou sua prova falha, mostre essa linha nova ou alterada (padrão, violação de exemplo, aprovação de exemplo, risco) e aguarde um sim antes de escrever qualquer coisa. Uma aprovação dada anteriormente não cobre um padrão diferente, e nunca substitua um padrão que o usuário não viu.
Tipos de regra
Cada regra tem id (kebab-case), source (CLAUDE.md:14), text (a regra original), message (mostrada para Claude quando bloqueado), type, os campos abaixo, e um proof com um payload de violation e um pass.
protected_path: sem edições em arquivos correspondentes. Globs correspondem ao caminho inteiro relativo ao projeto; use **/nome para qualquer profundidade.
{"id": "sem-edicoes-em-migrations", "source": "CLAUDE.md:3", "text": "Nunca edite nada dentro de migrations/",
"type": "protected_path", "globs": ["**/migrations/**"], "allow_globs": [],
"message": "Migrations são geradas. Crie uma nova migration.",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "app/migrations/0001_initial.py", "old_string": "a", "new_string": "b"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": {"file_path": "app/models.py", "old_string": "a", "new_string": "b"}}}}
blocked_command: Comandos Bash que correspondem a uma expressão regular, testados contra cada segmento de um comando composto. Use except_patterns para variantes seguras; uma exceção isenta o segmento inteiro, então torne-a específica.
{"id": "sem-push-forcado", "source": "CLAUDE.md:4", "text": "Nunca execute git push --force",
"type": "blocked_command", "patterns": ["\\bgit\\s+push\\b.*(?:--force\\b|\\s-[A-Za-z]*f[A-Za-z]*\\b|\\s\\+\\w)"], "except_patterns": ["--force-with-lease"],
"message": "Pushes forçados não são permitidos.",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": "git push --force origin main"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Bash", "tool_input": {"command": "git push origin feature"}}}}
banned_content: expressões regulares que não devem aparecer no novo texto sendo escrito (Edit, Write, MultiEdit, NotebookEdit), opcionalmente limitadas por globs de arquivo. O texto antigo nunca é inspecionado.
{"id": "sem-console-log", "source": "CLAUDE.md:5", "text": "Sem console.log( em src/",
"type": "banned_content", "patterns": ["console\\.log\\("], "globs": ["src/**"],
"message": "Use o logger, não console.log.",
"proof": {"violation": {"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "src/a.js", "content": "console.log(1)"}},
"pass": {"hook_event_name": "PreToolUse", "tool_name": "Write", "tool_input": {"file_path": "src/a.js", "content": "logger.info(1)"}}}}
stop_check: um comando que deve ter sucesso antes que Claude possa parar. Ele bloqueia a parada quando o comando sai com código diferente de zero. when_changed_globs limita a turnos que alteraram arquivos correspondentes (apenas alterações não commitadas: omita se Claude tende a commitar antes de parar). A prova usa simulate_exit (o selftest não executa o comando real).
{"id": "testes-passam", "source": "CLAUDE.md:6", "text": "Execute npm test antes de terminar",
"type": "stop_check", "command": "npm test", "timeout_seconds": 240, "when_changed_globs": ["src/**", "tests/**"],
"message": "Os testes devem passar antes de parar.",
"proof": {"violation": {"hook_event_name": "Stop", "simulate_exit": 1}, "pass": {"hook_event_name": "Stop", "simulate_exit": 0}}}
O arquivo é {"version": 1, "rules": [ ... ]}. Payloads de ferramentas: Bash usa tool_input.command; Edit usa file_path, old_string, new_string; Write usa file_path, content.
O que é aplicável (guia de classificação)
- Aplicável: "nunca edite X/", "não toque em .env", "nunca execute Y", "não use Z em arquivos sob W", "execute T antes de terminar".
- Gosto: "prefira funções pequenas", "escreva mensagens de commit claras", "mantenha a UI acessível", "favoreça clareza". Nenhum padrão pode decidir isso.
- Precisa de entrada: "tome cuidado com o banco de dados", "certifique-se de que os testes passam" (qual comando?), "evite código legado" (quais caminhos?). Pergunte; não adivinhe.
- Globs suportam apenas
*,**e?, relativos ao projeto (sem[ab],{a,b},./inicial ou/); o motor recusa qualquer outra coisa.timeout_secondsé no máximo 280, eenableddeve sertrueoufalse. - Prefira padrões estreitos. Indique o risco de falso positivo para cada regra (por exemplo, um padrão
maintambém corresponde a um branch chamadomain-menu) e adicioneallow_globsouexcept_patternsquando isso importar.
Tom
Conciso e factual. Isso é trabalho de configuração, não uma palestra sobre regras.
Erros Comuns
- Escrever qualquer arquivo, ou configurações, antes que o usuário tenha revisado a tabela.
- Escrever
settings.jsonsem mostrar o diff e obter um sim. - Instalar uma regra que o usuário não viu como uma linha de tabela, ou substituir silenciosamente o padrão solicitado pelo usuário.
- Instalar uma regra cuja prova não passou.
- Promover uma regra de gosto, ou adivinhar um padrão para uma regra vaga.
- Inventar um tipo de regra que o motor não possui.
- Deixar de fora o risco de falso positivo, ou a observação "barreira de proteção, não fronteira de segurança".
- Editar um
settings.jsoninválido manualmente em vez de parar. - Afirmar um bloqueio de ponta a ponta que você não observou realmente.