claude-hooks

Repositorio de hooks listos para usar con Claude Code en proyectos Java/Gradle. Complementa la serie de tutoriales en javatutoriales.com.

Estructura

.claude/
├── settings.json           ← configuración del equipo (versionar en Git)
├── settings.local.json     ← configuración personal (NO versionar)
└── hooks/
    ├── pre-bash-test-gate.sh               ← bloquea commit si tests fallan
    ├── pre-bash-block-protected-branches.sh← bloquea push a main/master
    ├── pre-write-detect-secrets.sh         ← bloquea secretos hardcodeados
    ├── pre-write-block-immutable-files.sh  ← protege migraciones Flyway
    ├── pre-write-auto-checkpoint.sh        ← checkpoint antes de editar
    ├── post-write-checkstyle.sh            ← Checkstyle automático
    ├── post-write-format-java.sh           ← google-java-format automático
    ├── post-write-antipatterns.sh          ← detecta anti-patrones Java
    ├── post-write-check-test-exists.sh     ← avisa si falta archivo de test
    ├── post-write-check-gradle-deps.sh     ← CVE scan tras cambio en build.gradle
    ├── post-write-validate-openapi.sh      ← valida specs OpenAPI/Swagger
    ├── session-start-context.sh            ← contexto dinámico al arrancar
    ├── session-end-log.sh                  ← log de sesión por proyecto
    ├── stop-notify.sh                      ← notificación al terminar tarea
    ├── pre-compact-save-changes.sh         ← trazabilidad antes de compactar
    └── notification-handler.sh             ← enruta notificaciones del agente

Instalación rápida

# 1. Copia el directorio .claude/ a la raíz de tu proyecto
cp -r .claude/ /ruta/a/tu/proyecto/

# 2. Da permisos de ejecución a todos los scripts
chmod +x /ruta/a/tu/proyecto/.claude/hooks/*.sh

# 3. Añade settings.local.json a .gitignore
echo ".claude/settings.local.json" >> /ruta/a/tu/proyecto/.gitignore
echo ".claude/session-log.jsonl" >> /ruta/a/tu/proyecto/.gitignore
echo ".claude/change-trace.log" >> /ruta/a/tu/proyecto/.gitignore

# 4. Verifica la configuración desde Claude Code
# /hooks

Configuración por hook

Hooks que requieren configuración adicional

Hook	Qué necesita
stop-notify.sh	Variable SLACK_CLAUDE_WEBHOOK en settings.local.json
notification-handler.sh	Misma variable. En Linux: libnotify-bin instalado
post-write-format-java.sh	Plugin Spotless en build.gradle o binario google-java-format.jar
post-write-check-gradle-deps.sh	Plugin OWASP Dependency Check en build.gradle
post-write-validate-openapi.sh	npm install -g @apidevtools/swagger-cli
pre-write-block-immutable-files.sh	Editar FLYWAY_DIRS en el script para tu proyecto
pre-bash-block-protected-branches.sh	Editar PROTECTED_PATTERNS para tus ramas

Configuración de Slack

Edita .claude/settings.local.json (no versionar):

{
  "_env": {
    "SLACK_CLAUDE_WEBHOOK": "https://hooks.slack.com/services/TU_WEBHOOK_AQUI"
  }
}

O exporta la variable en tu ~/.bashrc / ~/.zshrc:

export SLACK_CLAUDE_WEBHOOK="https://hooks.slack.com/services/TU_WEBHOOK_AQUI"

Configuración de Spotless (para formateo automático)

Añade a tu build.gradle:

plugins {
    id "com.diffplug.spotless" version "6.25.0"
}

spotless {
    java {
        googleJavaFormat()
        removeUnusedImports()
        trimTrailingWhitespace()
        endWithNewline()
    }
}

Configuración de OWASP Dependency Check

Añade a tu build.gradle:

plugins {
    id "org.owasp.dependencycheck" version "9.2.0"
}

dependencyCheck {
    failBuildOnCVSS = 9    // solo falla en CVEs críticos (CVSS >= 9)
    format = "JSON"
    suppressionFile = ".claude/owasp-suppressions.xml"  // opcional
}

Deshabilitar hooks temporalmente

Para deshabilitar todos los hooks en una sesión específica, edita settings.json y añade:

{
  "disableAllHooks": true,
  ...
}

Para deshabilitar un hook individual, comenta o elimina su entrada en el array correspondiente en settings.json.

Ver hooks activos

Dentro de una sesión de Claude Code:

/hooks

Para ver el output en tiempo real (debug):

Ctrl+O  →  activa verbose mode

Ver los logs generados

# Log de sesiones (una línea JSON por sesión)
cat .claude/session-log.jsonl | jq '.'

# Log de trazabilidad de cambios (antes de cada /compact)
cat .claude/change-trace.log

# Commits de checkpoint creados por el agente
git log --oneline --grep="claude-checkpoint"

# Limpiar checkpoints (mantener solo los últimos 5)
git log --oneline --grep="claude-checkpoint" | tail -n +6 | awk '{print $1}' | xargs git rebase -i 2>/dev/null || true

Exit codes de referencia

Código	Significado
0	Éxito — la acción puede proceder
2	Bloqueo en PreToolUse, o forzar continuar en Stop
1 (otro)	Warning no bloqueante — se muestra pero la acción continúa

Recursos

• Claude Code — Documentación oficial de Hooks
• Serie de tutoriales Claude Code — javatutoriales.com