Claude Code Hooks: Täydellinen kehittäjän opas tuotantovalmiilla esimerkeillä

Claude Code Hooks: Täydellinen kehittäjän opas tuotantokelpoisilla esimerkeillä

Claude Code on erinomainen koodin kirjoittamisessa, mutta se on silti probabilistinen järjestelmä. Voit pyytää sitä ajamaan Prettierin jokaisen tiedostomuokkauksen jälkeen. Voit lisätä tämän ohjeen CLAUDE.md-tiedostoosi. Ja joskus se vain... unohtaa. Claude Code -hookit ratkaisevat tämän antamalla sinulle deterministisen ja taatun hallinnan siihen, mitä tapahtuu ennen jokaista Clauden toimintoa, sen aikana ja sen jälkeen.

Olen konfiguroinut hookeja kymmenissä projekteissa viime kuukausien aikana, ja niistä on hiljalleen tullut tärkein osa Claude Code -ympäristöäni. Tämä opas kattaa kaiken perusteista tuotantokelpoiseen aloituspakettiin, jonka voit ottaa käyttöön missä tahansa projektissa jo tänään. Jos olet käyttänyt Claude Codea Cursorin tai Copilotin kaltaisten työkalujen rinnalla, tiedät jo mukauttamisen arvon – hookit vievät sen vielä askeleen pidemmälle.

Mitä ovat Claude Code -koukut (ja miksi sinun kannattaa välittää niistä)?

Claude Code -koukut ovat käyttäjän määrittämiä shell-komentoja, HTTP-päätepisteitä tai LLM-kehotteita, jotka suoritetaan automaattisesti Claude Coden elinkaaren tietyissä vaiheissa. Anthropicin virallisen dokumentaation mukaan koukut laukeavat deterministisesti joka kerta, toisin kuin kehotekäskyt, jotka Claude saattaa jättää huomiotta. Näin saat varman hallinnan muotoiluun, tietoturvaan, ilmoituksiin ja työnkulun automatisointiin.

Todennäköisyysongelma

CLAUDE.md-ohjeissa on yksi perustavanlaatuinen piirre: ne ovat ehdotuksia, eivät sopimuksia. Voit kirjoittaa projektisi kontekstiin "aja aina npx prettier --write TypeScript-tiedostojen muokkaamisen jälkeen", ja Claude noudattaa sitä useimmiten. Mutta "useimmiten" ei riitä, kun valvot koodin muotoilua koko tiimissä, estät tuotantoon pushaamista tai kirjaat jokaista shell-komentoa turvallisuusauditointia varten.

Tämä on minkä tahansa tekoälypohjaisen koodaustyökalun keskeinen jännite. Claude on kielimalli, joka toimii todennäköisyyksien varassa. Konteksti-insinöörinty voi ohjata käyttäytymistä, mutta se ei voi taata sitä.

Miten hookit ratkaisevat tämän

Hookit ohittavat LLM:n kokonaan. Ne ovat shell-skriptejä, HTTP-kutsuja tai tekoälyarviointeja, jotka käynnistyvät tietyissä elinkaaren tapahtumissa: ennen kuin työkalu suoritetaan (PreToolUse), sen valmistumisen jälkeen (PostToolUse), kun ilmoitus ilmestyy, kun istunto alkaa tai kun Claude pysähtyy. Ajattele niitä kuin Git-hookeja, mutta tekoälykoodausavustajallesi.

Hook-tyyppejä on neljä: command (shell-skriptit), HTTP (webhook-POST-pyynnöt), prompt (yhden kierroksen Claude kyllä/ei -arvioinnit) ja agent (käynnistää alagentin, jolla on työkalujen käyttöoikeus). Käymme jokaisen läpi myöhemmin, command-hookit kattavat noin 90 % tarpeistasi.

Kuinka Claude Code -koukut toimivat: Elinkaarivirtaus

Claude Code -koukut suoritetaan määritellyssä elinkaaressa: tapahtuma laukeaa (esim. PreToolUse), sovittaja tarkistaa, päteekö koukko, koukkoskripti ajetaan ja vastaanottaa JSON:ia stdin:issä, ja poistumiskoodi määrittää, mitä tapahtuu seuraavaksi. Poistumiskoodi 0 tarkoittaa jatka, poistumiskoodi 2 tarkoittaa estä toiminto. Tämä virtaus on sama riippumatta siitä, mitä koukkutyyppiä käytät.

