Directorio / Guías / Claude Code

Hooks en Claude Code: reglas que se cumplen siempre

Cómo hacer que algo pase cada vez sin depender de que Claude se acuerde: formatear lo que edita, bloquear un archivo sensible y qué revisar por seguridad.

Guía paso a paso5 min de lecturaPor Rafael Schwart

Un hook es un comando que Claude Code ejecuta solo, en un momento fijo: antes de usar una herramienta, después de editar un archivo o al terminar de responder. La diferencia con escribir una regla en el CLAUDE.md es la garantía. Claude sigue el CLAUDE.md casi siempre. Un hook corre siempre.

En mejora de procesos esto se llama poka-yoke: en vez de pedirle a alguien que se acuerde, diseñas el paso para que el error no pueda ocurrir.

Las tres piezas

  • El evento: en qué momento corre.
  • El matcher: a qué herramientas aplica. Edit|Write significa editar o escribir archivos. Distingue mayúsculas de minúsculas.
  • El comando: lo que se ejecuta. Recibe los datos de la acción en formato JSON, por ejemplo la ruta del archivo que Claude quiere editar.
EventoCuándo corre
PreToolUseAntes de que Claude use una herramienta. Puede bloquearla.
PostToolUseDespués de que la herramienta terminó bien.
NotificationCuando Claude Code te necesita, por ejemplo para aprobar algo.
StopCuando Claude termina de responder.
SessionStartAl empezar o retomar una sesión.

Dónde se configuran

ArchivoAlcance
~/.claude/settings.jsonTodos tus proyectos
.claude/settings.jsonEste proyecto. Se puede compartir por git.
.claude/settings.local.jsonEste proyecto, solo en tu computadora

Todo va dentro de una sola clave "hooks". Si el archivo ya tiene una, agrega el evento nuevo adentro en lugar de crear otra. También puedes describirle a Claude el hook que quieres y pedirle que lo escriba; igual revisa lo que escribió.

Ejemplo 1: formatear cada archivo que Claude edita

Si tu proyecto usa Prettier, este hook lo corre después de cada edición y el formato queda parejo sin pedirlo. Va en .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Necesita Node.js y jq, una herramienta pequeña para leer JSON que se instala aparte. Es un comando de Bash: en Windows funciona si tienes Git for Windows. Sin él, los hooks corren en PowerShell y tendrás que pedirle a Claude una versión para PowerShell. Cuando el hook funciona no ves ningún mensaje: abre el archivo y comprueba que quedó formateado.

Ejemplo 2: bloquear la edición de un archivo sensible

  1. Crea el script. En Mac o Linux, guárdalo como .claude/hooks/proteger.sh y hazlo ejecutable con chmod +x .claude/hooks/proteger.sh:
    #!/bin/bash
    ENTRADA=$(cat)
    ARCHIVO=$(echo "$ENTRADA" | jq -r '.tool_input.file_path // empty')
    ARCHIVO="${ARCHIVO//\\//}"
    
    for patron in ".env" "precios/"; do
      if [[ "$ARCHIVO" == *"$patron"* ]]; then
        echo "Bloqueado: $ARCHIVO es un archivo protegido" >&2
        exit 2
      fi
    done
    
    exit 0
  2. Regístralo en .claude/settings.json:
    {
      "hooks": {
        "PreToolUse": [
          {
            "matcher": "Edit|Write",
            "hooks": [
              {
                "type": "command",
                "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/proteger.sh"
              }
            ]
          }
        ]
      }
    }
  3. Pruébalo. Pídele a Claude que agregue un comentario al .env. Tiene que frenar antes de editar y explicarte por qué.

El código de salida 2 bloquea la acción, y el mensaje del script le llega a Claude para que cambie de plan. El 0 no aprueba nada: deja que siga el flujo normal de permisos.

En Windows, guarda este script como .claude/hooks/proteger.ps1:

$entrada = [Console]::In.ReadToEnd() | ConvertFrom-Json
$archivo = $entrada.tool_input.file_path -replace '\\', '/'

if ($archivo -match '\.env$|/precios/') {
  @{
    hookSpecificOutput = @{
      hookEventName = "PreToolUse"
      permissionDecision = "deny"
      permissionDecisionReason = "Archivo protegido: lo cambia una persona, no Claude"
    }
  } | ConvertTo-Json
} else {
  exit 0
}

Y en el paso 2 reemplaza el bloque del comando por este:

{
  "type": "command",
  "command": "powershell.exe",
  "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File",
           "${CLAUDE_PROJECT_DIR}/.claude/hooks/proteger.ps1"]
}

Para un bloqueo simple también existen las reglas de permisos, que administras con /permissions. El hook sirve cuando quieres una condición propia o un mensaje que explique el motivo.

Verifica

Escribe /hooks en Claude Code. Muestra todos los hooks activos, agrupados por evento y con el archivo de donde viene cada uno. Es solo de lectura: para cambiar algo, edita el archivo. Si el tuyo no aparece, revisa que el JSON sea válido y que el matcher esté bien escrito.

Seguridad: un hook es un programa

  • Corre con tus permisos. Puede leer, modificar o borrar cualquier archivo al que tenga acceso tu usuario. Lee y prueba cada comando antes de agregarlo.
  • Revisa los proyectos ajenos. Un repositorio puede traer hooks en su .claude/settings.json. Claude Code no los ejecuta hasta que aceptas que confías en la carpeta, así que lee ese archivo antes de aceptar.
  • Un hook roto puede fallar en silencio. En el ejemplo 2, si jq no está instalado, el script no encuentra la ruta y deja pasar todo. Prueba el bloqueo antes de confiar en él.
  • Para apagarlos todos, agrega "disableAllHooks": true a tu archivo de configuración.

La lista completa de eventos y opciones está en la documentación oficial de hooks.

Empieza con un solo hook: el que evita el error que más caro te sale. Un archivo de precios editado por accidente o un dato de cliente que se cuela en una página valen más que diez reglas de formato.

Sigue leyendo

Más guías.

Cada una se lee en menos de cinco minutos.

Todas las guías
Guía paso a paso · 4 min

Claude Code desde cero

Qué es Claude Code, cómo instalarlo en Windows o Mac, tu primer pedido, cómo aprobar lo que hace y los comandos que vas a usar cada día.

Guía paso a paso · 4 min

CLAUDE.md: el manual de tu proyecto

Qué es el archivo CLAUDE.md, dónde va, cómo crearlo con /init y qué escribir para que Claude no te pregunte lo mismo en cada sesión.

  Arqentia

¿Prefieres que lo armemos contigo?

Treinta minutos para ver tu operación: cómo entra el dinero, dónde se pierde tiempo y qué conviene automatizar primero. Gratis para negocios y sin compromiso.

Agendar consulta