¿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.pyen el proyecto.python rule_hook.py selftestdemuestra cada regla;checkes el punto de entrada del gancho.scripts/settings_merge.py:launcherelige un comando de Python que funcione;planmuestra las diferencias de configuración;applylas escribe.
Ejecuta ambos con un comando de Python 3 que funcione en esta máquina (prueba python3, python, py -3). Entrecomilla las rutas.
Proceso
-
Leer. Encuentra
CLAUDE.md,.claude/CLAUDE.mdyCLAUDE.local.mden el proyecto. Lista cada regla con su archivo y línea. Si no hay ninguna, indícalo y detente. -
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 inputy pregunta; nunca adivines un patrón para una regla vaga. Nunca inventes un tipo de regla. -
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_checktextualmente. Pide al usuario que elimine o ajuste filas. No escribas nada todavía. -
Demostrar. Después de la aprobación, crea
.claude/hooks/y copiascripts/rule_hook.pyallí, escribe.claude/rules.json, luego ejecutapython .claude/hooks/rule_hook.py selftestdesde 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. -
Instalar. Ejecuta
settings_merge.py launcher --script .claude/hooks/rule_hook.py, luegosettings_merge.py plan --settings .claude/settings.json --launcher "<launcher>" [--pretool] [--stop](--pretoolsi existe alguna regla de ruta, comando o contenido;--stopsi existe alguna regla stop_check). Muestra la diferencia y pide confirmación. Solo después de una confirmación, ejecuta el mismo comando conapply. 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 derule_hook.pyy deja los demás ganchos intactos. Si la verificación de extremo a extremo muestra que el gancho no se disparó aunqueselftestpase ydisableAllHooksno esté configurado, algunas versiones de Claude Code carecen deargsde formulario ejecutable: vuelve a ejecutarplanyapplycon--shell-form. -
Verificar extremo a extremo. Si puedes ejecutar
claude -pen el proyecto, prueba con una reglaprotected_pathobanned_contentcontra un archivo temporal (por ejemplo, pídele que editetmp-rule-check.txtbajo un glob protegido), nunca con una reglablocked_commandostop_checkque realmente ejecutaría algo, y deshaz cualquier cambio después. CompruebadisableAllHooksen la configuración del proyecto, local y de usuario antes de concluir algo. Confirma que la salida muestra el bloque de mensajeRule <id>:y muéstralo. Si no puedes ejecutar una sesión anidada, indícalo y di que la instalación está verificada solo conselftest. -
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 reglaprotected_pathpara 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": falseen una regla en.claude/rules.json, o elimina las entradas derule_hook.pyde.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_secondses como máximo 280, yenableddebe sertrueofalse. - Prefiere patrones estrechos. Indica el riesgo de falso positivo para cada regla (por ejemplo, un patrón
maintambién coincide con una rama llamadamain-menu) y agregaallow_globsoexcept_patternscuando 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.jsonsin 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.jsoninválido manualmente en lugar de detenerse. - Afirmar un bloqueo de extremo a extremo que no observaste realmente.