O que aprendemos montando hooks en Claude Code (e o que non fan aínda que o pareza)
- Un hook, en quince liñas
- 1. O porteiro que tarda demasiado deixa pasar a todo o mundo
- 2. A alarma que soa no soto
- 3. A alarma instalada que non estaba conectada
- 4. O filtro que non te deixa explicar o filtro
- 5. A lista de vetados fronte á lista de convidados
- 6. Un cartel non é un torniquete
- 7. Dúas persoas editan o mesmo documento e unha sobrescríbeo coa súa copia vella
- O que quitamos
- Un hook é código de produción
Hai unhas semanas contamos como traballamos con Claude Code: dez repositorios, varios axentes programando á vez e unha regra de fondo, que ningunha regra importante dependa de que alguén se lembre dela.
A peza que sostén esa regra son os hooks. Un hook é un pequeno programa que Claude Code executa en momentos fixos: ao comezar a sesión, despois de cada cambio nun ficheiro, antes de cada orde no terminal. E pode dicir «non»: se a orde é perigosa, bloquéaa antes de que pase.
Pensa no control de seguridade dun aeroporto. Ninguén confía en que cada pasaxeiro lembre o que non pode levar: hai un arco e unha cinta polos que pasa todo o mundo. Os hooks son ese arco para os axentes.

Nun aeroporto, que o arco falle sen que ninguén se decate é moi raro. Ten unha luz que indica se está aceso, un operario ao lado e unha proba cada mañá cun obxecto de metal. Un hook non trae nada diso: se non se executa, se se lle acaba o tempo ou se berra onde ninguén escoita, todo segue en verde. Esas comprobacións tes que poñelas ti.
Este artigo vai diso: sete formas en que os nosos hooks fallaron sen dicir nada, como nos decatamos e que cambiamos. Se usas hooks, ou calquera automatismo que faga de garda, é probable que atopes algunha.
Un hook, en quince liñas
Antes das trampas, vexamos como é un hook por dentro. Este bloquea calquera intento de subir cambios directamente á rama principal (git push a main). Non é a nosa garda real, que fai bastante máis, pero funciona e pódese copiar.
Primeiro, a liña que o conecta. Vai en .claude/settings.json, dentro do proxecto:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/no-push-main.sh\"",
"timeout": 10
}
]
}
]
}
}
Traducido: antes de cada orde de terminal (PreToolUse con Bash), executa este script, e dálle como moito dez segundos.
E o script:
#!/bin/sh
# Bloquea `git push` a main. Claude Code pasa a orde en JSON pola entrada estándar.
# Saír con 2 bloquéaa, e o que se escribe en stderr chégalle ao axente como motivo.
orden=$(jq -r '.tool_input.command // empty') || {
echo "Non podo ler a orde (falta jq?). Bloquéoa por se acaso." >&2
exit 2
}
# Só conta se git está onde o terminal o executaría: ao principio ou tras ; & | (
# Un grep ou un echo que mencionan «git push origin main» pasan.
if printf '%s\n' "$orden" | grep -Eq '(^|[;&|(])[[:space:]]*((rtk|sudo)[[:space:]]+)?git([[:space:]]+-C[[:space:]]+[^[:space:]]+)?[[:space:]]+push([[:space:]]+[^;&|]*)?([[:space:]]|:)(refs/heads/)?main([[:space:];&|)]|$)'; then
echo "A main só se chega por PR: empuxa a túa rama e abre unha." >&2
exit 2
fi
exit 0
Cando o axente tenta git push origin main, a orde non chega a executarse e o axente recibe o motivo. Nunha sesión de proba respondeu así: «O push a main bloqueouse: un hook do proxecto responde “A main só se chega por PR: empuxa a túa rama e abre unha”». E no canto de insistir, segue polo camiño que lle indicaches.
Nesas quince liñas xa hai tres das leccións que veñen agora: se non pode ler a orde, bloquea; distingue entre executar un comando e mencionalo; e o motivo vai polo canal que o axente si le. As sete trampas explican por que cada detalle está aí.
1. O porteiro que tarda demasiado deixa pasar a todo o mundo

