Communitygithub.com

Promotor de Reglas de CLAUDE.md

Convierte las reglas de CLAUDE.md en ganchos (hooks) ejecutables que Claude no puede ignorar. Útil cuando Claude ignora sistemáticamente una regla o cuando deseas reforzar reglas específicas.

¿Qué es Promotor de Reglas de CLAUDE.md?

Esta skill automatiza la conversión de reglas declarativas de CLAUDE.md en ganchos de enforcement para Claude Code. Analiza el proyecto, clasifica cada regla como enforceable (protegida por gancho), de gusto (no enforceable), o que necesita entrada adicional del usuario. Luego escribe las reglas en un archivo JSON y las prueba automáticamente con el motor rule_hook.py, que verifica cada regla mediante un test unitario (selftest). Finalmente instala los ganchos en la configuración de Claude Code (settings.json). Soporta cuatro tipos de reglas: protected_path (protege archivos de ediciones), blocked_command (bloquea comandos de bash específicos), banned_content (prohíbe patrones de contenido) y stop_check (verifica que un comando pase antes de detener la sesión). La skill es útil para equipos que quieren que Claude respete estrictamente políticas como 'no editar migraciones' o 'ejecutar pruebas antes de terminar'.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NarenDawar/narens-claude-skills/tree/HEAD/plugins/rule-promoter/skills/rule-promoter

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Promotor de Reglas de CLAUDE.md?

Descripción general

Las reglas de CLAUDE.md son consejos: Claude puede racionalizar y pasarlas por alto. Un gancho (hook) es un mecanismo de enforcement. Esta skill lee el proyecto CLAUDE.md, selecciona las reglas que un gancho puede realmente enforce, las escribe en un archivo de reglas enforcement por un motor pequeño y probado, demuestra que cada regla bloquea una violación, e instala los ganchos después de que el usuario confirme. Solo se ejecuta cuando el usuario lo solicita. Los ganchos son barandillas de contención, no una frontera de seguridad: una solución determinada (un script helper, sh -c) puede evadir un patrón. Así lo indica.

Archivos (en el directorio base de esta skill, mostrados cuando la skill carga)

  • scripts/rule_hook.py: el motor. Se copia a .claude/hooks/rule_hook.py en el proyecto. python rule_hook.py selftest demuestra cada regla; check es el punto de entrada del gancho.
  • scripts/settings_merge.py: launcher elige un comando de Python que funcione; plan muestra las diferencias de configuración; apply las escribe.

Ejecuta ambos con un comando de Python 3 que funcione en esta máquina (prueba python3, python, py -3). Entrecomilla las rutas.

Proceso

  1. Leer. Encuentra CLAUDE.md, .claude/CLAUDE.md y CLAUDE.local.md en el proyecto. Lista cada regla con su archivo y línea. Si no hay ninguna, indícalo y detente.

  2. Clasificar cada regla en exactamente una de:

    • un tipo de motor (abajo) con parámetros concretos;
    • taste, con una razón de una línea;
    • needs input, con la pregunta específica a hacer (por ejemplo "¿qué comando ejecuta tus pruebas?").

    Una regla es enforceable solo si nombra herramientas, rutas, comandos o patrones de texto concretos, y una violación es detectable desde una llamada a una herramienta o desde el código de salida de un comando al final del turno. Cuando haya dudas, márcala como needs input y pregunta; nunca adivines un patrón para una regla vaga. Nunca inventes un tipo de regla.

  3. Revisar. Muestra una tabla: regla, tipo, patrón o comando, una violación de muestra, un pase de muestra y el riesgo de falso positivo. Muestra cada comando stop_check textualmente. Pide al usuario que elimine o ajuste filas. No escribas nada todavía.

  4. Demostrar. Después de la aprobación, crea .claude/hooks/ y copia scripts/rule_hook.py allí, escribe .claude/rules.json, luego ejecuta python .claude/hooks/rule_hook.py selftest desde la raíz del proyecto. Muestra la salida. Una regla cuya demostración falla no se instala: corrige su patrón o elimínala, e indica cuál.

  5. Instalar. Ejecuta settings_merge.py launcher --script .claude/hooks/rule_hook.py, luego settings_merge.py plan --settings .claude/settings.json --launcher "<launcher>" [--pretool] [--stop] (--pretool si existe alguna regla de ruta, comando o contenido; --stop si existe alguna regla stop_check). Muestra la diferencia y pide confirmación. Solo después de una confirmación, ejecuta el mismo comando con apply. Si reporta JSON de configuración inválido o una clave duplicada, detente e informa al usuario; no edites el archivo manualmente. El helper elimina solo sus propias entradas de rule_hook.py y deja los demás ganchos intactos. Si la verificación de extremo a extremo muestra que el gancho no se disparó aunque selftest pase y disableAllHooks no esté configurado, algunas versiones de Claude Code carecen de args de formulario ejecutable: vuelve a ejecutar plan y apply con --shell-form.

  6. Verificar extremo a extremo. Si puedes ejecutar claude -p en el proyecto, prueba con una regla protected_path o banned_content contra un archivo temporal (por ejemplo, pídele que edite tmp-rule-check.txt bajo un glob protegido), nunca con una regla blocked_command o stop_check que realmente ejecutaría algo, y deshaz cualquier cambio después. Comprueba disableAllHooks en la configuración del proyecto, local y de usuario antes de concluir algo. Confirma que la salida muestra el bloque de mensaje Rule <id>: y muéstralo. Si no puedes ejecutar una sesión anidada, indícalo y di que la instalación está verificada solo con selftest.

  7. Informar. Lista las reglas promovidas, las reglas omitidas con razones y una limitación: Claude aún puede editar .claude/rules.json, .claude/hooks/ y .claude/settings.json. Ofrece agregar una regla protected_path para ellos y di que también bloquea volver a ejecutar esta skill hasta que la regla se deshabilite. Luego di cómo desactivar: establece "enabled": false en una regla en .claude/rules.json, o elimina las entradas de rule_hook.py de .claude/settings.json.

