← Tornar al Blog

El que hem après muntant hooks a Claude Code (i el que no fan encara que ho sembli)

Gorka Mendez
Gorka Mendez16 min de lectura
engineering

Fa unes setmanes vam explicar com treballem amb Claude Code: deu repositoris, diversos agents programant alhora i una regla de fons, que cap regla important depengui que algú se’n recordi.

La peça que sosté aquesta regla són els hooks. Un hook és un petit programa que Claude Code executa en moments fixos: en començar la sessió, després de cada canvi en un fitxer, abans de cada ordre al terminal. I pot dir «no»: si l’ordre és perillosa, la bloqueja abans que passi.

Pensa en el control de seguretat d’un aeroport. Ningú no confia que cada passatger recordi què no pot portar: hi ha un arc i una cinta per on passa tothom. Els hooks són aquest arc per als agents.

Il·lustració: una fila de persones i un petit robot, l’agent, passen per l’arc de seguretat d’un aeroport, amb el llum verd encès. Al costat, la cinta amb les maletes.

En un aeroport, que l’arc falli sense que ningú se n’adoni és molt estrany. Té un llum que indica si està encès, un operari al costat i una prova cada matí amb un objecte de metall. Un hook no porta res d’això: si no s’executa, se li acaba el temps o crida on ningú no l’escolta, tot continua en verd. Aquestes comprovacions les has de posar tu.

Aquest article va d’això: set maneres en què els nostres hooks van fallar sense dir res, com ens en vam adonar i què vam canviar. Si fas servir hooks, o qualsevol automatisme que faci de guarda, és probable que te’n trobis alguna.

Un hook, en quinze línies

Abans dels paranys, vegem com és un hook per dins. Aquest bloqueja qualsevol intent de pujar canvis directament a la branca principal (git push a main). No és la nostra guarda real, que fa força més coses, però funciona i es pot copiar.

Primer, la línia que el connecta. Va a .claude/settings.json, dins del projecte:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/no-push-main.sh\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Traduït: abans de cada ordre de terminal (PreToolUse amb Bash), executa aquest script, i dona-li com a molt deu segons.

I l’script:

#!/bin/sh
# Bloqueja `git push` a main. Claude Code passa l'ordre en JSON per l'entrada estàndard.
# Sortir amb 2 la bloqueja, i el que s'escriu a stderr li arriba a l'agent com a motiu.

orden=$(jq -r '.tool_input.command // empty') || {
  echo "No puc llegir l'ordre (falta jq?). La bloquejo per si de cas." >&2
  exit 2
}

# Només compta si git és on el terminal l'executaria: al principi o després de ; & | (
# Un grep o un echo que esmenten «git push origin main» passen.
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 només s'hi arriba per PR: puja la teva branca i obre'n una." >&2
  exit 2
fi
exit 0

Quan l’agent intenta git push origin main, l’ordre no arriba a executar-se i l’agent rep el motiu. En una sessió de prova va respondre així: «El push a main s’ha bloquejat: un hook del projecte respon “A main només s’hi arriba per PR: puja la teva branca i obre’n una”». I en comptes d’insistir, continua pel camí que li has indicat.

En aquestes quinze línies ja hi ha tres de les lliçons que venen ara: si no pot llegir l’ordre, bloqueja; distingeix entre executar una ordre i esmentar-la; i el motiu va pel canal que l’agent sí que llegeix. Els set paranys expliquen per què cada detall és allà.

1. El porter que triga massa deixa passar tothom

Il·lustració: un porter parla per telèfon, amb un rellotge en vermell a sobre, mentre la porta es queda oberta i hi entren persones i el robot sense que ningú les miri.

Imagina un porter que, abans de deixar entrar ningú, truca per telèfon per comprovar la llista. Un dia la línia va lenta. El lògic seria que no hi entrés ningú fins que el porter tingués resposta. El que passa en realitat és que, passada una estona, la porta s’obre sola.

Això fa un hook quan se li acaba el temps. Cada hook té un termini màxim, i suposàvem que, si s’esgotava, l’ordre quedava bloquejada. No és així. Ho vam mesurar amb un hook de prova que tenia dos segons de termini, en trigava sis i al final deia «no»: l’ordre es va executar igualment. El registre del hook tenia la línia d’inici però mai la del final, perquè Claude Code el va tallar abans que pogués dir res.

Ho vam repetir en escriure aquest article, amb la versió 2.1.318 de Claude Code, i al costat d’un hook de control idèntic però ràpid. El ràpid va bloquejar l’ordre i el lent la va deixar passar.

