Lyhyt yhteenveto: Claude Code -koukut ovat automaatiokomennukset, jotka suoritetaan tiettyinä elinkaaren vaiheina tekoälykoodausistuntojen aikana. Ne antavat kehittäjille mahdollisuuden suorittaa mukautettuja komentoja, validoida toimintoja, muotoilla koodia, lähettää ilmoituksia ja valvoa projektisääntöjä. Nämä koukut integroituvat Claude’n työnkulkuun tapahtumien, kuten SessionStart, PreToolUse ja PostToolUse, kautta, ja tukevat komento-, HTTP- ja kehoteperusteisia suoritustapoja konfiguroitavilla aikakatkaisuilla ja poistumiskoodikäyttäytymisellä.
Claude Code’n koukkujärjestelmä muuttaa tekoälykoodausavustajan hyödyllisestä työkalusta täysin automatisoiduksi kehitysympäristöksi. Useimmat kehittäjät eivät ymmärrä koukkujen kautta saatavan hallinnan laajuutta.
Tässä on se juttu – koukut eivät ole vain skriptien suorittamista tiedostomuokkausten jälkeen. Ne tarjoavat katkeamispisteitä läpi Claude’n koko päätöksentekoprosessin. Ennen kuin se suorittaa komennon. Työkalukutsun epäonnistumisen jälkeen. Kun se tarvitsee lupaa. Jopa ennen käyttäjäkehotteiden käsittelyä.
Tämä opas kattaa kaiken, mitä virallinen dokumentaatio tarjoaa, sekä käytännön malleja, jotka yhteisön keskusteluissa paljastuvat tuotantoympäristöissä todella toimiviksi.
Mitä Claude Code -koukut todella tekevät
Virallisen Claude Code -dokumentaation mukaan koukut ovat käyttäjän määrittelemiä komentokehotteita, HTTP-päätepisteitä tai kehoteinjektioita, jotka suoritetaan tiettyinä aikoina Claude Code’n elinkaaren aikana. Ne vastaanottavat jäsenneltyä JSON-syötettä stdin-syötteen kautta ja ohjaavat työnkulkua poistumiskoodien tai HTTP-vastausten avulla.
Automaatio menee syvemmälle kuin useimmat oppaat antavat ymmärtää. Koukut voivat estää työkalujen suorittamisen kokonaan, injektoida lisäkontekstia Claude’n päättelyyn, käynnistää ulkoisia palveluita ja valvoa validointisääntöjä, joita Claude’n on noudatettava.
Kolme ydinkoukkutyyppiä on olemassa:
- Komentokoukut: Komentotiedostot, jotka kommunikoivat stdoutin, stderrin ja poistumiskoodien kautta
- HTTP-koukut: Etäpäätepisteet, jotka vastaanottavat POST-pyyntöjä ja palauttavat JSON-vastauksia
- Kehotekoukut: Dynaamiset ohjeet, jotka injektoidaan Claude’n kontekstiin tietyissä tapahtumissa
Jokainen tyyppi palvelee erilaisia automaatiomalleja. Komentokoukut käsittelevät paikallista validointia ja muotoilua. HTTP-koukut integroivat ulkoisiin palveluihin ja tietokantoihin. Kehotekoukut muokkaavat Claude’n käyttäytymistä ilman ulkoisia prosesseja.
Koukkujen elinkaari ja tapahtumajärjestelmä
Virallinen dokumentaatio määrittelee useita koukkutapahtumia (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification ja muita), jotka käynnistyvät Claude Code’n suoritusvirran aikana. Ymmärtämällä, milloin kukin käynnistyy, määritetään, mikä automaatio on mahdollista.
| Tapahtuma | Milloin se käynnistyy | Voiko estää |
|---|---|---|
| SessionStart | Kun istunto alkaa tai jatkuu | Ei |
| UserPromptSubmit | Kun lähetät kehotteen, ennen kuin Claude käsittelee sen | Kyllä |
| PreToolUse | Ennen kuin työkalukutsu suoritetaan | Kyllä |
| PermissionRequest | Kun lupavalintaikkuna ilmestyy | Kyllä |
| PostToolUse | Kun työkalukutsu onnistuu | Ei |
| PostToolUseFailure | Kun työkalukutsu epäonnistuu | Ei |
| Notification | Kun Claude Code lähettää ilmoituksen | Ei |
| SubmitMessage | Kun Claude lähettää viestin käyttäjälle | Ei |
| ContextCompaction | Kun konteksti-ikkuna lähestyy rajoja | Ei |
Estokyky on tärkein. PreToolUse-koukut voivat estää vaaralliset toiminnot ennen niiden suorittamista. Poistumiskoodi 1 estää toimenpiteen. Poistumiskoodi 0 sallii sen. Poistumiskoodi 2 pyytää Claudea harkitsemaan uudelleen.
Mutta odota. PostToolUse-koukut eivät voi peruuttaa toimintoja, koska työkalu on jo suoritettu. Tämä rajoitus muokkaa, miten validointilogiikka rakentuu. Kriittiset tarkistukset kuuluvat PreToolUse-tapahtumaan. Puhdistus ja muotoilu kuuluvat PostToolUse-tapahtumaan.
Selaa tekoälytyökalujen etuja asentaessasi Claude Codea
Jos työskentelet Claude Code -koukkujen kanssa, saatat myös valita muita tekoälytyökaluja työnkulkuusi. Get AI Perks kerää startup-luottoja ja ohjelmistotarjouksia tekoäly- ja pilvityökaluille yhdestä paikasta. Alusta sisältää yli 200 tarjousta, joissa on etujen ehdot ja lunastusohjeet kullekin.
Etsitkö Claude- tai muita tekoälytyökalujen etuja?
Tarkista Get AI Perks, jotta voit:
- selata Claude- ja muita tekoälytyökalujen tarjouksia
- vertailla etujen ehtoja ennen hakemista
- löytää startup-alennuksia työkalupakettiisi
👉 Vieraile Get AI Perksissä tutustuaksesi nykyisiin tekoälyohjelmistojen etuihin.
Konfiguraatio ja tiedostorakenne
Koukut määritellään projektin .claude/settings.json -tiedostossa. Konfiguraatioskeema tukee globaaleja koukkuja ja työkalu-kohtaisia vastaavuuksia, jotka suodattavat, milloin koukut suoritetaan.
Peruskomentokoukun rakenne:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
`${file}`-muuttuja laajenee työkalun syötteestä tulevaksi todelliseksi tiedostopoluksi. Virallisen dokumentaation mukaan koukut tukevat näitä muuttujalaajennuksia komento- ja args-kentissä.
Koukkujen sijaintihierarkia
Claude Code tarkistaa useita sijainteja koukkumäärityksiä varten selkeällä etusijajärjestyksellä:
- Projektitaso: .claude/settings.json nykyisessä työtilassa
- Käyttäjätaso: ~/.claude/settings.json kaikille istunnoille
- Lisäosien tarjoamat: Asennettujen lisäosien mukana tulevat koukut
Projektikoukut ohittavat käyttäjäkoukut samalle tapahtumalle. Tämä mahdollistaa projektikohtaisten muotoilusääntöjen luomisen samalla, kun globaalit ilmoituskäsittelijät säilyvät.
Vastaavuusmallit valikoivaan suoritukseen
Vastaavuusjärjestelmä suodattaa koukut tietyille työkaluille tai ehdoille. Ilman vastaavuuksia koukut käynnistyvät jokaiselle tapahtumalleen.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
`pathPattern`-kenttä hyväksyy glob-syntaksin. `toolName`-kenttä vastaa Claude’n sisäänrakennettuja työkaluja, kuten edit_file, execute_command, read_file ja create_directory.
Yhteisön keskustelut paljastavat, että vastaavuusyhdistelmät toimivat AND-logiikalla. Kaikkien määritettyjen vastaavuuksien on täytyttävä, jotta koukku suoritetaan.
Komentokoukut: Komentotiedostojen integrointi
Komentokoukut suorittavat komentotiedostoja tai komentosarjoja jäsennellyllä JSON-syötteellä. Ne edustavat yleisintä koukkutyyppiä paikalliselle automaatiolle.
Virallinen dokumentaatio määrittelee, että komentokoukut vastaanottavat JSON-tiedostoa stdin-syötteen kautta seuraavalla rakenteella:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skriptit jäsentävät tämän syötteen päätösten tekemiseksi. Python-validointikoukku voisi näyttää tältä:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Poistumiskoodi 0 sallii toiminnon. Poistumiskoodi 1 estää sen ja näyttää stderr-viestin Claudelle. Poistumiskoodi 2 käynnistää erityiskäyttäytymistä tapahtumasta riippuen.
Poistumiskoodin 2 käyttäytyminen
Virallisen koukkujen viitedokumentaation mukaan poistumiskoodilla 2 on tapahtumakohtainen merkitys (PreToolUse: estää ja pyytää harkitsemaan uudelleen; UserPromptSubmit: tarjoaa kontekstia estämättä; PermissionRequest: estää luvan pyytämisen):
- PreToolUse: Estää työkalun ja pyytää Claudea harkitsemaan uudelleen stderr-viestiä kontekstina
- UserPromptSubmit: Tarjoaa stderr-ulostulon lisäkontekstina estämättä
- PermissionRequest: Estää luvan myöntämisen
Tämä luo keskitien kovan estämisen ja sallimisen välille. Claude saa palautetta siitä, miksi toimenpide voi olla ongelmallinen, ja voi mukauttaa lähestymistapaansa.
Asynkroniset komentokoukut
`async: true`-lippu suorittaa koukut taustalla estämättä Claude’n työnkulkua. Tämä on tärkeää hitaille toiminnoille, kuten käyttöönottoilmoituksille tai metriikan keräämiselle.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Kun asynkroninen koukku käynnistyy, Claude Code aloittaa prosessin ja jatkaa välittömästi. `timeout`-kenttä asettaa maksimisuoritusajan sekunneissa. Jos sitä ei ole määritetty, asynkroniset koukut käyttävät 10 minuutin oletusaikakatkaisua.
Rehellisesti sanottuna asynkroniset koukut eivät voi estää toimintoja, koska ne suoritetaan sen jälkeen, kun Claude on edennyt. Ne toimivat lokitukseen, ilmoituksiin ja siivoukseen – eivät validointiin.
HTTP-koukut: Ulkoisten palveluiden integrointi
HTTP-koukut lähettävät JSON-payloadteja etäpäätepisteisiin ja jäsentävät vastauksia päätöksenteon hallintaan. Ne mahdollistavat integroinnin validointipalveluihin, tietokantoihin ja kolmannen osapuolen työkaluihin.
Perus HTTP-koukun konfiguraatio:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Payload-rakenne vastaa komentokoukkujen syötettä, mutta se toimitetaan POST-pyynnön rungossa. Vastaus määrittää Claude’n seuraavan toimenpiteen.
HTTP-vastauksen käsittely
Virallisen dokumentaation mukaan HTTP-koukut tulkitsevat vastauksia tila- ja runkokoodin perusteella:
| Tila-koodi | Vaikutus | Viestin lähde |
|---|---|---|
| 200 | Salli toiminto | Vastausrunko (valinnainen) |
| 400 | Estä toiminto | Claude’lle näytetty vastausrunko |
| 500 | Koukkuvirhe, sallii toiminnon | Kirjattu, mutta ei näytetty Claudelle |
| Muu | Salli toiminto | Koukkujen epäonnistuminen ei estä työnkulkua |
Vastausrunko voi sisältää `message`-kentän, jonka Claude näkee kontekstina. Tämä mahdollistaa validointipalveluiden selittää, miksi toiminto estettiin.
Ympäristömuuttujien interpolointi
HTTP-koukut tukevat `${VAR}`-syntaksia URL-, header- ja muissa merkkijonokentissä. Muuttujat laajenevat ympäristöstä, jossa Claude Code toimii.
Virallisen MCP-dokumentaation mukaan ympäristömuuttujien laajennus sisältää oletusarvoisen varasyntaksin: `${VAR:-default}` laajenee VAR-arvoksi, jos se on asetettu, muuten käytetään oletusarvoa.
Turvallisuusrajoitus: GitHub-ongelman #28044 mukaan HTTP-koukut voivat käyttää vain `allowedEnvVars`-konfiguraatiokentässä erikseen lueteltuja ympäristömuuttujia. Tämä estää vahingossa tapahtuvan tunnistetietojen paljastumisen.
Kehotekoukut: Kontekstin injektointi
Kehotekoukut injektoivat dynaamisia ohjeita Claude’n kontekstiin tietyissä tapahtumissa. Ne muokkaavat käyttäytymistä ilman ulkoisia prosesseja tai API-kutsuja.
| { “event”: “SessionStart”, “prompt”: “Työskentelet TypeScript-projektin parissa. Käytä aina tiukkoja null-tarkistuksia ja suosi async/awaitia promisejen sijaan.” } |
Injektoitu teksti tulee osaksi Claude’n järjestelmäohjeita kyseiselle istunnolle. Kehotekoukut voivat myös käyttää mallimuuttujia, jotka laajenevat tapahtumatiedoista.
Dynaaminen kehoteiden luonti
Virallisen dokumentaation mukaan kehotekoukut tukevat komento-kenttiä, jotka luovat dynaamisia kehotteita:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Komento vastaanottaa standardin JSON-syötteen stdin-syötteen kautta ja lähettää kehote-tekstin stdout-syötteeseen. Tämä mahdollistaa kontekstitietoisen ohjeiden luomisen projektin tilan perusteella.
Agenttipohjaiset koukut
Agenttikoukut määrittelevät alagentin, joka käsittelee tapahtuman suoran kehoteinjektion sijaan. Alagentti saa tietoa tapahtumasta ja voi suorittaa monivaiheista päättelyä.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Työkalukutsu epäonnistui. Analysoi virhe ja ehdota korjauksia.” } |
Nimetty alagentti on määriteltävä projektikonfiguraatiossa. Agenttikoukut mahdollistavat monimutkaisen päätöksenteon logiikan, jota yksinkertainen kehoteinjektio ei voi tarjota.
Käytännön koukkumallit
Yhteisön keskustelut ja viralliset esimerkit paljastavat erityisiä automaatiomalleja, jotka toimivat luotettavasti tuotannossa.
Koodin automaattinen muotoilu muokkausten jälkeen
Yleisin malli muotoilee koodin automaattisesti sen jälkeen, kun Claude muokkaa tiedostoja:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
`${toolInput.path}`-muuttuja laajenee muokattuun tiedostopolkuun. PostToolUse varmistaa, että muotoilu tapahtuu onnistuneiden muokkausten jälkeen, mutta ei estä Claude’n työnkulkua.
Suojattujen tiedostojen muokkausten estäminen
PreToolUse-koukut valvoivat tiedostonsuojaussääntöjä:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skripti validoi kohdepolun suojattuihin malleihin ja poistuu koodilla 1 estääkseen kielletyt muokkaukset.
Saat ilmoituksen, kun Claude tarvitsee syötettä
Virallisen työnkulkuoppaan mukaan ilmoituskoukut voivat käynnistää työpöytähälytyksiä tai lähettää viestejä ulkoisiin palveluihin:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Tämä käynnistyy aina, kun Claude Code lähettää ilmoituksen, mukaan lukien odottaessaan käyttäjän syötettä tai tehtävän suorittamisen jälkeen.
Kontekstin uudelleeninjektointi tiivistämisen jälkeen
ContextCompaction-koukut palauttavat tärkeän kontekstin, kun keskusteluikkuna täyttyy:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Komennon ulostulo injektoidaan takaisin Claude’n kontekstiin tiivistämisen jälkeen, kun vanhemmat viestit poistetaan. Tämä estää kriittisten projektikohtaisten ohjeiden menetyksen.
Konfiguraatiomuutosten auditointi
Seuraa, milloin Claude muokkaa konfiguraatiotiedostoja:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asynkroninen suoritus estää Claude’n estämisen git-toimintojen valmistuessa. Tämä luo auditointijäljen konfiguraatiomuutoksista ilman manuaalista pysäytystä.
JSON-ulostulo ja päätöksenteon hallinta
Komentokoukut voivat lähettää jäsenneltyä JSON-tietoa antaakseen yksityiskohtaista palautetta pelkkien poistumiskoodien lisäksi. Virallisen viitteen mukaan JSON-ulostulo mahdollistaa monikenttäiset vastaukset, joita Claude tulkitsee päätöksentekoa varten.
| { “allowed”: false, “message”: “Tämä tiedosto on tiimikäytäntöjen suojaama”, “suggestion”: “Luo uusi tiedosto src/features/-kansioon sen sijaan” } |
`allowed`-kenttä määrittää, eteneekö toimenpide. `message`-kenttä näkyy Claudelle kontekstina. `suggestion`-kenttä tarjoaa vaihtoehtoisia lähestymistapoja.
Jotta koukut voivat tuottaa JSON-tietoa, niiden on:
- Kirjoitettava kelvollista JSON-tietoa stdout-syötteeseen
- Poistuttava koodilla 0 (sallittu) tai 1 (estetty)
- Sisällettävä vähintään `allowed`-boolean-kenttä
Claude Code jäsentää JSON-tiedon ja käyttää sitä palautesilmukan parantamiseen. Poistumiskoodit määrittävät edelleen ensisijaisen päätöksen, mutta JSON tarjoaa rikkaamman kontekstin.
Koukun syötekenttien viite
Kaikki koukut vastaanottavat JSON-objektin stdin-syötteen kautta, joka sisältää yhteisiä kenttiä sekä tapahtumakohtaisia tietoja. Täydellisen skeeman ymmärtäminen mahdollistaa kehittyneemmän koukkulogiikan.
Yleiset syötekentät
Jokainen koukku vastaanottaa nämä peruskentät:
- event: Koukkutapahtuman nimi (esim. “PreToolUse”)
- sessionId: Nykyisen Claude-istunnon yksilöllinen tunniste
- turnId: Nykyisen keskustelukierroksen tunniste
- timestamp: ISO 8601 -aikaleima, kun tapahtuma käynnistyi
Työkalutapahtumakentät
PreToolUse, PostToolUse ja PostToolUseFailure -tapahtumat sisältävät:
- toolName: Kutsuttavan työkalun nimi (edit_file, execute_command jne.)
- toolInput: Objekti, joka sisältää työkalun syöteparametrit
- toolResponse: Työkalun ulostulodata (vain PostToolUse)
- error: Virhetiedot, mukaan lukien viesti ja koodi (vain PostToolUseFailure)
`toolInput`-rakenne vaihtelee työkaluittain. `edit_file`-työkalulla se sisältää polun ja sisällön. `execute_command`-työkalulla se sisältää komennon ja argumentit.
Lupatapahtumakentät
PermissionRequest-tapahtumat sisältävät:
- permissionType: Pyydetyn luvan tyyppi (file_write, command_execute jne.)
- requestedAction: Laitetta vaativa tietty toimenpide
- resourcePath: Tiedostopolku tai resurssitunniste, johon toimenpide vaikuttaa
MCP-työkalukoukut
Virallisen koukkujen viitteen mukaan koukut voivat vastaavuusmallia `mcpTool` käyttäen vastaamaan Model Context Protocol (MCP) -työkaluja. Tämä mahdollistaa koukkujen suorittamisen, kun Claude käyttää MCP-palvelimien tarjoamia ulkoisia työkaluja.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
`mcpTool`-arvo vastaa työkalun nimeä muodossa palvelin-nimi/työkalun-nimi. Tämä mahdollistaa validointilogiikan tietokantakyselyille, API-kutsuille tai muille ulkoisille toiminnoille.
GitHubin ominaisuuspyynnöt osoittavat kasvavaa kiinnostusta syvempään MCP-integraatioon, mukaan lukien koukkuihin, jotka voivat tarkastella MCP-palvelimen ilmoituksia ja reagoida ulkoisiin tapahtumiin.
Turvallisuusnäkökohdat
Koukut suoritetaan samoilla oikeuksilla kuin Claude Code itse. Tämä luo turvallisuusriskejä monen käyttäjän ympäristöissä ja jaetuissa konfiguraatioissa.
Komentojen suorituksen hiekkalaatikko
GitHub-ongelman #28044 mukaan HTTP-koukut kulkevat hiekkalaatikon välityspalvelimen kautta, joka rajoittaa verkkoyhteyksiä ja suodattaa ympäristömuuttujia. Komentokoukuilla ei ole tällaisia rajoituksia – ne suoritetaan täydellä komentorivillä.
Dokumentaatio suosittelee seuraavia käytäntöjä:
- Älä koskaan tallenna tunnistetietoja komentoihin
- Käytä ympäristömuuttujia arkaluonteisille tiedoille
- Validoi kaikki syöte `${…}`-laajennuksista
- Toteuta aikakatkaisurajat ulkoisille palveluille
- Käytä asynkronisia koukkuja ei-kriittisille toiminnoille estämisen välttämiseksi epäonnistumisen sattuessa
Koukkujen suorituksen eristäminen
Käyttäjätason koukut tiedostossa ~/.claude/settings.json koskevat kaikkia projekteja. Tämä luo riskejä työskenneltäessä eri luottamusrajojen yli. Projektitason koukut ohittavat käyttäjäkoukut, mutta eivät voi poistaa niitä kokonaan.
Claude Code’n `/hooks`-valikko näyttää kaikki aktiiviset koukut nykyiselle istunnolle. Tämän luettelon tarkistaminen ennen arkaluontoisten projektien kanssa työskentelyä auttaa tunnistamaan mahdolliset turvallisuushuolenaiheet.
Vianmääritys ja ongelmanratkaisu
Koukkujen epäonnistumiset eivät aina näy selkeästi Claude’n keskustelussa. Virallinen dokumentaatio tarjoaa useita vianmääritystapoja.
Koukkujen suorituslokit
Claude Code kirjaa koukkujen suorittamisen istunnon virheenkorjausulostuloon. Vianmääritysoppaan mukaan virheenkorjauslokituksen käyttöönotto paljastaa:
- Mitkä koukut vastaavat kutakin tapahtumaa
- JSON-syöte, joka lähetettiin kullekin koukulle
- Komentoprosessien stdout- ja stderr-ulostulo
- Poistumiskoodit ja suoritusaika
- HTTP-vastaukset ja rungot HTTP-koukkuille
Ota virheenkorjauslokitus käyttöön asettamalla CLAUDE_DEBUG=1 ympäristöön ennen Claude Code’n käynnistämistä.
Koukkujen itsenäinen testaus
Komentokoukut voidaan testata Claude Code’n ulkopuolella rakentamalla JSON-syöte manuaalisesti:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Tämä validoi koukkulogiikan ilman, että Claude-toiminnot todella käynnistyvät. Poistumiskoodin ja stdout/stderr-ulostulon tulisi vastata odotettua käyttäytymistä.
Yleiset koukkujen epäonnistumiset
Yhteisön keskustelut tunnistavat nämä yleiset ongelmat:
- Aikakatkaisuvirheet: Oletus 10 minuutin aikakatkaisu liian lyhyt hitaalle toiminnalle – lisää `timeout`-kentällä
- Polun laajennusvirheet: Muuttujat kuten `${file}` määrittelemättömiä tapahtumissa, jotka eivät sisällä tiedostokontekstia
- Oikeusvirheet: Koukkuskripteillä ei ole suoritusoikeuksia – suorita `chmod +x script.sh`
- JSON-jäsentelyvirheet: Virheellinen JSON-ulostulo koukuista – validoi `jq`-työkalulla ennen palautusta
- Ympäristömuuttujien puuttuminen: Muuttujat eivät välity koukkutiedostoon – tarkista Claude Code’n ympäristö
Koukkujen suorituskykyvaikutukset
Synkroniset koukut estävät Claude’n työnkulun valmistumiseen asti. Oletus 10 minuutin aikakatkaisu estää loputtomat jäätymiset, mutta jopa lyhyet viiveet kertyvät useiden toimintojen aikana.
Käytännön kokemukset kertovat, että yksinkertaisilla validointikoukuilla on merkityksetön suorituskykyvaikutus. Tiedostomuotoilukoukut aiheuttavat havaittavan, mutta hyväksyttävän suorituskykyvaikutuksen. Ulkoiset API-kutsut voivat aiheuttaa kitkaa työnkulussa. Raskaat laskentatoiminnot hyötyvät asynkronisesta suorituksesta.
Koukkujen eräajo
Useat koukut voivat vastata samaan tapahtumaan. Viitedokumentaation mukaan koukut suoritetaan peräkkäin määritysjärjestyksessä. Jos jokin koukku estää toiminnon, jäljellä olevat koukut eivät suoritu.
Tämä on tärkeää suorituskyvyn kannalta. Viisi synkronista koukkua, jotka kestävät 200 ms kukin, lisäävät yhden sekunnin per tapahtuma. Samankaltaisten validointien yhdistäminen yhteen koukkuun vähentää ylikuormitusta.
Edistyneet mallit
Perusautomaation lisäksi koukut mahdollistavat monimutkaisen työnkulun räätälöinnin.
Tilatiedot koukkuketjut
Koukut voivat ylläpitää tilaa suoritusten välillä käyttämällä tiedostoja tai tietokantoja. PostToolUse-koukku voi kirjata onnistuneet toiminnot, joita PreToolUse-koukku myöhemmin validoi:
| #!/bin/bash # Kirjaa onnistuneet muokkaukset echo “${toolInput.path}” >> .claude/edit-history.txt |
Tukeva PreToolUse-koukku voisi tarkistaa tämän historian estääkseen tarpeettomat toiminnot tai valvoakseen järjestysrajoituksia.
Ehdollinen koukkujen aktivointi
Ympäristömuuttujat ohjaavat koukkujen käyttäytymistä ajon aikana. `CLAUDE_SKIP_HOOKS=1`-asetus poistaa koukut käytöstä hätätilanteita varten.
Koukut itse voivat tarkistaa ympäristölippuja:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Käytä tiukkaa validointia exit 1 fi exit 0 |
Tämä mahdollistaa kehitystilan tai tuotantotilan käyttäytymisen ilman konfiguraatiomuutoksia.
Monivaiheinen validointi
PreToolUse-koukut voivat toteuttaa monitasoisen validoinnin, jossa poistumiskoodi 2 antaa Claude’n jatkaa varoituksilla:
- Kovat virheet (poistumiskoodi 1): Estää vaaralliset toiminnot
- Pehmeät varoitukset (poistumiskoodi 2): Hälyttää Claude’ta harkitsemaan uudelleen
- Passi kontekstin kanssa (poistumiskoodi 0 + JSON): Tarjoaa lisätietoja
Tämä luo validointispektrin, joka on hienovaraisempi kuin binäärinen sallia/kieltää.
Integrointi CI/CD:hen
Virallisen alustaintegraatiodokumentaation mukaan Claude Code toimii CI/CD-ympäristöissä automatisoidun koodin tarkistuksen ja ongelmien käsittelyn varmistamiseksi. Koukut laajentavat tätä automaatiota.
GitHub Actions -työnkulut voivat määrittää koukkuja, jotka valvovat tiimin käytäntöjä automatisoitujen istuntojen aikana:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
`STRICT_MODE`-lippu aktivoi ehdollisen validointilogiikan koukkuskripteissä. Tämä varmistaa, että automatisoidut istunnot noudattavat tiukempia sääntöjä kuin interaktiivinen kehitys.
Auditointijäljen luonti
CI-ympäristöjen PostToolUse-koukut luovat yksityiskohtaisia auditointilokeja kaikista Claude-toiminnoista:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Taustalokitus ei vaikuta suorituskykyyn, mutta tarjoaa täydellisen toimintahistorian vaatimustenmukaisuuden ja vianmäärityksen kannalta.
The /hooks Menu
Claude Code tarjoaa `/hooks`-komennon, joka näyttää kaikki aktiiviset koukut nykyiselle istunnolle. Virallisen dokumentaation mukaan tämä valikko näyttää:
- Koukkutapahtuman tyyppi
- Vastaavuusmallit
- Komento tai URL-päätepiste
- Onko koukku asynkroninen
- Konfiguraation lähde (projekti, käyttäjä tai lisäosa)
Koukun valitseminen näyttää sen täydellisen konfiguraation ja antaa mahdollisuuden poistaa sen käytöstä väliaikaisesti nykyiselle istunnolle.
Koukkujen poistaminen käytöstä tai poistaminen
Koukkuja voidaan poistaa käytöstä ilman konfiguraation poistamista lisäämällä `"enabled": false` koukkumääritykseen. Tämä säilyttää konfiguraation estäen samalla suorituksen.
Jos haluat poistaa koukun pysyvästi, poista sen merkintä asianmukaisesta settings.json-tiedostosta. Muutokset tulevat voimaan seuraavan istunnon uudelleenkäynnistyksen yhteydessä tai kun `/reload` suoritetaan.
Koukut taidoissa ja agenteissa
Virallisen dokumentaation mukaan taitojen tai alagenttien konfiguraatioiden sisällä määritellyt koukut pätevät vain kyseisen taidon tai agentin suorittaessa. Tämä mahdollistaa erikoistuneen automaation tiettyjä työnkulkuja varten.
Debuggaava alagentti voi sisältää koukkuja, jotka kirjaavat kaikki työkalukutsut:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Nämä koukut käynnistyvät vain debuggaaja-agentin istunnoissa, eivät normaalissa Claude Code -käytössä.
Viittaa skripteihin polun avulla
Komentokoukut tukevat sekä suhteellisia että absoluuttisia polkuja. Suhteelliset polut ratkeavat projektin juuresta, jossa Claude Code toimii.
Yhteisön keskustelujen parhaat käytännöt:
- Tallenna koukkuskriptit .claude/hooks/-hakemistoon
- Käytä kuvaavia nimiä: validate-typescript.sh, ei hook1.sh
- Tee skripteistä suoritettavia: chmod +x .claude/hooks/*.sh
- Sisällytä shebang-rivi: #!/usr/bin/env bash tai #!/usr/bin/env python3
- Lisää virheenkäsittely `set -e`-komennolla bash-skripteissä
Tulevaisuuden koukkuominaisuudet
GitHubin ominaisuuspyynnöt paljastavat suunniteltuja ja pyydettyjä koukkujen parannuksia:
- Inline-skriptikoukut: Määritä koukkulogiikka suoraan settings.json-tiedostossa ilman ulkoisia tiedostoja
- MCP-työkalujen integraatio: Kutsu MCP-palvelintyökaluja koukuista komentotiedostojen sijaan
- Monen agentin yhteistyö: Koukut, jotka koordinoivat Claude-instanssien välillä eri koneilla
- Parannettu tyypitys: TypeScript-tyyppimääritykset koukkujen syöte-/ulostuloskeemoille
GitHub-ongelman #4274 mukaan pyyntö integroiduista koukkutyypeistä (MCP-työkalu, inline-skripti, API-kutsu) pyrkii yksinkertaistamaan konfiguraatiota ja parantamaan kehittäjäkokemusta.
Usein kysytyt kysymykset
Voivatko koukut estää Claudea suorittamasta vaarallisia komentoja?
Kyllä. PreToolUse-koukut voivat estää minkä tahansa työkalun suorittamisen poistumalla koodilla 1. Tämä sisältää tiedostomuokkaukset, komennon suorittamisen ja MCP-työkalukutsut. Koukku vastaanottaa täydellisen työkalusyötteen ja voi validoida minkä tahansa kriteerin mukaan ennen toiminnon sallimista.
Miten voin korjata koukun, joka ei toimi?
Ota virheenkorjauslokitus käyttöön asetuksella CLAUDE_DEBUG=1 ennen Claude Code’n käynnistämistä. Tarkista istuntolokit koukkujen suoritusyksityiskohdista, mukaan lukien mitkä koukut vastasivat, lähetetty JSON-syöte, stdout/stderr-ulostulo ja poistumiskoodit. Testaa koukkuja itsenäisesti syöttämällä näyte-JSON-tietoa koukkuskriptille.
Toimivatko koukut kaikilla Claude Code -alustoilla?
Koukut toimivat komentorivillä, työpöytäsovelluksessa ja VS Code -lisäosassa. Virallisen dokumentaation mukaan koukut suoritetaan aina, kun Claude Code toimii ja sillä on pääsy tiedostojärjestelmään. Selainpohjaiset Claude- ja mobiilisovellukset eivät tue koukkuja hiekkalaatikkorajoitusten vuoksi.
Voivatko koukut muokata Claude’n vastauksia tai käyttäytymistä?
Kehotekoukut injektoivat ohjeita, jotka vaikuttavat Claude’n käyttäytymiseen. Agenttikoukut delegoivat tapahtumien käsittelyn erikoistuneisiin alagentteihin. Koukut eivät kuitenkaan voi suoraan muokata Claude’n tuottamaa tekstiä tai päättelyprosessia – ne toimivat tarjoamalla kontekstia ja estämällä toimintoja.
Mikä on ero asynkronisten ja synkronisten koukkujen välillä?
Synkroniset koukut estävät Claude’n työnkulun valmistumiseen tai aikakatkaisuun asti. Asynkroniset koukut suoritetaan taustalla estämättä. Synkroniset koukut voivat estää toimintoja poistumiskoodien avulla. Asynkroniset koukut eivät voi estää, koska Claude jatkaa ennen kuin koukku valmistuu. Käytä asynkronisia lokitukseen ja ilmoituksiin, synkronisia validointiin.
Miten voin jakaa koukkuja tiimin kanssa?
Vientitiedostoon `.claude/settings.json`-tiedosto versionhallintaan. Projektitason koukut koskevat kaikkia tiimin jäseniä, jotka kloonaavat arkiston. Organisaatiotason käytäntöjä varten tiimit voivat ylläpitää jaettua käyttäjätason asetustiedostoa, jonka jäsenet kopioivat tiedostoon `~/.claude/settings.json`.
Voivatko HTTP-koukut kutsua sisäisiä API-rajapintoja palomuurien takana?
Kyllä, jos Claude Code toimii ympäristössä, jolla on verkkoyhteys näihin API-rajapintoihin. HTTP-koukut tekevät tavallisia POST-pyyntöjä Claude Codea ajavalta koneelta. Yritysverkkopalomuurit ja VPN-yhteydet toimivat normaalisti. Dokumentaatiossa mainittu hiekkalaatikon välityspalvelin hallitsee ympäristömuuttujien paljastumista, ei verkkoreititystä.
Lisäävätkö koukut Claude Code’n merkkiaineiden käyttöä?
Kehotekoukut injektoivat tekstiä Claude’n kontekstiin, mikä kuluttaa merkkiaineita. Komento- ja HTTP-koukut eivät vaikuta suoraan merkkiaineiden käyttöön, mutta niiden ulostulo (virheviestit, ehdotukset) tulee osaksi keskustelujen kontekstia. Poistumiskoodi 2 selittävillä viesteillä lisää kontekstia kuin poistumiskoodi 1 pelkällä estämisellä.
Yhteenveto
Claude Code -koukut muuttavat tekoälyavustajan tehokkaasta työkalusta täysin automatisoiduksi kehitysalustaksi. Tapahtumajärjestelmä tarjoaa katkeamispisteitä läpi Claude’n työnkulun – istunnon alusta aina kontekstin tiivistämiseen asti.
Komentokoukut hoitavat paikallisen validoinnin ja muotoilun. HTTP-koukut integroivat ulkoisia palveluita ja tietokantoja. Kehotekoukut muokkaavat käyttäytymistä kontekstin injektoinnin avulla. Yhdessä nämä mahdollistavat automaatiomallit, jotka valvovat tiimin käytäntöjä, ylläpitävät koodin laatua ja integroituvat olemassa olevaan kehitysinfrastruktuuriin.
Vastaavuusjärjestelmä suodattaa koukut tietyille työkaluille ja tiedostomalleille. Poistumiskoodit ja JSON-ulostulo ohjaavat päätöksentekoa. Asynkroninen suoritus estää hidastoimintojen estymisen. Täysi konfiguraatioskeema tukee kaikkea yksinkertaisesta automaattisesta muotoilusta monimutkaiseen monivaiheiseen validointiin.
Aloita yksinkertaisilla PostToolUse-koukuilla koodin muotoiluun. Lisää PreToolUse-validointia käytäntöjen kehittyessä. Kokeile kehotekoukkuja käyttäytymisen muokkaamiseen. Rakenna HTTP-integraatioita tiimilaajuiseen valvontaan.
Tarkista virallisesta Claude Code -dokumentaatiosta täydellinen koukkujen viite ja päivitetty konfiguraatioskeema uusien ominaisuuksien julkaisun myötä.
