Hook de Claude Code para formatear con Pint y analizar con PHPStan

Hola, bienvenido. En la lección anterior creamos guard.sh, que bloquea en PreToolUse lo que no debe pasar nunca en claude-tasks, y en esta lección pasamos al otro lado de la herramienta, a PostToolUse. Vamos a crear 2 hooks de calidad: pint.sh, que formatea con Pint cada archivo PHP que Claude acaba de escribir o editar, y phpstan.sh, que lo analiza con PHPStan y le cuenta a Claude los errores que encuentre. Por el camino veremos cómo le llega esa información a Claude con additionalContext y qué límites tiene, por qué Rector se queda fuera de los hooks y, para probarlo todo, le pediremos a Claude una acción que marca una tarea como completada, mal formateada a propósito.

¿Qué ganamos con esto, si nuestro CLAUDE.md ya dice que una tarea está terminada cuando pasa composer qa? Que el circuito completo llega al final, cuando Claude ya ha escrito todos los archivos, y un hook llega justo después de cada edición, mientras el cambio está todavía fresco en la conversación. Si Claude escribe una acción con una propiedad que no existe y sigue adelante, puede escribir encima un controlador y un test que usan esa misma propiedad, y el error aparece 3 archivos después. Con el hook, PHPStan se lo dice en cuanto guarda el primer archivo, y Claude lo corrige antes de construir nada encima.

Los 2 hooks responden al mismo momento, cuando la herramienta Edit o Write termina con éxito sobre un archivo PHP, pero hacen cosas distintas con él:

• pint.sh cambia el archivo. Pasa Pint solo sobre ese archivo, con las reglas de nuestro pint.json, y si el formato cambia, se lo dice a Claude. Es una tarea mecánica y sin decisiones: el estilo del proyecto ya está decidido, y no tiene sentido que Claude gaste tokens en espacios y saltos de línea, ni que tú los revises.
• phpstan.sh no cambia nada. Analiza el archivo con Larastan en el nivel 5 de nuestro phpstan.neon, y si hay errores, se los pasa a Claude para que los corrija él. Aquí sí hay decisiones, porque un error de tipos puede tener varias soluciones, así que el hook informa y Claude decide.

Ninguno de los 2 sustituye a composer qa. Los hooks miran un archivo cada vez y dan una señal rápida, y el circuito completo, con Rector en seco y los tests, sigue siendo lo que dice si una tarea está lista. Y hay una tercera herramienta del circuito que no va a tener hook, Rector, por un motivo que veremos más abajo.

Para seguir esta lección necesitas claude-tasks con el commit de guard.sh de la lección anterior, los contenedores de Sail levantados, porque los 2 hooks ejecutan las herramientas dentro del contenedor, y jq instalado. Recuerda también lo que vimos al configurar los hooks: se ejecutan fuera del sandbox, así que pueden llamar a ./vendor/bin/sail aunque Sail no pueda ejecutarse dentro de él.