hookify-rules

Cómo Escribir Reglas de Hookify

Resumen

Las reglas de Hookify son archivos Markdown con metadatos (frontmatter) en YAML que definen patrones a vigilar y mensajes a mostrar cuando esos patrones coinciden. Las reglas se almacenan en archivos .claude/hookify.{nombre-regla}.local.md.

Formato del Archivo de Regla

Estructura Básica

---
name: identificador-regla
enabled: true
event: bash|file|stop|prompt|all
pattern: patron-regex-aqui
---

Mensaje a mostrar a Claude cuando se active esta regla.
Puede incluir formato Markdown, advertencias, sugerencias, etc.

Campos del Frontmatter

Campo	Obligatorio	Valores	Descripción
name	Sí	cadena en kebab-case	Identificador único (verbo primero: warn-, block-, require-*)
enabled	Sí	true/false	Activar/desactivar sin eliminar
event	Sí	bash/file/stop/prompt/all	Qué evento del gancho activa esta regla
action	No	warn/block	warn (por defecto) muestra mensaje; block impide la operación
pattern	Sí*	cadena regex	Patrón a coincidir (*o usar conditions para reglas complejas)

Formato Avanzado (Condiciones Múltiples)

---
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
---

Estás agregando una clave API a un archivo .env. ¡Asegúrate de que este archivo esté en .gitignore!

Campos de condición 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 las condiciones deben cumplirse para que la regla se active.

Guía de Tipos de Evento

Eventos bash

Coincidir con patrones de comandos Bash:

• Comandos peligrosos: rm\s+-rf, dd\s+if=, mkfs
• Elevación de privilegios: sudo\s+, su\s+
• Problemas de permisos: chmod\s+777

Eventos file

Coincidir con operaciones de Edición/Escritura/MultiEdición:

• Código de depuración: console\.log\(, debugger
• Riesgos de seguridad: eval\(, innerHTML\s*=
• Archivos sensibles: \.env$, credentials, \.pem$

Eventos stop

Verificaciones al completar y recordatorios. El patrón .* coincide siempre.

Eventos prompt

Coincidir con contenido del prompt del usuario para reforzar el flujo de trabajo.

Consejos para Escribir Patrones

Conceptos Básicos de Regex

• Escapar caracteres especiales: . a \., ( a \(
• \s espacio en blanco, \d dígito, \w carácter de palabra
• + uno o más, * cero o más, ? opcional
• | operador OR

Errores Comunes

• Demasiado amplio: log coincide con “login”, “dialog” — usa console\.log\(
• Demasiado específico: rm -rf /tmp — usa rm\s+-rf
• Escapado en YAML: Usa patrones sin comillas; las cadenas con comillas necesitan \\s

Pruebas

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

Organización de Archivos

• Ubicación: Directorio .claude/ en la raíz del proyecto
• Nomenclatura: .claude/hookify.{nombre-descriptivo}.local.md
• Gitignore: Agrega .claude/*.local.md al .gitignore

Comandos

• /hookify [descripción] - Crear nuevas reglas (analiza automáticamente la conversación si no hay argumentos)
• /hookify-list - Ver todas las reglas en formato tabla
• /hookify-configure - Activar/desactivar reglas de forma interactiva
• /hookify-help - Documentación completa

Referencia Rápida

Regla mínima funcional:

---
name: mi-regla
enabled: true
event: bash
pattern: comando_peligroso
---
Mensaje de advertencia aquí