Tapahtuma -> Matcher -> Hook -> Exit-koodi (nelivaiheinen kulku)

Näin jokainen hook-suoritus toimii:

1. EVENT FIRES          e.g., PreToolUse(Write)
       |
2. MATCHER CHECKS       Does "Write" match the hook's matcher pattern?
       |
3. HOOK EXECUTES        Shell script runs, receives JSON via stdin
       |
4. EXIT CODE DECIDES    0 = proceed | 2 = block | other = error

Stdinin kautta saapuva JSON sisältää kaiken tapahtumasta: tool_name, tool_input (tiedostopolku, sisältö, komento) sekä istunnon metatiedot. Skriptisi lukee tämän JSONin, suorittaa tarvittavan logiikan ja poistuu asianmukaisella koodilla.

PreToolUse-hookeissa exit-koodi 2 on tehokkain: se estää toiminnon kokonaan ja lähettää stdout-viestisi takaisin Claudelle palautteena. Claude näkee viestisi ja voi mukauttaa lähestymistapaansa.

Asetusalueet: käyttäjä, projekti ja paikallinen

Hookit sijaitsevat settings.json-tiedostossa kolmella tasolla:

Projektiasetukset ovat hyödyllisimpiä tiimeille. Lisää hookisi .claude/settings.json-tiedostoon, commitoi se, niin jokainen tiimin kehittäjä saa samat suojakaiteet automaattisesti.

if-kenttä: Hienojakoinen suodatus

Claude Code v2.1.85 -versiosta lähtien hookit ovat tukeneet if-kenttää, jonka avulla voit suodattaa työkalun argumenttien eikä vain työkalun nimen perusteella. Kuten Anthropicin hooks-ohjeessa dokumentoidaan, tämä tarkoittaa, että voit kirjoittaa hookin, joka käynnistyy vain Bash-komennoilla, jotka vastaavat git push -komentoa, sen sijaan että se laukeaisi jokaisella Bash-kutsulla.

{
  "matcher": "Bash",
  "if": "tool_input.command matches 'git push'",
  "hooks": [{ "type": "command", "command": "./scripts/check-branch.sh" }]
}

Tämä oli merkittävä parannus. Ennen if-kenttää joko täsmäytettiin liian laajasti (jokainen Bash-komento) tai suodatus tehtiin skriptin sisällä (sotkuista).

Kaikki Claude Coden hook-tapahtumat: Pikaopastaulukko

Claude Code tarjoaa yli 20 hook-tapahtumaa elinkaarensa aikana, kuten virallisessa hooks-ohjeessa ja Claude Coden muutoslokissa on dokumentoitu. Yleisimmin käytetyt ovat PreToolUse, PostToolUse, Notification ja Stop, mutta uudemmat tapahtumat, kuten ConfigChange ja FileChanged, mahdollistavat edistyneitä automaatiomalleja.

Tässä on täydellinen opas:

Ammattilaisvinkki: Käytät PreToolUsea ja PostToolUsea 80 prosentissa hookeistasi. SessionStart on seuraavaksi hyödyllisin – se sopii täydellisesti projektikontekstin lisäämiseen, jota Claude tarvitsee jokaisen istunnon alussa.

Claude Coden neljä hook-tyyppiä selitettynä

Claude Code tukee neljää hook-käsittelijätyyppiä: command-hookit ajavat shell-skriptejä, HTTP-hookit tekevät POST-pyyntöjä URL-osoitteisiin, prompt-hookit kysyvät Claudelta kyllä/ei-kysymyksen ja agent-hookit käynnistävät työkaluihin pääsyn saavan alagentin. Kokemuksemme perusteella command-hookit hoitavat 90 % käyttötapauksista. Käytä HTTP:tä ulkoisiin integraatioihin sekä prompt- ja agent-hookeja vivahteikkaisiin päätöksiin, jotka vaativat tekoälyn harkintaa.

Komentokoukut (työjuhta)