En el nostre flux, CI passa els tests i desplega, però qui prem el botó de merge és l’agent, amb una ordre al terminal. Davant d’aquesta ordre hi ha una guarda: abans de deixar que un canvi entri a la branca principal, la que es desplega a producció, pregunta a GitHub si els tests estan en verd i si la branca principal s’ha mogut mentrestant. Amb la xarxa lenta, aquesta consulta es menjava el termini i la porta quedava oberta. Ningú no va veure cap error, perquè no n’hi va haver cap.

Dues línies de temps. A dalt, el que esperes: el hook es passa del termini i l’ordre queda bloquejada. A baix, el que passa: el hook es passa del termini, Claude Code deixa d’esperar-lo i l’ordre s’executa.

El que vam canviar:

  • El porter té el seu propi rellotge, més curt que el de la porta. Cada guarda es posa a si mateixa un límit de temps per a cada consulta, i ho fa abans que s’esgoti el del hook.
  • Si no pot comprovar, no deixa passar. Sense xarxa, sense una eina que necessita o amb l’ordinador tan carregat que no hi arriba a temps: bloqueja i explica per què.
  • Un test vigila que els dos rellotges quadrin. Si algú en canvia un i no l’altre, es posa en vermell. Ja va saltar una vegada: una còpia de la guarda tenia 60 segons de termini i en necessitava 120.

I una confessió: la primera versió d’aquest test no comprovava res. Un error en una ruta feia que se saltés tots els fitxers, i sortia sempre en verd. Ho vam descobrir quan vam trencar un termini a propòsit i el test va continuar en verd. Una guarda morta es llegeix igual de bé que una de viva.

2. L’alarma que sona al soterrani

Il·lustració: una casa en secció. A la planta baixa, el robot treballa tranquil al costat de la seva taula; al soterrani, una alarma sona sense que ningú la senti.

Un dels nostres hooks revisa cada fitxer després que l’agent l’editi i avisa de problemes: «a aquest pla li falta l’estat», «aquest document s’ha passat de mida». El provàvem a mà i l’avís sortia perfecte.

Durant setmanes, l’agent no en va rebre ni un.

Era com una alarma que sona al soterrani, on no hi ha ningú. El que aquest tipus de hook escriu com a text normal va al registre que pot llegir la persona, no a l’agent. Perquè l’agent el rebi, l’avís ha d’anar en un format concret (un petit JSON amb un camp anomenat additionalContext). En canvi, en el hook d’inici de sessió el text normal sí que arriba, i per això l’un funcionava i l’altre semblava que funcionava.

També ho vam repetir amb la versió 2.1.318. Un hook que s’executa després de cada edició li passava a l’agent una paraula clau inventada en el moment, i després li preguntàvem quina era. Quan el hook l’escrivia com a text normal, l’agent responia «cap». Quan l’escrivia al JSON, responia la paraula exacta.

Un hook que s’executa després de cada edició pot avisar de dues maneres. Si escriu text normal, l’avís va al registre que llegeix la persona i l’agent no el veu. Si escriu un JSON amb additionalContext, l’avís arriba a l’agent.

Ara tots els avisos surten en aquest format, i un test es posa en vermell si algú torna a escriure text normal.

La lliçó general: no n’hi ha prou de comprovar que una alarma sona. Cal comprovar que la sent qui l’ha de sentir. Amb un hook, això vol dir provocar la situació dins d’una sessió de debò i veure si l’agent reacciona.

3. L’alarma instal·lada que no estava connectada

Il·lustració: un edifici de quatre plantes. El robot entra pel portal, on l’alarma està encesa en verd; les de les plantes de dalt estan apagades, en gris.

La nostra feina està repartida en deu repositoris. Les guardes són les mateixes per a tots: una sola còpia de cada script, al repositori de planificació. El que té cada repositori és el cablejat, una línia a la seva configuració que diu «abans de cada ordre, executa aquesta guarda». Els dos principals, l’aplicació i la plataforma d’esdeveniments, la tenien. Però les nostres sessions no arrenquen dins d’un repositori de producte: arrenquen al de planificació i obren els altres des d’allà.