Imaxina un porteiro que, antes de deixar entrar a ninguén, chama por teléfono para comprobar a lista. Un día a liña vai lenta. O lóxico sería que ninguén entrase ata que o porteiro tivese resposta. O que pasa en realidade é que, pasado un tempo, a porta ábrese soa.
Iso fai un hook cando se lle acaba o tempo. Cada hook ten un prazo máximo, e supoñiamos que, se se esgotaba, a orde quedaba bloqueada. Non é así. Medímolo cun hook de proba que tiña dous segundos de prazo, tardaba seis e ao final dicía «non»: a orde executouse igual. O rexistro do hook tiña a liña de inicio e nunca a do final, porque Claude Code o cortou antes de que puidese dicir nada.
Repetímolo ao escribir este artigo, coa versión 2.1.318 de Claude Code, e ao lado dun hook de control idéntico pero rápido. O rápido bloqueou a orde e o lento deixouna pasar.
No noso fluxo, CI pasa os tests e desprega, pero quen preme o botón de merge é o axente, cunha orde no terminal. Diante desa orde hai unha garda: antes de deixar que un cambio entre na rama principal, a que se desprega a produción, pregúntalle a GitHub se os tests están en verde e se a rama principal se moveu mentres tanto. Coa rede lenta, esa consulta comíase o prazo e a porta quedaba aberta. Ninguén viu ningún erro, porque non o houbo.

O que cambiamos:
- O porteiro ten o seu propio reloxo, máis curto ca o da porta. Cada garda ponse a si mesma un límite de tempo para cada consulta, e faino antes de que se esgote o do hook.
- Se non pode comprobar, non deixa pasar. Sen rede, sen unha ferramenta que necesita ou co ordenador tan cargado que non chega a tempo: bloquea e explica por que.
- Un test vixía que os dous reloxos cadren. Se alguén cambia un e non o outro, ponse en vermello. Xa saltou unha vez: unha copia da garda tiña 60 segundos de prazo e necesitaba 120.
E unha confesión: a primeira versión dese test non comprobaba nada. Un erro nunha ruta facía que saltase todos os ficheiros, e saía sempre en verde. Descubrímolo cando rompemos un prazo a propósito e o test seguiu en verde. Unha garda morta lese igual de ben ca unha viva.
2. A alarma que soa no soto

Un dos nosos hooks revisa cada ficheiro despois de que o axente o edita e avisa de problemas: «a este plan fáltalle o seu estado», «este documento pasouse de tamaño». Probabámolo a man e o aviso saía perfecto.
Durante semanas, o axente non recibiu nin un.
Era coma unha alarma que soa no soto, onde non hai ninguén. O que ese tipo de hook escribe como texto normal vai ao rexistro que pode ler a persoa, non ao axente. Para que o axente o reciba, o aviso ten que ir nun formato concreto (un pequeno JSON cun campo chamado additionalContext). No hook de inicio de sesión, en cambio, o texto normal si chega, e por iso un funcionaba e o outro parecía funcionar.
Tamén o repetimos coa versión 2.1.318. Un hook que corre despois de cada edición pasáballe ao axente unha palabra clave inventada no momento, e logo preguntabámoslle cal era. Cando o hook a escribía como texto normal, o axente respondía «ningunha». Cando a escribía no JSON, respondía a palabra exacta.

Agora todos os avisos saen nese formato, e un test ponse en vermello se alguén volve escribir texto normal.
A lección xeral: comprobar que unha alarma soa non abonda. Hai que comprobar que a oe quen ten que oíla. Cun hook, iso significa provocar a situación dentro dunha sesión de verdade e ver se o axente reacciona.
3. A alarma instalada que non estaba conectada

O noso traballo está repartido en dez repositorios. As gardas son as mesmas para todos: unha soa copia de cada script, no repositorio de planificación. O que ten cada repositorio é o cableado, unha liña na súa configuración que di «antes de cada orde, executa esta garda». Os dous principais, a aplicación e a plataforma de eventos, tíñana. Pero as nosas sesións non arrancan dentro dun repositorio de produto: arrancan no de planificación e abren os demais desde alí.
Resulta que Claude Code le a configuración de dous sitios: a túa de usuario e a do proxecto onde arranca a sesión. A dos repositorios que abre despois, non. Volvémolo comprobar coa versión 2.1.318: o mesmo hook que bloqueaba unha orde cando a sesión arrancaba no seu repositorio non se executaba cando ese repositorio se abría desde outro. É coma un edificio no que só se conecta a alarma do portal. Subías aos andares onde está o valioso e a súa alarma, instalada e no seu sitio, estaba apagada. E outros sete andares nin sequera tiñan alarma.

Había dúas variantes máis do mesmo problema:
- Hooks que miraban o andar equivocado. Algúns deducían en que repositorio estaban a partir de onde comezara a sesión, non do ficheiro que se acababa de tocar. O que formata o código despois de cada edición non se executaba nunca no modo normal de traballo.
- Unha garda que só miraba desde onde se lanzaba a orde. Se a orde saía dun cartafol temporal, a garda apagábase, aínda que a orde apuntase directamente ao repositorio que había que protexer. É coma un vixiante que só revisa a quen entra pola porta principal e non mira a onde vai.
Agora a garda principal está instalada a nivel de usuario, así que cobre o edificio enteiro. Os hooks deducen o repositorio a partir do ficheiro tocado, e as gardas miran a onde apunta cada orde, non desde onde se lanza. Cando non poden sabelo, bloquean o que sexa destrutivo.
4. O filtro que non te deixa explicar o filtro