Komentokoukut suorittavat shell-komennon ja käyttävät poistumiskoodia tuloksen määrittämiseen. Ne vastaanottavat tapahtuman JSON-datan stdinin kautta.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' | grep -q 'rm -rf /' && exit 2 || exit 0"
      }]
    }]
  }
}

Tätä käytät muotoiluun, tiedostojen suojaamiseen, ilmoituksiin ja useimpiin automaatioihin. Nopea, yksinkertainen ja ennustettava.

HTTP-hookit (ulkoiset integraatiot)

HTTP-hookit lähettävät POST-pyynnön URL-osoitteeseen, jonka runkona on tapahtuman JSON. Vastauksen tilakoodi ratkaisee lopputuloksen (200 = jatketaan, 403 = estetään).

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "http",
        "url": "https://your-api.com/claude-webhook"
      }]
    }]
  }
}

Erinomainen tapahtumien lähettämiseen Slackiin, Discordiin, PagerDutyyn tai mukautettuun kojelautaan. Voit myös käyttää tätä ulkoisen politiikkamoottorin kuulemiseen ennen työkalun suorituksen sallimista.

Prompt-koukut (tekoälypohjaiset päätökset)

Prompt-koukut välittävät tapahtumatiedot Claudelle itselleen yhden kierroksen kyllä/ei-arviointia varten. Claude palauttaa JSON-vastauksen, jossa on "decision": "allow" tai "decision": "block" sekä perustelut.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Is this bash command safe to run in a production environment? Consider: does it modify system files, delete data, or access sensitive credentials?"
      }]
    }]
  }
}

Käytä näitä säästeliäästi. Ne lisäävät viivettä (kokonainen LLM-kutsu jokaista koukun suoritusta kohden) ja kustannuksia. Mutta aidosti subjektiivisiin turvatarkastuksiin, kuten "näyttääkö tämä tietokantamigraatio tuhoavalta?", niitä on vaikea voittaa. Jos olet kiinnostunut Claude Code -mallien vaihtamisesta, prompt-koukuissa käytetty malli seuraa nykyisen istunnon mallia.

Agentin koukut (työkaluavusteinen varmistus)

Agentin koukut käynnistävät aliagentin, jolla on pääsy Read-, Grep- ja Glob-työkaluihin. Aliagentti voi tutkia tiedostoja ennen päätöksentekoa.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "agent",
        "prompt": "Check if the file being written follows the project's naming conventions and import patterns. Read .claude/CONVENTIONS.md for the rules."
      }]
    }]
  }
}

Tämä on tehokkain koukkutyyppi, mutta myös hitain. Varaa se tarkistuksiin, joissa on paljon pelissä ja joissa tarvitset tiedostokontekstin hyvän päätöksen tekemiseen.

7 tuotantokäyttöön valmista Claude Code -hook-esimerkkiä (valmiina kopioitavaksi)

Hyödyllisimpiä Claude Code -hookeja ovat muun muassa automaattinen muotoilu Prettierillä tai Blackillä tiedostomuokkausten jälkeen, kirjoittamisen estäminen suojattuihin tiedostoihin, työpöytäilmoitusten lähettäminen tehtävän valmistuessa, projektikontekstin lisääminen istunnon alussa, testien suorittaminen koodimuutosten jälkeen, haarasuojausten valvonta ja kaiken työkalujen käytön auditointi. Olen käyttänyt näiden muunnelmia kaikissa projekteissani viimeisten kolmen kuukauden ajan.

Jokainen alla oleva esimerkki on valmis settings.json-koodinpätkä, jonka voit lisätä .claude/settings.json-tiedostoosi. Yhteisökokoelmissa, kuten awesome-claude-code, on vielä enemmän malleja.

1. Automaattinen muotoilu tallennuksen yhteydessä

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }]
  }
}

Tämä käynnistyy jokaisen Write- tai Edit-operaation jälkeen, poimii tiedostopolun stdin-JSON:sta ja ajaa sopivan muotoiluohjelman. Lopussa oleva exit 0 varmistaa, ettei koukku koskaan estä toimintaa — muotoiluvirheet eivät saa pysäyttää Claudea.

Ammattilaisvinkki: Lisää *.go ja gofmt sekä *.rs ja rustfmt, jos työskentelet useilla kielillä.

