---
title: "O que aprendemos montando hooks en Claude Code (e o que non fan aínda que o pareza)"
description: "Un hook parece un muro e é un script, con formas de fallar case sempre en silencio. Sete trampas ao usar hooks de Claude Code como gardas dun equipo."
url: https://blablanote.com/gl/blog/o-que-aprendemos-montando-hooks-en-claude-code/
lang: gl
author: Gorka Mendez
published: 2026-11-04
tags: engineering
translations:
  ca: https://blablanote.com/ca/blog/el-que-hem-apres-muntant-hooks-a-claude-code/
  en: https://blablanote.com/blog/what-we-learned-building-claude-code-hooks/
  es: https://blablanote.com/es/blog/lo-que-aprendimos-montando-hooks-en-claude-code/
  eu: https://blablanote.com/eu/blog/claude-codeko-hookekin-ikasi-duguna/
  fr: https://blablanote.com/fr/blog/ce-que-nous-avons-appris-avec-les-hooks-de-claude-code/
---

# O que aprendemos montando hooks en Claude Code (e o que non fan aínda que o pareza)

Hai unhas semanas contamos [como traballamos con Claude Code](https://blablanote.com/gl/blog/asi-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.

(Image: Ilustración: unha fila de persoas e un pequeno robot, o axente, pasan polo arco de seguridade dun aeroporto, coa luz verde acesa. Ao lado, a cinta coas maletas.)

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:

```json
{
  "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:

```sh
#!/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

(Image: Ilustración: un porteiro fala por teléfono, cun reloxo en vermello enriba del, mentres a porta queda aberta e entran persoas e o robot sen que ninguén as mire.)

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.

(Image: Dúas liñas de tempo. Arriba, o que esperas: o hook pásase do seu prazo e a orde queda bloqueada. Abaixo, o que pasa: o hook pásase do seu prazo, Claude Code deixa de esperalo e a orde execútase.)

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

(Image: Ilustración: unha casa en sección. Arriba, o robot traballa tranquilo xunto á súa mesa; no soto, unha alarma soa sen que ninguén a oia.)

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.

(Image: Un hook que se executa despois de cada edición pode avisar de dúas formas. Se escribe texto normal, o aviso vai ao rexistro que le a persoa e o axente non o ve. Se escribe un JSON con additionalContext, o aviso chega ao axente.)

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

(Image: Ilustración: un edificio de catro andares. O robot entra polo portal, onde a alarma está acesa en verde; as dos andares de arriba están apagadas en gris.)

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.

(Image: Catro andares. A sesión entra polo portal, o repositorio de planificación, e só se activa a súa alarma. As da aplicación e da plataforma de eventos están cableadas á mesma garda, pero apagadas. Os outros sete repositorios non teñen cableado.)

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

(Image: Ilustración en dúas metades. Á esquerda, o robot xunto a un libro de receitas aberto, cun visto verde: escribila é inofensivo. Á dereita, o robot dálle a receita a un cociñeiro xunto aos fogóns, cunha aspa vermella: iso si se executa.)

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.

(Image: Tres ordes que nomean o mesmo comando perigoso. Executalo: bloquea, correcto. Buscalo nun documento con grep: pasa, correcto. Mandalo a un intérprete dentro dun bloque de texto: bloquea, correcto, porque ese texto se executa.)

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](https://www.rtk-ai.app/), 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

(Image: Ilustración de dúas portas de discoteca. Á esquerda, un porteiro cunha lista de vetados mentres alguén que non está nela se coa, cunha aspa vermella. Á dereita, un porteiro coa lista de convidados: entra quen está apuntado e quen non o está queda tras o cordón, cun visto verde.)

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:

(Image: Unha táboa con cinco valores posibles do contorno: produción, baleiro, mal escrito, un contorno creado despois e local. A lista negra só para en produción e destrúe nos tres casos raros. A lista branca para en todos menos en local.)

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

(Image: Ilustración en dúas metades. Á esquerda, un sinal de prohibido o paso e unha persoa e o robot que pasan por diante sen deterse. Á dereita, o robot fronte a un torniquete de metro pechado, cunha aspa vermella.)

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.

(Image: Antes da garda: 21 cambios directos á rama principal nunha semana, cada un despregado a produción sen revisión. Despois: 0, porque a garda bloquea o intento e explica o camiño correcto, que é abrir unha PR.)

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

(Image: Ilustración: unha persoa e o robot, cada un co seu portátil, gardan no mesmo documento. A persoa engadira catro seccións; o robot garda a súa copia da mañá e as catro seccións quedan marcadas en vermello, perdidas.)

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.

(Image: Unha liña de tempo coa rama principal. Entran catro cambios: A, B, C e D. Unha rama preparada sobre unha foto vella, anterior a eses catro, entra despois e devólveos ao seu estado anterior. A garda nova compara o que a rama deixa co que acaba de entrar e bloquea o merge.)

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

(Image: Ilustración en dúas metades. Á esquerda, a xente cruza o arco de seguridade sen pararse. Á dereita, unha maleta aberta e desfeita sobre a mesa, un reloxo de area e unha cola de persoas agardando.)

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.