A primeira versión da nosa garda buscaba palabras: se a orde contiña o nome dun comando perigoso, bloqueábaa. O primeiro que bloqueou foi a edición do documento que explicaba por que ese comando estaba prohibido.
É coma un filtro de spam que manda á papeleira o correo de seguridade que che avisa de como recoñecer o spam. Ou un detector que non te deixa dicir «coitelo» para explicar que non se poden levar coitelos.
Unha garda así é peor que non tela. Molesta ao documentala, ao probala e ao falar dela, e á terceira vez alguén busca a forma de apagala.

A solución é distinguir entre nomear un comando e executalo. A garda só bloquea cando a palabra está no lugar onde o terminal a executaría: ao principio da orde ou xusto despois dos símbolos que encadean ordes. Buscala nun ficheiro ou escribila nun documento pasa.
Cun matiz que nos custou dous sustos: un bloque de texto que se manda a un intérprete si se executa. É a diferenza entre escribir unha receita e darlla ao cociñeiro. O noso primeiro filtro trataba igual as dúas cousas e deixaba pasar as ordes perigosas agochadas dentro dunha receita que alguén lle daba ao cociñeiro.
E unha sorpresa máis: outros hooks poden reescribir a orde antes ca o teu. Usamos rtk, unha ferramenta que recorta a saída dos comandos para que o axente gaste menos tokens. Funciona co seu propio hook, que reescribe cada orde engadíndolle un prefixo: gh pr merge pasa a ser rtk gh pr merge. E Claude Code non garante en que orde corren os hooks. Cando a outra ía primeiro, a nosa garda non recoñecía a orde e deixábaa pasar. A mesma orde bloqueouse nun repositorio e pasou noutro.
O arranxo foi deixar de supoñer en que forma chega a orde. A garda recoñece o comando tanto só como con ese prefixo diante, e cada forma ten o seu caso no test. Se mañá outra ferramenta reescribe as ordes doutra maneira, o test é o sitio onde engadila.
5. A lista de vetados fronte á lista de convidados

Unha discoteca pode controlar o acceso de dúas formas: cunha lista de persoas vetadas ou cunha lista de convidados. Coa primeira, entra todo o mundo menos os que xa deron problemas. Coa segunda, só entra quen está apuntado.
A nosa garda de produción comezou cunha lista de vetados: estas ordes contra os servidores, non. Cando a puxemos a proba de verdade, atopamos un camiño que non estaba na lista e que permitía executar o que quixeses en produción. Era xusto o que a garda pretendía impedir, por unha porta que ninguén apuntara.
Démoslle a volta. Agora é unha lista de convidados: enumera as consultas de só lectura que se permiten e bloquea todo o demais. Unha ferramenta nova ou un comando que non coñeciamos contan como perigosos ata que alguén decida o contrario.
O mesmo principio vale dentro do código. Compara estas dúas regras para un comando que borra datos:

A lista de vetados deixa pasar, e destrúe, cando a variable vén baleira, mal escrita ou co nome dun contorno novo. A de convidados trata como produción todo o que non recoñece.
6. Un cartel non é un torniquete

As normas escritas son carteis: «prohibido o paso», «non pisar o céspede». Unha garda é un torniquete de metro: sen billete, non pasas, o leses ou non.
Nós tiñamos a norma escrita: os cambios á rama principal entran sempre por unha PR revisada, nunca directamente. E o axente coñecíaa, porque está no protocolo que le ao comezar cada sesión. Cando por fin medimos, atopamos 21 cambios directos á rama principal da aplicación nunha semana. Cada un despregouse a produción sen revisión. Ninguén se saltou a norma a propósito. Simplemente, non había ningún torniquete que a fixese cumprir.

O outro aviso chegounos por produción. Unha sesión escribiu 20 filas na base de datos de produción mediante un comando remoto, e nada entre a credencial e a base de datos preguntou nada. Desde entón, contra produción só se le, e a chave non está ao alcance do axente: tena unha persoa.
Por que hooks e non as regras de permisos que trae Claude Code? Porque queriamos que a protección non dependese de como se configurase cada sesión. Traballamos con sesións longas e bastante autónomas, e un hook execútase sempre.
7. Dúas persoas editan o mesmo documento e unha sobrescríbeo coa súa copia vella