Nunca escribas rules.json, archivos de gancho o settings.json antes de que el usuario haya revisado la tabla. Nunca escribas settings.json antes de mostrar la diferencia y obtener una confirmación.

Si el usuario agrega una regla o cambia un patrón después de la tabla, o tienes que cambiar un patrón porque no es válido o su demostración falla, muestra esa fila nueva o modificada (patrón, violación de muestra, pase de muestra, riesgo) y espera una confirmación antes de escribir algo. Una aprobación dada anteriormente no cubre un patrón diferente, y nunca sustituyas un patrón que el usuario no vio.

Tipos de regla

Cada regla tiene id (en kebab-case), source (CLAUDE.md:14), text (la regla original), message (mostrado a Claude cuando está bloqueado), type, los campos abajo y un proof con un payload de violation y pass.

protected_path: no se permiten ediciones en archivos que coinciden con los patrones. Los patrones coinciden con la ruta completa relativa al proyecto; usa **/name para cualquier profundidad.

{"id": "sin-ediciones-migraciones", "source": "CLAUDE.md:3", "text": "Nunca edites nada dentro de migrations/",
 "type": "protected_path", "globs": ["**/migrations/**"], "allow_globs": [],
 "message": "Las migraciones se generan. Crea una nueva migración en su lugar.",
 "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 de Bash que coinciden con una expresión regular, probados contra cada segmento de un comando compuesto. Usa except_patterns para variantes seguras; una excepción exime al segmento completo, así que hazla específica.

{"id": "sin-push-forzado", "source": "CLAUDE.md:4", "text": "Nunca ejecutes 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": "No se permiten pushes forzados.",
 "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: expresiones regulares que no deben aparecer en el texto nuevo que se escribe (Edit, Write, MultiEdit, NotebookEdit), opcionalmente limitado por globs de archivos. El texto antiguo nunca se inspecciona.

{"id": "sin-console-log", "source": "CLAUDE.md:5", "text": "No console.log( en src/",
 "type": "banned_content", "patterns": ["console\\.log\\("], "globs": ["src/**"],
 "message": "Usa el logger, no 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: un comando que debe tener éxito antes de que Claude pueda detenerse. Bloquea la detención cuando el comando sale con un código no cero. when_changed_globs limita a los turnos que cambiaron archivos coincidentes (solo cambios no confirmados: omítelo si Claude tiende a confirmar antes de detenerse). La demostración usa simulate_exit (selftest no ejecuta el comando real).

{"id": "pruebas-pasan", "source": "CLAUDE.md:6", "text": "Ejecuta npm test antes de terminar",
 "type": "stop_check", "command": "npm test", "timeout_seconds": 240, "when_changed_globs": ["src/**", "tests/**"],
 "message": "Las pruebas deben pasar antes de que te detengas.",
 "proof": {"violation": {"hook_event_name": "Stop", "simulate_exit": 1}, "pass": {"hook_event_name": "Stop", "simulate_exit": 0}}}

El archivo es {"version": 1, "rules": [ ... ]}. Los payloads de las herramientas: Bash usa tool_input.command; Edit usa file_path, old_string, new_string; Write usa file_path, content.

Qué es enforceable (guía de clasificación)

  • Enforceable: "nunca edites X/", "no toques .env", "nunca ejecutes Y", "no uses Z en archivos bajo W", "ejecuta T antes de terminar".
  • Taste: "prefiere funciones pequeñas", "escribe mensajes de confirmación claros", "mantén la UI accesible", "favorece la claridad". Ningún patrón puede decidir estos.
  • Needs input: "ten cuidado con la base de datos", "asegúrate de que las pruebas pasen" (¿qué comando?), "evita código heredado" (¿qué rutas?). Pregunta; no adivines.
  • Los patrones soportan solo *, ** y ?, relativos al proyecto (no [ab], {a,b}, ./ o / al inicio); el motor rechaza cualquier otra cosa. timeout_seconds es como máximo 280, y enabled debe ser true o false.
  • Prefiere patrones estrechos. Indica el riesgo de falso positivo para cada regla (por ejemplo, un patrón main también coincide con una rama llamada main-menu) y agrega allow_globs o except_patterns cuando eso importe.

Tono

Breve y objetivo. Esto es trabajo de configuración, no una lección sobre reglas.

Errores comunes

  • Escribir cualquier archivo, o configuraciones, antes de que el usuario haya revisado la tabla.
  • Escribir settings.json sin mostrar la diferencia y obtener una confirmación.
  • Instalar una regla que el usuario no ha visto como fila de tabla, o reemplazar silenciosamente el patrón que el usuario pidió.
  • Instalar una regla cuya demostración no pasó.
  • Promover una regla de gusto, o adivinar un patrón para una regla vaga.
  • Inventar un tipo de regla que el motor no tiene.
  • Omitir el riesgo de falso positivo, o la advertencia de "barandilla de contención, no una frontera de seguridad".
  • Editar un settings.json inválido manualmente en lugar de detenerse.
  • Afirmar un bloqueo de extremo a extremo que no observaste realmente.

Skills relacionados