hookify-rules

Escrevendo Regras Hookify

Visão Geral

As regras Hookify são arquivos markdown com frontmatter YAML que definem padrões a serem observados e mensagens a serem exibidas quando esses padrões coincidem. As regras são armazenadas em arquivos .claude/hookify.{nome-da-regra}.local.md.

Formato do Arquivo de Regra

Estrutura Básica

---
name: identificador-da-regra
enabled: true
event: bash|file|stop|prompt|all
pattern: expressão-regex-aqui
---

Mensagem a ser mostrada ao Claude quando esta regra for acionada.
Pode incluir formatação markdown, avisos, sugestões, etc.

Campos do Frontmatter

Campo	Obrigatório	Valores	Descrição
name	Sim	string kebab-case	Identificador único (verbo-primeiro: warn-, block-, require-*)
enabled	Sim	true/false	Ativar/desativar sem excluir
event	Sim	bash/file/stop/prompt/all	Qual evento do hook aciona esta regra
action	Não	warn/block	warn (padrão) exibe mensagem; block impede a operação
pattern	Sim*	string regex	Padrão para correspondência (*ou use conditions para regras complexas)

Formato Avançado (Múltiplas Condições)

---
name: warn-env-api-keys
enabled: true
event: file
conditions:
  - field: file_path
    operator: regex_match
    pattern: \.env$
  - field: new_text
    operator: contains
    pattern: API_KEY
---

Você está adicionando uma chave de API a um arquivo .env. Certifique-se de que este arquivo está no .gitignore!

Campos de condição por evento:

• bash: command
• file: file_path, new_text, old_text, content
• prompt: user_prompt

Operadores: regex_match, contains, equals, not_contains, starts_with, ends_with

Todas as condições devem corresponder para que a regra seja acionada.

Guia de Tipos de Evento

Eventos bash

Correspondência a padrões de comando Bash:

• Comandos perigosos: rm\s+-rf, dd\s+if=, mkfs
• Escalação de privilégio: sudo\s+, su\s+
• Problemas de permissão: chmod\s+777

Eventos file

Correspondência a operações de Edição/Escrita/MultiEdição:

• Código de depuração: console\.log\(, debugger
• Riscos de segurança: eval\(, innerHTML\s*=
• Arquivos sensíveis: \.env$, credentials, \.pem$

Eventos stop

Verificações e lembretes de conclusão. O padrão .* corresponde sempre.

Eventos prompt

Correspondência ao conteúdo do prompt do usuário para imposição de fluxo de trabalho.

Dicas para Escrever Padrões

Noções Básicas de Regex

• Escape caracteres especiais: . para \., ( para \(
• \s espaço em branco, \d dígito, \w caractere de palavra
• + um ou mais, * zero ou mais, ? opcional
• | operador OU

Armadilhas Comuns

• Muito amplo: log corresponde a "login", "dialog" — use console\.log\(
• Muito específico: rm -rf /tmp — use rm\s+-rf
• Escape no YAML: Use padrões sem aspas; strings entre aspas precisam de \\s

Testes

python3 -c "import re; print(re.search(r'seu_padrao', 'texto de teste'))"

Organização de Arquivos

• Localização: Diretório .claude/ na raiz do projeto
• Nomenclatura: .claude/hookify.{nome-descritivo}.local.md
• Gitignore: Adicione .claude/*.local.md ao .gitignore

Comandos

• /hookify [descrição] - Criar novas regras (analisa automaticamente a conversa se nenhum argumento for fornecido)
• /hookify-list - Visualizar todas as regras em formato de tabela
• /hookify-configure - Ativar/desativar regras interativamente
• /hookify-help - Documentação completa

Referência Rápida

Regra mínima funcional:

---
name: minha-regra
enabled: true
event: bash
pattern: comando_perigoso
---
Mensagem de aviso aqui