Esta coñécea calquera que traballase con documentos compartidos. Abres o documento pola mañá e traballas na túa parte. Mentres, unha compañeira engade a súa sección e garda. Pola tarde gardas ti, desde a túa copia da mañá, e a súa sección desaparece. Ninguén borrou nada a propósito.
Pasounos con código e en produción. Varias sesións traballan á vez sobre o mesmo repositorio. Unha preparou o seu cambio a partir dunha foto da rama principal que outra sesión acababa de mover. O resultado parecía un cambio normal, pasou todos os tests e a revisión, e ao entrar desfixo catro cambios anteriores que xa estaban en produción.

A garda que saíu de aí comproba, antes de cada envío e de cada merge, se o cambio devolve ao seu estado anterior ficheiros que acaban de cambiar na rama principal. Antes de activala probámola contra as 60 últimas PRs dos nosos dous repositorios principais: salta nos dous incidentes reais e en ningunha PR lexítima. Se de verdade queres desfacer algo, dilo na mensaxe do cambio e pasa.
Ninguén escribiría esa garda por adiantado. Sae de tratar cada incidente como unha pregunta: isto podería detectalo unha máquina? Se a resposta é si, convértese en garda, cos seus tests.
O que quitamos

Todo isto suma, e chegou un momento en que sumaba demasiado. «Todo o que facemos é moi lento»: esperas de máis dunha hora para algunhas comprobacións e despregamentos de proba que o seguinte cambio deixaba vellos.
Ao medir, vimos que baixo a palabra «gardas» había dúas cousas moi distintas. Volvendo ao aeroporto:
- O arco de seguridade son as gardas que bloquean ordes perigosas. Custan milisegundos por orde e evitan os desastres.
- O rexistro a fondo de cada maleta son as comprobacións lentas: certas probas exhaustivas ou despregar un contorno de proba con cada cambio. Aí íanse as horas, e ninguén volvera mirar se cada unha seguía pagando a pena.
Dúas xa non pagaban a pena, e sacámolas do camiño de cada cambio:
-
As probas de mutación en local. Unha proba de mutación mete pequenos erros a propósito no código (cambia un
>por un>=, borra unha liña) e comproba se os tests se decatan. Se non se decatan, eses tests non protexen tanto como parece. É moi útil, pero na aplicación mutabamos os ficheiros enteiros que tocaba cada cambio, e iso tardaba entre seis e dez minutos, e ás veces horas. Agora cada tarefa muta só o que o seu cambio engade: quita cada condición nova, unha a unha, e mira se algún test se decata. Tarda segundos e apunta xusto ao que importa, porque con miles de tests a pregunta útil non é se hai tests, senón se este cambio trae un que o vixíe.Tamén apagamos a medición semanal do código enteiro. Custaba miles de minutos de CI ao mes e case nunca chegaba ao final: das últimas oito, rematou unha. Daba unha nota global sobre a que ninguén actuaba.
-
O despregamento a staging en cada envío dunha PR a medio facer. Staging é unha copia da aplicación onde se mira o cambio antes de produción. Antes, cada vez que o axente subía un cambio á súa PR, despregábase staging enteiro: uns 8 minutos. Unha PR recibía de media case tres envíos, e cada despregamento deixaba vello o anterior antes de que ninguén o mirase. Na aplicación eran uns 16 minutos por PR construíndo algo que ninguén miraba. Agora a PR nace en borrador e só desprega cando está lista.
O arco quedou. Unha garda que custa milisegundos e para un desastre ao mes é o máis barato de todo o sistema.
Un hook é código de produción
Se hai que resumilo nunha idea: un hook que fai de garda é código de produción e merece o mesmo trato.
- Ten tests. Os nosos son 336 casos, cada un cunha orde real e o que a garda debería facer con ela. Comezan polas ordes inofensivas que non deberían bloquearse.
- Ponse a proba a si mesmo. Para cada garda temos unha versión rota a propósito, e os tests teñen que detectala. É coma facer un simulacro cunha maleta trampa: se o arco non pita, o arco non funciona.
- Ante a dúbida, pecha. Se non pode comprobar, bloquea.
- Próbase onde se usa. Que o script funcione non abonda. O axente ten que recibir o aviso.
- Gáñase o sitio. Só automatizamos o que falla sen avisar e unha máquina pode detectar. O demais escríbese, co seu porqué.
Os axentes non se cansan, pero tampouco desconfían. Esa desconfianza poñémola nós, en forma de gardas que se cumpren soas. Somos moi desconfiados, aínda que só cos axentes: por iso cada norma que importa é un torniquete, non un cartel.
E imos seguir sendo moi desconfiados.