2. Suojattuihin tiedostoihin kirjoittamisen estäminen

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\.local|package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: This file is protected. Edit it manually.\"}' && exit 2"
      }]
    }]
  }
}

Paluukoodi 2 estää toiminnon ja lähettää JSON-muotoisen viestin takaisin Claudelle. Claude näkee palautteen ja mukautuu, yleensä se kertoo halunneensa muokata tiedostoa ja pyytää sinua tekemään sen manuaalisesti. if-kenttä estää tätä laukeamasta jokaisella Write-operaatiolla.

3. Työpöytäilmoitus valmistumisesta

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Claude Code task finished\"' /dev/stdin); if [ \"$(uname)\" = 'Darwin' ]; then osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\"; else notify-send 'Claude Code' \"$MSG\"; fi; exit 0"
      }]
    }]
  }
}

Toimii macOS:ssä (osascript) ja Linuxissa (notify-send). Tyhjä matcher tarkoittaa, että se laukeaa kaikista ilmoituksista. Tämä on aidosti hyödyllistä, kun käynnistät pitkän tehtävän ja vaihdat toiseen ikkunaan.

4. Kontekstin injektointi istunnon alussa

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null || echo none)\"' | Last commit: '\"$(git log --oneline -1 2>/dev/null || echo none)\"'\"}'; exit 0"
      }]
    }]
  }
}

Tämä lisää nykyisen projektin nimen, Git-haaran ja viimeisimmän commitin jokaiseen istuntoon. Claude saa tämän kontekstin automaattisesti, eikä sinun tarvitse kertoa sille, millä haaralla olet.

5. Suorita testit automaattisesti koodimuutosten jälkeen

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '\\.(ts|tsx|js|jsx|py)$'",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path' /dev/stdin); TEST_FILE=$(echo \"$FILE\" | sed 's/\\.[^.]*$/.test&/'); if [ -f \"$TEST_FILE\" ]; then npx jest \"$TEST_FILE\" --no-coverage 2>&1 | tail -5; fi; exit 0",
        "timeout": 30000
      }]
    }]
  }
}

Jos vastaava testitiedosto on olemassa, se suoritetaan automaattisesti sen jälkeen, kun Claude on muokannut lähdekoodia. tail -5 pitää tulosteen tiiviinä, ja aikakatkaisu estää testisarjoja karkaamasta käsistä. Tämä toimii hyvin yhteen tekoälypohjaisen koodikatselmoinnin kanssa.

6. Haarojen suojauksen pakottaminen (edistynyt)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "tool_input.command matches 'git push.*(main|master|production)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: Direct push to protected branch. Use a feature branch and open a PR.\"}' && exit 2"
      }]
    }]
  }
}

Tämä estää kaikki git push -komennot, jotka kohdistuvat main-, master- tai production-haaroihin. Claude saa palautteen ja ehdottaa sen sijaan ominaisuushaaran luomista.

7. Turvallisuuden auditointiloki (Edistynyt)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "INPUT=$(cat /dev/stdin); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command'); echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] BASH: $CMD\" >> .claude/audit.log; exit 0"
      }]
    }]
  }
}

Kirjaa jokaisen Clauden suorittaman Bash-komennon auditointitiedostoon UTC-aikaleimalla. Korvaamaton turvatarkasteluissa ja sen ymmärtämisessä, mitä Claude todella teki istunnon aikana. Pidä .claude/audit.log .gitignore-tiedostossasi.

Hooks vs MCP vs Skills vs CLAUDE.md: milloin mitäkin käyttää

Käytä hookseja deterministiseen automaatioon, jonka täytyy aina suorittua (muotoilu, estäminen, ilmoitukset). Käytä MCP:tä antaaksesi Claudelle pääsyn ulkoisiin työkaluihin ja dataan. Käytä Skillsiä uudelleenkäytettäviin prompt-paketteihin. Käytä CLAUDE.md-tiedostoa käyttäytymisohjeisiin ja projektikontekstiin. Hooksit ovat taattuja; kaikki muu on probabilistista. Tämä on kaikkein tärkein ero, ja palaan siihen jatkuvasti neuvoessani tiimejä.

Päätösmatriisi