Resulta que Claude Code llegeix la configuració de dos llocs: la teva d’usuari i la del projecte on arrenca la sessió. La dels repositoris que obre després, no. Ho vam tornar a comprovar amb la versió 2.1.318: el mateix hook que bloquejava una ordre quan la sessió arrencava al seu repositori no s’executava quan aquest repositori s’obria des d’un altre. És com un edifici on només hi ha connectada l’alarma del portal. Pujaves a les plantes on hi ha les coses de valor i la seva alarma, instal·lada i al seu lloc, estava apagada. I unes altres set plantes ni tan sols tenien alarma.

Quatre plantes. La sessió entra pel portal, el repositori de planificació, i només s’activa la seva alarma. Les de l’aplicació i de la plataforma d’esdeveniments estan cablejades a la mateixa guarda, però apagades. Els altres set repositoris no tenen cablejat.

Hi havia dues variants més del mateix problema:

  • Hooks que miraven la planta equivocada. Alguns deduïen en quin repositori eren a partir d’on havia començat la sessió, no del fitxer que s’acabava de tocar. El que formata el codi després de cada edició no s’executava mai en el mode normal de treball.
  • Una guarda que només mirava des d’on es llançava l’ordre. Si l’ordre sortia d’una carpeta temporal, la guarda s’apagava, encara que l’ordre apuntés directament al repositori que calia protegir. És com un vigilant que només revisa qui entra per la porta principal i no mira on va.

Ara la guarda principal està instal·lada a nivell d’usuari, així que cobreix l’edifici sencer. Els hooks dedueixen el repositori a partir del fitxer tocat, i les guardes miren cap a on apunta cada ordre, no des d’on es llança. Quan no ho poden saber, bloquegen tot el que sigui destructiu.

4. El filtre que no et deixa explicar el filtre

Il·lustració en dues meitats. A l’esquerra, el robot al costat d’un llibre de receptes obert, amb una marca verda: escriure-la és inofensiu. A la dreta, el robot dona la recepta a un cuiner al costat dels fogons, amb una creu vermella: això sí que s’executa.

La primera versió de la nostra guarda buscava paraules: si l’ordre contenia el nom d’una instrucció perillosa, la bloquejava. El primer que va bloquejar va ser l’edició del document que explicava per què aquella instrucció estava prohibida.

És com un filtre de correu brossa que envia a la paperera el correu de seguretat que t’explica com reconèixer el correu brossa. O un detector que no et deixa dir «ganivet» per explicar que no es poden portar ganivets.

Una guarda així és pitjor que no tenir-ne cap. Molesta quan la documentes, quan la proves i quan en parles, i a la tercera vegada algú busca la manera d’apagar-la.

Tres ordres que esmenten la mateixa instrucció perillosa. Executar-la: bloqueja, correcte. Buscar-la en un document amb grep: passa, correcte. Enviar-la a un intèrpret dins d’un bloc de text: bloqueja, correcte, perquè aquest text s’executa.

La solució és distingir entre anomenar una ordre i executar-la. La guarda només bloqueja quan la paraula és al lloc on el terminal l’executaria: al principi de l’ordre o just després dels símbols que encadenen ordres. Si la busques en un fitxer o l’escrius en un document, passa.

Amb un matís que ens va costar dos ensurts: un bloc de text que s’envia a un intèrpret sí que s’executa. És la diferència entre escriure una recepta i donar-la al cuiner. El nostre primer filtre tractava totes dues coses igual i deixava passar les ordres perilloses amagades dins d’una recepta que algú donava al cuiner.

I una sorpresa més: altres hooks poden reescriure l’ordre abans que el teu. Fem servir rtk, una eina que retalla la sortida de les ordres perquè l’agent gasti menys tokens. Funciona amb el seu propi hook, que reescriu cada ordre afegint-hi un prefix: gh pr merge passa a ser rtk gh pr merge. I Claude Code no garanteix en quin ordre s’executen els hooks. Quan l’altra eina anava primer, la nostra guarda no reconeixia l’ordre i la deixava passar. La mateixa ordre es va bloquejar en un repositori i va passar en un altre.

La solució va ser deixar de suposar com arriba l’ordre. La guarda reconeix la instrucció tant sola com amb aquest prefix al davant, i cada forma té el seu cas al test. Si demà una altra eina reescriu les ordres d’una altra manera, el test és el lloc on afegir-la.

5. La llista de vetats contra la llista de convidats

Il·lustració de dues portes de discoteca. A l’esquerra, un porter amb una llista de vetats mentre algú que no hi surt es cola, amb una creu vermella. A la dreta, un porter amb la llista de convidats: entra qui hi és apuntat i qui no es queda darrere el cordó, amb una marca verda.