Jos haluat perehtyä MCP:hen syvällisemmin, tutustu MCP-oppaaseemme. Jos tulet Cursorista, Cursorin sääntöjärjestelmä vastaa suunnilleen CLAUDE.md-tiedostoa, mutta Cursorissa ei ole mitään hookseihin verrattavaa.

Kun ne menevät päällekkäin (ja miten valita)

Tässä on käyttämäni päätöspuu:

• "Täytyykö tämän tapahtua joka kerta, poikkeuksetta?", Hook. Muotoile koodi, estä suojatut tiedostot, lähetä ilmoituksia. Nolla epäselvyyttä.
• "Tarvitseeko Claude uuden OMINAISUUDEN, jota sillä ei ole?", MCP-palvelin. Pääsy tietokantaan, API-kutsu, ulkoisten dokumenttien haku.
• "Haluan uudelleenkäytettäviä OHJEITA tiettyä työnkulkua varten?", Skill (slash-komento). Koodikatselmointimallit, käyttöönottotarkistuslistat.
• "Haluan muokata Clauden KÄYTTÄYTYMISTÄ tässä projektissa?", CLAUDE.md. Koodausstandardit, arkkitehtuuripäätökset, suositut kirjastot.

Todelliset esimerkit, jotka selventävät rajaa:

• "Muotoile aina Prettierillä" = Hook (sen täytyy tapahtua joka kerta)
• "Käytä Prettieriä muotoiluun" CLAUDE.md-tiedostossa = Ohjeistus (Claude saattaa unohtaa)
• "Hae yrityksemme dokumenteista" = MCP (uusi ominaisuus)
• "Noudata tyyliopastamme koodia katselmoidessasi" = Skill tai CLAUDE.md

Kuten Anthropicin plugins-julkistuksessa kuvataan, hookit ovat osa laajempaa plugin-ekosysteemiä, johon kuuluvat myös MCP ja Skillit. Ne on suunniteltu täydentämään toisiaan, eivät kilpailemaan.

Aloituspaketti: Valmis Claude Code -hooks-asetus mille tahansa projektille

Claude Coden hooks-aloitusasetuksen tulisi sisältää automaattinen muotoilu tiedostoa muokattaessa, ilmoitus tehtävän valmistumisesta, arkaluonteisten tiedostojen suojaus, istunnon kontekstin injektointi sekä stop-hook siivousta varten. Tämä on juuri se asetus, jonka lisään jokaiseen uuteen projektiin — mukautettuna pinolle, mutta rakenne pysyy samana.

Asetukset

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null)\"' | Node: '\"$(node -v 2>/dev/null)\"'\"}'; exit 0"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\..+|.*lock\\.json|.*lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Protected file. Edit manually.\"}' && exit 2"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; *.go) gofmt -w \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Done\"' /dev/stdin); osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\" 2>/dev/null || notify-send 'Claude Code' \"$MSG\" 2>/dev/null; exit 0"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '[STOP] '\"$(date +%H:%M:%S)\"'' >> .claude/session.log; exit 0"
      }]
    }]
  }
}

Kuinka mukauttaa omaan teknologiapinoosi

Vaihda yllä olevan konfiguraation muotoilu- ja testauskomennot vastaamaan omaa teknologiapinoasi. Rakenne pysyy täysin samana.

Varmista hookien toiminta

Kolme tapaa varmistaa, että hookit ovat aktiivisia:

1. /hooks-komento, Kirjoita /hooks Claude Codessa nähdäksesi kaikki rekisteröidyt hookit, niiden matcherit ja tila.
2. Transkriptin tarkastelu, Kun hook on lauennut, tarkista istunnon transkripti. Hookien suoritukset näkyvät tulosteineen ja poistumiskoodeineen.
3. Nopea kytkin, Lisää \"disableAllHooks\": true settings.json-tiedostoosi poistaaksesi kaikki hookit väliaikaisesti käytöstä poistamatta asetuksia. Poista se (tai aseta arvoksi false) ottaaksesi ne uudelleen käyttöön.

CI/CD-integraatio: Claude Code -koukut headless-tilassa