Una discoteca pot controlar l’accés de dues maneres: amb una llista de persones vetades o amb una llista de convidats. Amb la primera, hi entra tothom menys els que ja han donat problemes. Amb la segona, només hi entra qui hi és apuntat.

La nostra guarda de producció va començar amb una llista de vetats: aquestes ordres contra els servidors, no. Quan la vam posar a prova de debò, vam trobar un camí que no era a la llista i que permetia executar el que volguessis a producció. Era just el que la guarda pretenia impedir, per una porta que ningú no havia apuntat.

Hi vam donar la volta. Ara és una llista de convidats: enumera les consultes de només lectura que es permeten i bloqueja tota la resta. Una eina nova o una ordre que no coneixíem compten com a perilloses fins que algú decideixi el contrari.

El mateix principi val dins del codi. Compara aquestes dues regles per a una ordre que esborra dades:

Una taula amb cinc valors possibles de l’entorn: producció, buit, mal escrit, un entorn creat després i local. La llista negra només s’atura a producció i destrueix en els tres casos estranys. La llista blanca s’atura en tots menys en local.

La llista de vetats deixa passar, i destrueix, quan la variable arriba buida, mal escrita o amb el nom d’un entorn nou. La de convidats tracta com a producció tot el que no reconeix.

6. Un cartell no és un torniquet

Il·lustració en dues meitats. A l’esquerra, un senyal de prohibit el pas i una persona i el robot que hi passen per davant sense aturar-se. A la dreta, el robot davant d’un torniquet de metro tancat, amb una creu vermella.

Les normes escrites són cartells: «prohibit el pas», «no trepitgeu la gespa». Una guarda és un torniquet de metro: sense bitllet no passes, tant si l’has llegit com si no.

Nosaltres teníem la norma escrita: els canvis a la branca principal entren sempre per una PR revisada, mai directament. I l’agent la coneixia, perquè és al protocol que llegeix en començar cada sessió. Quan per fi ho vam mesurar, vam trobar 21 canvis directes a la branca principal de l’aplicació en una setmana. Cadascun es va desplegar a producció sense revisió. Ningú no es va saltar la norma a propòsit. Simplement, no hi havia cap torniquet que la fes complir.

Abans de la guarda: 21 canvis directes a la branca principal en una setmana, cadascun desplegat a producció sense revisió. Després: 0, perquè la guarda bloqueja l’intent i explica el camí correcte, que és obrir una PR.

L’altre avís ens va arribar per producció. Una sessió va escriure 20 files a la base de dades de producció mitjançant una ordre remota, i res entre la credencial i la base de dades no va preguntar res. Des d’aleshores, contra producció només es llegeix, i la clau no és a l’abast de l’agent: la té una persona.

Per què hooks i no les regles de permisos que porta Claude Code? Perquè volíem que la protecció no depengués de com es configurés cada sessió. Treballem amb sessions llargues i força autònomes, i un hook s’executa sempre.

7. Dues persones editen el mateix document i una hi desa una còpia vella a sobre

Il·lustració: una persona i el robot, cadascun amb el seu portàtil, desen al mateix document. La persona hi havia afegit quatre seccions; el robot desa la seva còpia del matí i les quatre seccions queden marcades en vermell, perdudes.

Aquesta la coneix tothom qui hagi treballat amb documents compartits. Obres el document al matí i treballes en la teva part. Mentrestant, una companya hi afegeix la seva secció i desa. A la tarda deses tu, des de la teva còpia del matí, i la seva secció desapareix. Ningú no ha esborrat res a propòsit.

Ens va passar amb codi i a producció. Diverses sessions treballen alhora sobre el mateix repositori. Una va preparar el seu canvi a partir d’una foto de la branca principal que una altra sessió acabava de moure. El resultat semblava un canvi normal, va passar tots els tests i la revisió, i en entrar va desfer quatre canvis anteriors que ja eren a producció.

Una línia de temps amb la branca principal. Hi entren quatre canvis: A, B, C i D. Una branca preparada sobre una foto vella, anterior a aquests quatre, entra després i els torna al seu estat anterior. La guarda nova compara el que la branca deixa amb el que acaba d’entrar i bloqueja el merge.

La guarda que en va sortir comprova, abans de cada enviament i de cada merge, si el canvi torna al seu estat anterior fitxers que acaben de canviar a la branca principal. Abans d’activar-la la vam provar contra les 60 últimes PR dels nostres dos repositoris principals: salta en els dos incidents reals i en cap PR legítima. Si de debò vols desfer alguna cosa, ho dius al missatge del canvi i passa.

Ningú no hauria escrit aquesta guarda per endavant. Surt de tractar cada incident com una pregunta: això ho podria detectar una màquina? Si la resposta és sí, es converteix en guarda, amb els seus tests.

El que vam treure

Il·lustració en dues meitats. A l’esquerra, la gent travessa l’arc de seguretat sense aturar-se. A la dreta, una maleta oberta i desfeta damunt la taula, un rellotge de sorra i una cua de persones esperant.

Tot això suma, i va arribar un moment en què sumava massa. «Tot el que fem és molt lent»: esperes de més d’una hora per a algunes comprovacions i desplegaments de prova que el canvi següent deixava antiquats.

En mesurar-ho, vam veure que sota la paraula «guardes» hi havia dues coses molt diferents. Tornant a l’aeroport:

  • L’arc de seguretat són les guardes que bloquegen ordres perilloses. Costen mil·lisegons per ordre i eviten els desastres.
  • L’escorcoll a fons de cada maleta són les comprovacions lentes: certes proves exhaustives o desplegar un entorn de prova amb cada canvi. Allà se n’anaven les hores, i ningú no havia tornat a mirar si cadascuna encara valia la pena.

Dues ja no la valien, i les vam treure del camí de cada canvi:

  • Les proves de mutació en local. Una prova de mutació introdueix petits errors a propòsit al codi (canvia un > per un >=, esborra una línia) i comprova si els tests se n’adonen. Si no se n’adonen, aquests tests no protegeixen tant com sembla. És molt útil, però a l’aplicació mutàvem sencers els fitxers que tocava cada canvi, i això trigava entre sis i deu minuts, i de vegades hores. Ara cada tasca muta només el que afegeix el seu canvi: treu cada condició nova, una per una, i mira si algun test se n’adona. Triga segons i apunta just al que importa, perquè amb milers de tests la pregunta útil no és si hi ha tests, sinó si aquest canvi en porta un que el vigili.

    També vam apagar la mesura setmanal del codi sencer. Costava milers de minuts de CI al mes i gairebé mai no arribava al final: de les últimes vuit, en va acabar una. Donava una nota global sobre la qual ningú no actuava.

  • El desplegament a staging en cada enviament d’una PR a mig fer. Staging és una còpia de l’aplicació on es revisa el canvi abans de producció. Abans, cada vegada que l’agent pujava un canvi a la seva PR, es desplegava staging sencer: uns 8 minuts. Una PR rebia de mitjana gairebé tres enviaments, i cada desplegament deixava antiquat l’anterior abans que ningú el mirés. A l’aplicació eren uns 16 minuts per PR construint una cosa que ningú no mirava. Ara la PR neix en esborrany i només desplega quan està llesta.

L’arc es va quedar. Una guarda que costa mil·lisegons i atura un desastre al mes és el més barat de tot el sistema.

Un hook és codi de producció

Si ho hem de resumir en una idea: un hook que fa de guarda és codi de producció i mereix el mateix tracte.

  • Té tests. Els nostres són 336 casos, cadascun amb una ordre real i el que la guarda n’hauria de fer. Comencen per les ordres inofensives que no s’haurien de bloquejar.
  • Es posa a prova a si mateix. Per a cada guarda tenim una versió trencada a propòsit, i els tests l’han de detectar. És com fer un simulacre amb una maleta trampa: si l’arc no sona, l’arc no funciona.
  • En cas de dubte, tanca. Si no pot comprovar, bloqueja.
  • Es prova on es fa servir. No n’hi ha prou que l’script funcioni. L’agent ha de rebre l’avís.
  • Es guanya el lloc. Només automatitzem el que falla sense avisar i una màquina pot detectar. La resta s’escriu, amb el seu perquè.

Els agents no es cansen, però tampoc no desconfien. Aquesta desconfiança la posem nosaltres, en forma de guardes que es compleixen soles. Som molt desconfiats, encara que només amb els agents: per això cada norma que importa és un torniquet, no un cartell.

I continuarem sent molt desconfiats.

Gorka

Gorka Mendez

Gorka Mendez

Co-founder
30 dies gratis

Transforma les teves converses

Professionals que capturen, organitzen i actuen sobre les seves converses amb intel·ligència artificial.

30 dies gratis
Sense targeta de crèdit
Cancel·la quan vulguis