Claude Code -koukut toimivat headless-tilassa (claude -p) tietyin eroavaisuuksin: Notification-koukut laukeavat edelleen, mutta ne kannattaa ohjata lokitukseen työpöytäilmoitusten sijaan. PreToolUse-koukut paluuarvolla 2 voivat keskeyttää headless-istunnon ihmisen tarkastusta varten. GitHub Actions käyttää anthropics/claude-code-action@v1 -toimintoa koukkujen rinnalla automatisoituja työnkulkuja varten.

Headless-tilan toiminta

Headless-tilan suuri yllätys: PreToolUse-hookit, jotka poistuvat koodilla 2, eivät vain epäonnistu hiljaisesti. Ne keskeyttävät istunnon ja antavat sinun jatkaa --resume-komennolla, mikä tarjoaa human-in-the-loop-mallin CI-putkille.

GitHub Actions -integraatio

Tässä on minimaalinen GitHub Actions -työnkulku, joka käyttää Claude Codea hookien kanssa. Kuten virallisessa GitHub Actions -oppaassa dokumentoidaan:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR and suggest improvements"
    allowed_tools: "Read,Grep,Glob"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

.claude/settings.json-hookisi kulkevat repon mukana, joten ne laukeavat CI:ssä täsmälleen samalla tavalla kuin paikallisesti. Varmista vain, että hookit, jotka nojaavat työpöytäspesifeihin työkaluihin (kuten osascript), sisältävät varapolkuja tai ehdollisia tarkistuksia.

Tiimin hook-hallinta

Tiimeille hyvin toimiva malli:

• .claude/settings.json (commitoitu), tiimin yhteiset hookit: tiedostosuojaus, muotoilijat, haarasuojaus. Kaikki saavat nämä.
• .claude/settings.local.json (gitignoroitu), henkilökohtaiset hookit: ilmoitusasetukset, mukautettu lokitus, kokeelliset hookit.
• ~/.claude/settings.json (käyttäjän globaali), oletusasetuksesi kaikissa projekteissa: ilmoitustyyli, henkilökohtaiset muotoiluasetukset.

Tämä vastaa tapaa, jolla .editorconfig (commitoitu) ja paikalliset IDE-asetukset (henkilökohtaiset) toimivat. Kuten Angelo Liman CI/CD-opas toteaa, tiimit, jotka standardoivat yhteiset hookit, kohtaavat vähemmän "toimii minun koneellani" -ongelmia Claude Coden kanssa.

Claude Code -koukkujen vianmääritys ja yleiset virheet

Yleisiä Claude Code -koukkujen ongelmia ovat muun muassa koukkujen laukeamatta jääminen (tarkista matcherin oikeinkirjoitus ja settings.json-tiedoston sijainti), koukkujen suorittuminen ilman estämistä (väärä poistumiskoodi, käytä 2 äläkä 1), päättymättömät silmukat (Stop-koukku laukaisee itsensä) ja hidas käynnistyminen (liian monta synkronista koukkua). Yleisin virhe, johon törmään, on poistumiskoodien sekoittaminen – kehittäjät käyttävät exit 1, kun tarkoittavat exit 2.

Hook ei laukea

Oireet: Lisäsit hookin, mutta mitään ei tapahdu, kun tapahtuma käynnistyy.

Korjaukset:

• Matcher-kirjoitusvirhe, matcherit ovat kirjainkokoriippuvaisia. \"write\" ei vastaa Write-työkalua. Tarkista tarkat työkalujen nimet komennolla /hooks.
• Väärä asetustiedosto, hookit tiedostossa ~/.claude/settings.json eivät näy /hooks-tulosteessa projektin laajuudella. Kokeile tiedostoa .claude/settings.json projektin juuressa.
• JSON-syntaksivirhe, ylimääräinen pilkku tai puuttuva sulje poistaa hiljaisesti koko hooks-asetuksen käytöstä. Aja settings.json jq . -komennon läpi validoidaksesi sen.
• disableAllHooks: true, tarkista, onko joku (tai aiempi debuggausistunto) jättänyt tämän lipun päälle.

Koukku suoritetaan, mutta ei estä

Oireet: PreToolUse-koukkusi suoritetaan, mutta toiminto jatkuu silti.

Korjaukset:

• Väärä poistumiskoodi, Poistumiskoodi 1 tarkoittaa "virhettä" (koukku epäonnistui), ei "estoa". Käytä exit 2 estääksesi toiminnon. Tämä hämmentää lähes kaikkia, kuten virallisessa dokumentaatiossa todetaan.
• Puuttuva stdout-JSON, Estäville kookuille tulosta JSON-viesti, jotta Claude tietää, miksi toiminto estettiin: echo '{"message": "Blocked: reason"}'

Päättymättömät silmukat

Oireet: Claude yrittää samaa toimintoa yhä uudelleen, tai koneesi kuumenee epäilyttävästi.

Korjaukset:

• Stop-hook laukaisee toimintoja, Jos Stop-hook kirjoittaa tiedoston tai suorittaa komennon, joka saa Clauden vastaamaan, olet luonut silmukan. Stop-hookien tulisi tehdä vain passiivisia asioita: kirjata lokiin, ilmoittaa, siivota.
• PostToolUse-hook aiheuttaa muokkauksia, PostToolUse-hook, joka muokkaa tiedostoa, laukaisee uuden PostToolUse-tapahtuman. Suojaudu tältä tietyillä matchereilla tai if-kentällä.

Suorituskykyongelmat

Oireet: Clauen käynnistyminen tai työkalujen suorittaminen kestää huomattavasti kauemmin.

Korjaukset:

• Liian monta SessionStart-hookia, Jokainen niistä suoritetaan synkronisesti käynnistyksen yhteydessä. Pidä nämä kevyinä (alle 1 sekunti kutakin kohden).
• Raskaat skriptit kuumissa poluissa, PreToolUse- ja PostToolUse-hookit laukeavat tiheästi. Jos skriptisi tekee verkkopyyntöjä tai raskaita laskutoimituksia, lisää timeout-kenttä (millisekunteina) ja harkitse, pitäisikö sen sen sijaan olla HTTP-hookki.
• Ei välimuistia, Jos tarkistat samaa asiaa toistuvasti (kuten "onko tämä suojattu haara?"), tallenna tulos väliaikaistiedostoon sen sijaan, että ajaisit Git-komentoja jokaisella hookin kutsulla.

Usein kysytyt kysymykset

Mitä ovat Claude Code -hookit ja miten ne toimivat?

Claude Code -hookit ovat käyttäjän määrittämiä automaatiokomentosarjoja, jotka suoritetaan tietyissä elinkaaren tapahtumissa Claude Code -istunnon aikana. Ne määritetään settings.json-tiedostossa sovituskuviolla ja käsittelijällä (komentotulkinkomento, HTTP-päätepiste, kehote tai agentti). Kun vastaava tapahtuma laukeaa, hookki käynnistyy automaattisesti ja käyttää poistumiskoodeja tuloksen ohjaamiseen.

Miten määritän hookit Claude Coden settings.json-tiedostossa?

Lisää "hooks"-objekti johonkin kolmesta asetussijainnista: ~/.claude/settings.json (käyttäjän yleiset asetukset), .claude/settings.json (jaetut projektiasetukset) tai .claude/settings.local.json (henkilökohtaiset projektiasetukset). Jokainen tapahtumatyyppi vastaa hook-määritysten taulukkoa, jossa on matcher, valinnainen if-kenttä sekä hooks-taulukko, joka sisältää käsittelijäobjekteja, joissa on type ja command tai url.

Mitä eroa PreToolUse- ja PostToolUse-koukuilla on?

PreToolUse laukeaa ennen työkalun suorittamista ja antaa sinulle mahdollisuuden estää sen poistumiskoodilla 2. PostToolUse laukeaa suorituksen päätyttyä ja on hyödyllinen muotoiluun, testaukseen tai lokitukseen. PreToolUse on tarkoitettu ennaltaehkäisyyn ja portitukseen. PostToolUse on tarkoitettu validointiin ja siivoukseen. Molemmat vastaanottavat työkalun nimen ja syötteen JSON-muodossa stdin-virrassa.

Voiko Claude Coden hookit estää vaaralliset komennot?

Kyllä. PreToolUse-hookit estävät minkä tahansa työkalun suorituksen poistumiskoodilla 2. Voit suojata arkaluonteisia tiedostoja kirjoittamiselta, estää vaarallisia kuvioita vastaavat shell-komennot, kuten rm -rf tai git push main, ja estää pääsyn tuotantotietokantoihin. Estoviesti lähetetään takaisin Claudelle palautteena, jotta se voi mukauttaa lähestymistapaansa.

Mitä hook-tapahtumia Claude Codessa on saatavilla?

Claude Code tarjoaa yli 15 tapahtumaa: PreToolUse ja PostToolUse työkalujen suorittamiseen, Notification hälytyksiin, Stop istunnon päättymiseen, SessionStart alustukseen, UserPromptSubmit syötteen suodattamiseen, PreCompact ja PostCompact kontekstin hallintaan sekä uudempia tapahtumia, kuten ConfigChange, FileChanged, TaskCreated ja PermissionDenied. Katso täydellinen viitetaulukko yllä olevasta hook-tapahtumien osiosta.

Miten hookit eroavat MCP-työkaluista ja Skillseistä?

Hookit ovat deterministisiä – ne laukeavat aina vastaavissa tapahtumissa riippumatta siitä, mitä Claude päättää. MCP-työkalut laajentavat Clauden ominaisuuksia (tietokantayhteydet, API-kutsut), mutta Claude päättää, milloin niitä käytetään. Skillsit ovat uudelleenkäytettäviä ohjepakkauksia, jotka käynnistetään kauttaviivakomennoilla. CLAUDE.md tarjoaa ohjeistusta käyttäytymiseen. Käytä hookeja, kun jonkin asian täytyy tapahtua joka kerta, ja MCP:tä, kun Claude tarvitsee uusia kykyjä.

Toimivatko Claude Code -koukut headless-tilassa?

Kyllä, tietyin varauksin. Koukut käynnistyvät normaalisti headless-tilassa (claude -p), mutta työpöytäkohtaiset koukut, kuten macOS-ilmoitukset, tarvitsevat vararatkaisuja. On tärkeää huomata, että PreToolUse-koukut, jotka päättyvät koodiin 2, voivat keskeyttää headless-istunnot ihmisen hyväksyntää varten --resume-lipun avulla. Tämä mahdollistaa human-in-the-loop CI/CD -putket, joissa tietyt toiminnot edellyttävät manuaalista hyväksyntää.

Kuinka monta hookia on liikaa? Hidastavatko hookit Claude Codea?

Ehdotonta rajaa ei ole, mutta jokainen synkroninen hook lisää viivettä. SessionStart-hookit suoritetaan käynnistyksen yhteydessä, joten pidä ne nopeina (alle 1 sekunti kukin). PreToolUse- ja PostToolUse-hookit laukeavat jokaisella vastaavalla työkalukutsulla, ja raskaat skriptit kasautuvat tässä nopeasti. Suosittelen pitämään hookien kokonaismäärän alle 10–15:ssä, käyttämään if-kenttää soveltamisalan rajaamiseen ja lisäämään timeout-arvoja hallitsemattomien skriptien estämiseksi.

Voinko käyttää hookkeja koodin automaattiseen muotoiluun Prettierillä tai Blackilla?

Kyllä, kyseessä on suosituin hookkien käyttötarkoitus. Luo PostToolUse-hookki, joka vastaa arvoa Write|Edit, poimi tiedostopolku stdin-JSON:stä ja suorita tiedostopäätteen mukainen muotoilija. Tuotantoesimerkkien osion ensimmäinen esimerkki tarjoaa täydellisen, suoraan kopioitavissa olevan konfiguraation, joka käsittelee TypeScript-, JavaScript- ja Python-tiedostoja.

Ovatko Claude Coden hookit turvallisia? Mitä turvallisuusriskejä niihin liittyy?

Hookit toimivat täysillä käyttäjäoikeuksillasi, eikä niissä ole hiekkalaatikkoa. Haitallinen hookki voisi lukea SSH-avaimet, poistaa tiedostoja tai viedä dataa ulos. Käytä vain luotettavista lähteistä peräisin olevia hookeja, tarkista jaetut .claude/settings.json -tiedostot ennen kuin otat ne projektiisi, ja käytä .claude/settings.local.json -tiedostoa henkilökohtaisille hookeille, joita ei tule jakaa. Laajempia tekoälyn turvallisuusmalleja varten katso LLM:n suojakäytäntöjen oppaamme.