Ringkasan Pantas: Claude Code hooks ialah skrip automasi yang dilaksanakan pada titik kitaran hayat tertentu semasa sesi pengekodan AI, membolehkan pembangun menjalankan arahan tersuai, mengesahkan tindakan, memformat kod, menghantar pemberitahuan dan menguatkuasakan peraturan projek. Cangkuk ini berintegrasi dengan aliran kerja Claude melalui peristiwa seperti SessionStart, PreToolUse, dan PostToolUse, menyokong corak pelaksanaan berasaskan arahan, berasaskan HTTP, dan berasaskan gesaan dengan tamat masa yang boleh dikonfigurasi dan tingkah laku kod keluar.
Sistem cangkuk Claude Code mengubah pembantu pengekodan AI daripada alat yang berguna kepada persekitaran pembangunan yang automatik sepenuhnya. Kebanyakan pembangun tidak menyedari tahap kawalan yang tersedia melalui cangkuk.
Inilah perkara sebenarnya—cangkuk bukan sekadar tentang menjalankan skrip selepas edit fail. Ia menyediakan titik persisian sepanjang proses pembuatan keputusan Claude yang lengkap. Sebelum ia melaksanakan arahan. Selepas panggilan alatan gagal. Apabila ia memerlukan kebenaran. Malah sebelum memproses gesaan pengguna.
Panduan ini merangkumi semua yang disediakan oleh dokumentasi rasmi, ditambah dengan corak praktikal yang didedahkan oleh perbincangan komuniti yang benar-benar berfungsi dalam persekitaran pengeluaran.
Apa yang Sebenarnya Dilakukan oleh Claude Code Hooks
Menurut dokumentasi rasmi Claude Code, cangkuk ialah arahan shell yang ditakrifkan pengguna, titik akhir HTTP, atau suntikan gesaan yang dilaksanakan pada titik tertentu dalam kitaran hayat Claude Code. Ia menerima input JSON berstruktur melalui stdin dan mengawal aliran kerja melalui kod keluar atau respons HTTP.
Automasi berjalan lebih dalam daripada kebanyakan panduan yang dicadangkan. Cangkuk boleh menyekat pelaksanaan alatan sepenuhnya, menyuntik konteks tambahan ke dalam penaakulan Claude, mencetuskan perkhidmatan luaran, dan menguatkuasakan peraturan pengesahan yang Claude mesti patuhi.
Tiga jenis cangkuk teras wujud:
- Cangkuk arahan: Skrip shell yang berkomunikasi melalui stdout, stderr, dan kod keluar
- Cangkuk HTTP: Titik akhir jauh yang menerima permintaan POST dan mengembalikan respons JSON
- Cangkuk gesaan: Arahan dinamik yang disuntik ke dalam konteks Claude pada peristiwa tertentu
Setiap jenis melayani corak automasi yang berbeza. Cangkuk arahan menguruskan pengesahan dan pemformatan tempatan. Cangkuk HTTP berintegrasi dengan perkhidmatan dan pangkalan data luaran. Cangkuk gesaan mengubah tingkah laku Claude tanpa proses luaran.
Sistem Kitar Hayat dan Peristiwa Cangkuk
Dokumentasi rasmi mentakrifkan pelbagai peristiwa cangkuk (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, dan lain-lain) yang ditembak semasa aliran pelaksanaan Claude Code. Memahami bila setiap satu ditembak menentukan automasi yang mungkin.
| Peristiwa | Bila Ia Ditembak | Boleh Sekat |
|---|---|---|
| SessionStart | Apabila sesi bermula atau bersambung semula | Tidak |
| UserPromptSubmit | Apabila anda menyerahkan gesaan, sebelum Claude memprosesnya | Ya |
| PreToolUse | Sebelum panggilan alatan dilaksanakan | Ya |
| PermissionRequest | Apabila dialog kebenaran muncul | Ya |
| PostToolUse | Selepas panggilan alatan berjaya | Tidak |
| PostToolUseFailure | Selepas panggilan alatan gagal | Tidak |
| Notification | Apabila Claude Code menghantar pemberitahuan | Tidak |
| SubmitMessage | Apabila Claude menyerahkan mesej kepada pengguna | Tidak |
| ContextCompaction | Apabila tetingkap konteks menghampiri had | Tidak |
Keupayaan menyekat adalah yang paling penting. Cangkuk PreToolUse boleh menghalang operasi berbahaya sebelum ia dilaksanakan. Kod keluar 1 menyekat tindakan. Kod keluar 0 membenarkannya. Kod keluar 2 mendorong Claude untuk mempertimbangkan semula.
Tetapi tunggu. Cangkuk PostToolUse tidak boleh membatalkan tindakan kerana alatan telah pun dilaksanakan. Had ini membentuk bagaimana logik pengesahan distrukturkan. Pemeriksaan kritikal terletak pada PreToolUse. Pembersihan dan pemformatan terletak pada PostToolUse.
Semak Kebaikan Alatan AI Semasa Menyiapkan Claude Code
Jika anda sedang bekerja dengan cangkuk Claude Code, anda mungkin juga memilih alatan AI lain di sekeliling aliran kerja anda. Get AI Perks mengumpul kredit permulaan dan diskaun perisian untuk alatan AI dan awan di satu tempat. Platform ini merangkumi 200+ tawaran, dengan syarat kebaikan dan panduan tuntutan untuk setiap satu.
Mencari Kebaikan Claude atau Alatan AI Lain?
Semak Get AI Perks untuk:
- semak tawaran Claude dan alatan AI lain
- bandingkan syarat kebaikan sebelum memohon
- cari diskaun permulaan di seluruh tindanan alatan anda
👉 Lawati Get AI Perks untuk meneroka kebaikan perisian AI semasa.
Konfigurasi dan Struktur Fail
Cangkuk ditakrifkan dalam fail .claude/settings.json dalam projek. Skema konfigurasi menyokong cangkuk global dan pencocok khusus alatan yang menapis bila cangkuk dilaksanakan.
Struktur cangkuk arahan asas:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Pembolehubah ${file} mengembang kepada laluan fail sebenar daripada input alatan. Menurut dokumentasi rasmi, cangkuk menyokong pengembangan pembolehubah ini dalam medan arahan dan argumen.
Hierarki Lokasi Cangkuk
Claude Code menyemak pelbagai lokasi untuk takrifan cangkuk, dengan urutan keutamaan yang jelas:
- Peringkat Projek: .claude/settings.json dalam ruang kerja semasa
- Peringkat Pengguna: ~/.claude/settings.json untuk semua sesi
- Disediakan plugin: Cangkuk dibundel dengan plugin yang dipasang
Cangkuk peringkat projek mengatasi cangkuk pengguna untuk peristiwa yang sama. Ini membolehkan peraturan pemformatan khusus projek sambil mengekalkan pengendali pemberitahuan global.
Corak Pencocok untuk Pelaksanaan Pilihan
Sistem pencocok menapis cangkuk kepada alatan atau syarat tertentu. Tanpa pencocok, cangkuk ditembak untuk setiap kejadian peristiwanya.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Medan pathPattern menerima sintaks glob. Medan toolName dipadankan dengan alatan terbina dalam Claude seperti edit_file, execute_command, read_file, dan create_directory.
Perbincangan komuniti mendedahkan bahawa gabungan pencocok berfungsi dengan logik AND. Semua pencocok yang dinyatakan mesti sepadan agar cangkuk dilaksanakan.
Cangkuk Arahan: Integrasi Skrip Shell
Cangkuk arahan melaksanakan arahan shell atau skrip dengan input JSON berstruktur. Ia mewakili jenis cangkuk yang paling biasa untuk automasi tempatan.
Dokumentasi rasmi menyatakan bahawa cangkuk arahan menerima JSON melalui stdin dengan struktur ini:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skrip mengurai input ini untuk membuat keputusan. Cangkuk pengesahan Python mungkin kelihatan seperti:#!/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) |
Kod keluar 0 membenarkan operasi. Kod keluar 1 menyekatnya dan menunjukkan mesej stderr kepada Claude. Kod keluar 2 mencetuskan tingkah laku khas bergantung pada peristiwa.
Tingkah Laku Kod Keluar 2
Menurut dokumentasi rujukan cangkuk rasmi, kod keluar 2 mempunyai makna khusus peristiwa (PreToolUse: menyekat dan mendorong pertimbangan semula; UserPromptSubmit: menyediakan konteks tanpa menyekat; PermissionRequest: menyekat kebenaran):
- PreToolUse: Menyekat alatan dan mendorong Claude untuk mempertimbangkan semula dengan mesej stderr sebagai konteks
- UserPromptSubmit: Menyediakan output stderr sebagai konteks tambahan tanpa menyekat
- PermissionRequest: Menyekat pemberian kebenaran
Ini mewujudkan jalan tengah antara penyekatan keras dan kebenaran. Claude menerima maklum balas tentang mengapa tindakan itu mungkin bermasalah dan boleh menyesuaikan pendekatannya.
Cangkuk Arahan Asinkron
Penanda `async: true` menjalankan cangkuk di latar belakang tanpa menyekat aliran kerja Claude. Ini penting untuk operasi yang perlahan seperti pemberitahuan penggunaan atau pengumpulan metrik.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Apabila cangkuk asinkron ditembak, Claude Code memulakan proses dan meneruskan dengan segera. Medan tamat masa menetapkan masa pelaksanaan maksimum dalam saat. Jika tidak dinyatakan, cangkuk asinkron menggunakan tamat masa lalai 10 minit.
Bercakap benar: cangkuk asinkron tidak boleh menyekat operasi kerana ia berjalan selepas Claude meneruskan. Ia berfungsi untuk logging, pemberitahuan, dan pembersihan—bukan pengesahan.
Cangkuk HTTP: Integrasi Perkhidmatan Luaran
Cangkuk HTTP menghantar muatan JSON ke titik akhir jauh dan mengurai respons untuk kawalan keputusan. Ia membolehkan integrasi dengan perkhidmatan pengesahan, pangkalan data, dan alatan pihak ketiga.
Konfigurasi cangkuk HTTP asas:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Struktur muatan sepadan dengan input cangkuk arahan tetapi tiba sebagai badan POST HTTP. Respons menentukan tindakan seterusnya Claude.
Pengendalian Respons HTTP
Menurut dokumentasi rasmi, cangkuk HTTP mentafsir respons berdasarkan kod status dan kandungan badan:
| Kod Status | Kesan | Sumber Mesej |
|---|---|---|
| 200 | Benarkan operasi | Badan respons (pilihan) |
| 400 | Sekat operasi | Badan respons ditunjukkan kepada Claude |
| 500 | Ralat cangkuk, benarkan operasi | Log tetapi tidak ditunjukkan kepada Claude |
| Lain-lain | Benarkan operasi | Kegagalan cangkuk tidak menyekat aliran kerja |
Badan respons boleh termasuk medan mesej yang dilihat Claude sebagai konteks. Ini membolehkan perkhidmatan pengesahan menerangkan mengapa operasi disekat.
Interpolasi Pembolehubah Persekitaran
Cangkuk HTTP menyokong sintaks ${VAR} dalam url, pengepala, dan medan rentetan lain. Pembolehubah mengembang daripada persekitaran di mana Claude Code berjalan.
Menurut dokumentasi MCP rasmi, pengembangan pembolehubah persekitaran termasuk sintaks sandaran lalai: ${VAR:-default} mengembang kepada VAR jika ditetapkan, jika tidak menggunakan nilai lalai.
Batasan keselamatan: Menurut isu GitHub #28044, cangkuk HTTP hanya boleh mengakses pembolehubah persekitaran yang dinyatakan secara eksplisit dalam medan konfigurasi `allowedEnvVars`. Ini menghalang pendedahan kelayakan yang tidak disengajakan.
Cangkuk Gesaan: Suntikan Konteks
Cangkuk gesaan menyuntik arahan dinamik ke dalam konteks Claude pada peristiwa tertentu. Mereka mengubah tingkah laku tanpa proses luaran atau panggilan API.
| { “event”: “SessionStart”, “prompt”: “Anda sedang mengusahakan projek TypeScript. Sentiasa gunakan pemeriksaan null yang ketat dan utamakan async/await berbanding janji.” } |
Teks yang disuntik menjadi sebahagian daripada arahan sistem Claude untuk sesi itu. Cangkuk gesaan juga boleh menggunakan pembolehubah templat yang mengembang berdasarkan data peristiwa.
Penjanaan Gesaan Dinamik
Menurut dokumentasi rasmi, cangkuk gesaan menyokong medan arahan yang menjana gesaan dinamik:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Arahan menerima input JSON standard melalui stdin dan mengeluarkan teks gesaan kepada stdout. Ini membolehkan penjanaan arahan yang sedar konteks berdasarkan keadaan projek.
Cangkuk Berasaskan Ejen
Cangkuk ejen menentukan sub-ejen yang mengendalikan peristiwa dan bukannya suntikan gesaan langsung. Sub-ejen menerima konteks tentang peristiwa dan boleh melakukan penaakulan berbilang langkah.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Panggilan alatan gagal. Analisis ralat dan cadangkan pembaikan.” } |
Sub-ejen bernama mesti ditakrifkan dalam konfigurasi projek. Cangkuk ejen membolehkan logik keputusan yang kompleks yang tidak dapat disediakan oleh suntikan gesaan mudah.
Corak Cangkuk Praktikal
Perbincangan komuniti dan contoh rasmi mendedahkan corak automasi tertentu yang berfungsi dengan boleh dipercayai dalam pengeluaran.
Format Kod Auto Selepas Edit
Corak yang paling biasa memformat kod secara automatik selepas Claude mengedit fail:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Pembolehubah ${toolInput.path} mengembang kepada laluan fail yang diedit. PostToolUse memastikan pemformatan berlaku selepas edit yang berjaya tetapi tidak menyekat aliran kerja Claude.
Sekat Pengubahsuaian Fail Terlindung
Cangkuk PreToolUse menguatkuasakan peraturan perlindungan fail:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skrip mengesahkan laluan sasaran terhadap corak yang dilindungi dan keluar dengan kod 1 untuk menyekat edit yang dilarang.
Dapatkan Pemberitahuan Apabila Claude Memerlukan Input
Menurut panduan aliran kerja rasmi, cangkuk Pemberitahuan boleh mencetuskan amaran desktop atau menghantar mesej ke perkhidmatan luaran:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Ini ditembak setiap kali Claude Code menghantar pemberitahuan, termasuk semasa menunggu input pengguna atau selepas penyiapan tugasan.
Suntik Semula Konteks Selepas Pemadatan
Cangkuk ContextCompaction memulihkan konteks penting apabila tetingkap perbualan penuh:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Output arahan disuntik kembali ke dalam konteks Claude selepas pemadatan mengalih keluar mesej yang lebih lama. Ini menghalang kehilangan arahan penting khusus projek.
Audit Perubahan Konfigurasi
Jejaki bila Claude mengubah fail konfigurasi:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Pelaksanaan asinkron menghalang penyekatan Claude semasa operasi git selesai. Ini mencipta jejak audit perubahan konfigurasi tanpa pementasan manual.
Output JSON dan Kawalan Keputusan
Cangkuk arahan boleh mengeluarkan JSON berstruktur untuk memberikan maklum balas terperinci di luar kod keluar ringkas. Menurut rujukan rasmi, output JSON membolehkan respons berbilang medan yang ditafsirkan oleh Claude untuk pembuatan keputusan.
| { “allowed”: false, “message”: “File ini dilindungi oleh polisi pasukan” “suggestion”: “Cipta fail baharu dalam src/features/ sebaliknya” } |
Medan `allowed` mengawal sama ada operasi diteruskan. Mesej itu dipaparkan kepada Claude sebagai konteks. Medan `suggestion` menyediakan pendekatan alternatif.
Agar cangkuk mengeluarkan JSON, ia mesti:
- Tulis JSON yang sah ke stdout
- Keluar dengan kod 0 (untuk dibenarkan) atau 1 (untuk disekat)
- Sertakan sekurang-kurangnya medan boolean `allowed`
Claude Code mengurai JSON dan menggunakannya untuk meningkatkan kitaran maklum balas. Kod keluar masih menentukan keputusan utama, tetapi JSON menyediakan konteks yang lebih kaya.
Rujukan Medan Input Cangkuk
Semua cangkuk menerima objek JSON melalui stdin dengan medan biasa serta data khusus peristiwa. Memahami skema lengkap membolehkan logik cangkuk yang lebih canggih.
Medan Input Biasa
Setiap cangkuk menerima medan asas ini:
- event: Nama peristiwa cangkuk (cth., "PreToolUse")
- sessionId: Pengenal unik untuk sesi Claude semasa
- turnId: Pengenal untuk pusingan perbualan semasa
- timestamp: Cap waktu ISO 8601 apabila peristiwa ditembak
Medan Peristiwa Alatan
Peristiwa PreToolUse, PostToolUse, dan PostToolUseFailure termasuk:
- toolName: Nama alatan yang dipanggil (edit_file, execute_command, dsb.)
- toolInput: Objek yang mengandungi parameter input alatan
- toolResponse: Data output alatan (PostToolUse sahaja)
- error: Butiran ralat termasuk mesej dan kod (PostToolUseFailure sahaja)
Struktur `toolInput` berbeza mengikut alatan. Untuk `edit_file` ia mengandungi laluan dan kandungan. Untuk `execute_command` ia mengandungi arahan dan argumen.
Medan Peristiwa Kebenaran
Peristiwa PermissionRequest termasuk:
- permissionType: Jenis kebenaran yang diminta (file_write, command_execute, dsb.)
- requestedAction: Tindakan spesifik yang memerlukan kebenaran
- resourcePath: Laluan fail atau pengenal sumber yang terjejas
Cangkuk Alatan MCP
Menurut rujukan cangkuk rasmi, cangkuk boleh dipadankan dengan alatan Model Context Protocol (MCP) menggunakan medan pencocok `mcpTool`. Ini membolehkan pelaksanaan cangkuk apabila Claude menggunakan alatan luaran yang disediakan oleh pelayan MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Nilai `mcpTool` dipadankan dengan nama alatan dalam format `server-name/tool-name`. Ini membolehkan logik pengesahan untuk pertanyaan pangkalan data, panggilan API, atau operasi luaran lain.
Permintaan ciri GitHub menunjukkan minat yang semakin meningkat dalam integrasi MCP yang lebih mendalam, termasuk cangkuk yang boleh memeriksa pemberitahuan pelayan MCP dan bertindak balas terhadap peristiwa luaran.
Pertimbangan Keselamatan
Cangkuk dilaksanakan dengan kebenaran yang sama seperti Claude Code itu sendiri. Ini mewujudkan implikasi keselamatan untuk persekitaran berbilang pengguna dan konfigurasi kongsi.
Sandbox Pelaksanaan Arahan
Menurut isu GitHub #28044, cangkuk HTTP laluan melalui proksi sandbox yang menyekat akses rangkaian dan menapis pembolehubah persekitaran. Cangkuk arahan tidak mempunyai sekatan sedemikian—ia berjalan dengan akses shell penuh.
Dokumentasi mengesyorkan amalan ini:
- Jangan sekali-kali menyimpan kelayakan dalam arahan cangkuk
- Gunakan pembolehubah persekitaran untuk data sensitif
- Sahkan semua input daripada pengembangan ${…}
- Laksanakan had tamat masa untuk perkhidmatan luaran
- Gunakan cangkuk asinkron untuk operasi bukan kritikal untuk mengelakkan penyekatan semasa kegagalan
Pengasingan Pelaksanaan Cangkuk
Cangkuk peringkat pengguna dalam ~/.claude/settings.json terpakai kepada semua projek. Ini mewujudkan risiko apabila bekerja merentasi sempadan amanah yang berbeza. Cangkuk peringkat projek mengatasi cangkuk pengguna tetapi tidak boleh melumpuhkannya sepenuhnya.
Menu /hooks dalam Claude Code menunjukkan semua cangkuk aktif untuk sesi semasa. Menyemak senarai ini sebelum bekerja pada projek sensitif membantu mengenal pasti kebimbangan keselamatan yang mungkin.
Penyahpepijatan dan Penyelesaian Masalah
Kegagalan cangkuk tidak selalu timbul dengan jelas dalam perbualan Claude. Dokumentasi rasmi menyediakan beberapa pendekatan penyahpepijatan.
Log Pelaksanaan Cangkuk
Claude Code mencatat pelaksanaan cangkuk ke output penyahpepijatan sesi. Menurut panduan penyelesaian masalah, mendayakan logging penyahpepijatan mendedahkan:
- Cangkuk mana yang sepadan untuk setiap peristiwa
- Input JSON yang dihantar ke setiap cangkuk
- Output stdout dan stderr daripada proses cangkuk
- Kod keluar dan masa pelaksanaan
- Kod status dan badan respons HTTP untuk cangkuk HTTP
Dayakan logging penyahpepijatan dengan menetapkan `CLAUDE_DEBUG=1` dalam persekitaran sebelum memulakan Claude Code.
Uji Cangkuk Secara Bebas
Cangkuk arahan boleh diuji di luar Claude Code dengan membina input JSON secara manual:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Ini mengesahkan logik cangkuk tanpa mencetuskan operasi Claude sebenar. Kod keluar dan output stdout/stderr harus sepadan dengan tingkah laku yang dijangka.
Kegagalan Cangkuk Biasa
Perbincangan komuniti mengenal pasti isu kerap ini:
- Ralat tamat masa: Tamat masa lalai 10 minit terlalu pendek untuk operasi perlahan—tambah dengan medan `timeout`
- Kegagalan pengembangan laluan: Pembolehubah seperti ${file} tidak ditakrifkan untuk peristiwa yang tidak termasuk konteks fail
- Ralat kebenaran: Skrip cangkuk kekurangan kebenaran pelaksanaan—jalankan `chmod +x script.sh`
- Ralat parse JSON: Output JSON yang rosak daripada cangkuk—sahkan dengan `jq` sebelum mengembalikan
- Ketidaktersediaan pembolehubah persekitaran: Pembolehubah tidak disebarkan kepada proses cangkuk—semak persekitaran Claude Code
Implikasi Prestasi Cangkuk
Cangkuk segerak menyekat aliran kerja Claude sehingga selesai. Tamat masa lalai 10 minit menghalang penggantungan yang tidak terhad, tetapi kelewatan yang singkat pun terkumpul merentasi pelbagai operasi.
Pengamal melaporkan bahawa cangkuk pengesahan ringkas mempunyai impak prestasi yang boleh diabaikan. Cangkuk pemformatan fail menyebabkan impak prestasi yang ketara tetapi boleh diterima. Panggilan API luaran boleh mewujudkan geseran aliran kerja. Operasi pengiraan berat mendapat manfaat daripada pelaksanaan asinkron.
Papak Cangkuk
Beberapa cangkuk boleh sepadan dengan peristiwa yang sama. Menurut dokumentasi rujukan, cangkuk melaksanakan secara berturutan mengikut urutan takrifan. Jika mana-mana cangkuk menyekat operasi, cangkuk yang tinggal tidak akan dilaksanakan.
Ini penting untuk prestasi. Lima cangkuk segerak pada 200ms setiap satu menambah satu saat setiap peristiwa. Menggabungkan pengesahan berkaitan ke dalam satu cangkuk mengurangkan overhead.
Corak Lanjutan
Di luar automasi asas, cangkuk membolehkan penyesuaian aliran kerja yang canggih.
Rantaian Cangkuk Berkeadaan
Cangkuk boleh mengekalkan keadaan antara pelaksanaan menggunakan fail atau pangkalan data. Cangkuk PostToolUse mungkin merekodkan operasi yang berjaya yang kemudiannya disahkan oleh cangkuk PreToolUse:
| #!/bin/bash # Rekod edit yang berjaya echo “${toolInput.path}” >> .claude/edit-history.txt |
Cangkuk PreToolUse rakan kongsi boleh menyemak sejarah ini untuk mengelakkan operasi berulang atau menguatkuasakan sekatan susunan.
Pengaktifan Cangkuk Bersyarat
Pembolehubah persekitaran mengawal tingkah laku cangkuk semasa masa jalan. Menetapkan `CLAUDE_SKIP_HOOKS=1` melumpuhkan cangkuk untuk situasi kecemasan.
Cangkuk itu sendiri boleh menyemak bendera persekitaran:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Guna pengesahan ketat exit 1 fi exit 0 |
Ini membolehkan tingkah laku mod pembangunan berbanding mod pengeluaran tanpa perubahan konfigurasi.
Pengesahan Berbilang Peringkat
Cangkuk PreToolUse boleh melaksanakan pengesahan berbilang peringkat di mana kod keluar 2 membenarkan Claude meneruskan dengan amaran:
- Kegagalan keras (keluar 1): Sekat operasi berbahaya
- Amaran lembut (keluar 2): Maklumkan Claude untuk mempertimbangkan semula
- Lulus dengan konteks (keluar 0 + JSON): Sediakan maklumat tambahan
Ini mewujudkan spektrum pengesahan yang lebih bernuansa daripada biari/tolak binari.
Integrasi dengan CI/CD
Menurut dokumentasi integrasi platform rasmi, Claude Code berjalan dalam persekitaran CI/CD untuk semakan kod automatik dan triase isu. Cangkuk melanjutkan automasi ini.
Aliran kerja GitHub Actions boleh mentakrifkan cangkuk yang menguatkuasakan polisi pasukan semasa sesi automatik:
| – name: Jalankan Claude Code dengan cangkuk ketat env: STRICT_MODE: 1 run: | claude “Semak PR ini dan cadangkan penambahbaikan” |
Penanda `STRICT_MODE` mengaktifkan logik pengesahan bersyarat dalam skrip cangkuk. Ini memastikan sesi automatik mengikut peraturan yang lebih ketat daripada pembangunan interaktif.
Penjanaan Jejak Audit
Cangkuk PostToolUse dalam persekitaran CI mencipta log audit terperinci bagi semua operasi Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Logging latar belakang tidak menjejaskan prestasi tetapi menyediakan sejarah operasi lengkap untuk pematuhan dan penyahpepijatan.
Menu /hooks
Claude Code menyediakan arahan /hooks yang memaparkan semua cangkuk aktif untuk sesi semasa. Menurut dokumentasi rasmi, menu ini menunjukkan:
- Jenis peristiwa cangkuk
- Corak pencocok
- Arahan atau titik akhir URL
- Sama ada cangkuk berjalan secara asinkron
- Sumber konfigurasi (projek, pengguna, atau plugin)
Memilih cangkuk menunjukkan konfigurasinya yang lengkap dan membolehkan pelumpuhan sementara untuk sesi semasa.
Lumpuhkan atau Alih Keluar Cangkuk
Cangkuk boleh dilumpuhkan tanpa mengalih keluar konfigurasi dengan menambahkan `"enabled": false` pada takrifan cangkuk. Ini mengekalkan konfigurasi sambil menghalang pelaksanaan.
Untuk mengalih keluar cangkuk secara kekal, padamkan entrinya daripada fail settings.json yang sesuai. Perubahan berkuat kuasa pada permulaan semula sesi seterusnya atau apabila menjalankan /reload.
Cangkuk dalam Kemahiran dan Ejen
Menurut dokumentasi rasmi, cangkuk yang ditakrifkan dalam konfigurasi kemahiran atau sub-ejen hanya terpakai apabila kemahiran atau ejen tersebut dilaksanakan. Ini membolehkan automasi khusus untuk aliran kerja tertentu.
Sub-ejen penyahpepijatan mungkin termasuk cangkuk yang mencatat semua panggilan alatan:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Cangkuk ini hanya ditembak semasa sesi ejen debugger, bukan semasa operasi Claude Code biasa.
Rujuk Skrip mengikut Laluan
Arahan cangkuk menyokong laluan relatif dan mutlak. Laluan relatif diselesaikan dari akar projek di mana Claude Code berjalan.
Amalan terbaik daripada perbincangan komuniti:
- Simpan skrip cangkuk dalam direktori .claude/hooks/
- Gunakan nama deskriptif: `validate-typescript.sh` bukan `hook1.sh`
- Jadikan skrip boleh dilaksanakan: `chmod +x .claude/hooks/*.sh`
- Sertakan baris shebang: `#!/usr/bin/env bash` atau `#!/usr/bin/env python3`
- Tambah pengendalian ralat dengan `set -e` dalam skrip bash
Keupayaan Cangkuk Masa Depan
Permintaan ciri GitHub mendedahkan penambahbaikan cangkuk yang dirancang dan diminta:
- Cangkuk skrip sebaris: Takrifkan logik cangkuk secara langsung dalam `settings.json` tanpa fail luaran
- Integrasi alatan MCP: Panggil alatan pelayan MCP daripada cangkuk dan bukannya arahan shell
- Kerjasama berbilang ejen: Cangkuk yang menyelaraskan antara contoh Claude pada mesin yang berbeza
- Penjujukan jenis yang dipertingkat: Definisi jenis TypeScript untuk skema input/output cangkuk
Menurut isu GitHub #4274, permintaan untuk jenis cangkuk bersepadu (alatan MCP, skrip sebaris, panggilan API) bertujuan untuk memudahkan konfigurasi dan meningkatkan pengalaman pembangun.
Soalan Lazim
Bolehkah cangkuk menghalang Claude daripada melaksanakan arahan berbahaya?
Ya. Cangkuk PreToolUse boleh menyekat sebarang pelaksanaan alatan dengan keluar dengan kod 1. Ini termasuk edit fail, pelaksanaan arahan, dan panggilan alatan MCP. Cangkuk menerima input alatan lengkap dan boleh mengesahkan terhadap sebarang kriteria sebelum membenarkan operasi.
Bagaimana cara saya menyahpepijat cangkuk yang tidak berfungsi?
Dayakan logging penyahpepijatan dengan `CLAUDE_DEBUG=1` sebelum memulakan Claude Code. Semak log sesi untuk butiran pelaksanaan cangkuk termasuk cangkuk mana yang sepadan, input JSON yang dihantar, output stdout/stderr, dan kod keluar. Uji cangkuk secara bebas dengan menala JSON sampel ke skrip cangkuk.
Adakah cangkuk berfungsi dengan semua platform Claude Code?
Cangkuk berfungsi dalam CLI, aplikasi desktop, dan sambungan VS Code. Menurut dokumentasi rasmi, cangkuk dilaksanakan di mana sahaja Claude Code berjalan dengan akses kepada sistem fail. Claude berasaskan penyemak imbas dan apl mudah alih tidak menyokong cangkuk kerana kekangan sandbox.
Bolehkah cangkuk mengubah respons atau tingkah laku Claude?
Cangkuk gesaan menyuntik arahan yang mempengaruhi tingkah laku Claude. Cangkuk ejen menyerah pengendalian peristiwa kepada sub-ejen khusus. Walau bagaimanapun, cangkuk tidak boleh mengubah teks yang dijana atau proses penaakulan Claude secara langsung—ia berfungsi dengan menyediakan konteks dan menyekat operasi.
Apakah perbezaan antara cangkuk asinkron dan sinkron?
Cangkuk segerak menyekat aliran kerja Claude sehingga selesai atau tamat masa. Cangkuk asinkron berjalan di latar belakang tanpa menyekat. Cangkuk sinkron boleh menghalang operasi melalui kod keluar. Cangkuk asinkron tidak boleh menyekat kerana Claude meneruskan sebelum cangkuk selesai. Gunakan asinkron untuk logging dan pemberitahuan, sinkron untuk pengesahan.
Bagaimana cara saya berkongsi cangkuk di seluruh pasukan?
Tanam fail .claude/settings.json ke dalam kawalan versi. Cangkuk peringkat projek terpakai kepada semua ahli pasukan yang mengklon repositori. Untuk polisi seluruh organisasi, pasukan boleh mengekalkan fail tetapan peringkat pengguna yang dikongsi yang disalin oleh ahli ke ~/.claude/settings.json.
Bolehkah cangkuk HTTP memanggil API dalaman di belakang tembok api?
Ya, jika Claude Code berjalan dalam persekitaran dengan akses rangkaian kepada API tersebut. Cangkuk HTTP membuat permintaan POST standard dari mesin yang menjalankan Claude Code. Tembok api korporat dan VPN terpakai seperti biasa. Proksi sandbox yang disebut dalam dokumentasi mengawal pendedahan pembolehubah persekitaran, bukan penghalaan rangkaian.
Adakah cangkuk meningkatkan penggunaan token Claude Code?
Cangkuk gesaan menyuntik teks ke dalam konteks Claude, yang menggunakan token. Cangkuk arahan dan HTTP tidak menjejaskan penggunaan token secara langsung, tetapi outputnya (mesej ralat, cadangan) menjadi sebahagian daripada konteks perbualan. Kod keluar 2 dengan mesej penjelasan menambah lebih banyak konteks daripada kod keluar 1 dengan penyekatan ringkas.
Kesimpulan
Claude Code hooks mengubah pembantu AI daripada alat yang berkuasa kepada platform pembangunan yang automatik sepenuhnya. Sistem peristiwa menyediakan titik persisian sepanjang aliran kerja Claude—daripada inisialisasi sesi melalui pemadatan konteks.
Cangkuk arahan mengendalikan pengesahan dan pemformatan tempatan. Cangkuk HTTP menyepadukan perkhidmatan dan pangkalan data luaran. Cangkuk gesaan mengubah tingkah laku melalui suntikan konteks. Bersama-sama, ini membolehkan corak automasi yang menguatkuasakan polisi pasukan, mengekalkan kualiti kod, dan berintegrasi dengan infrastruktur pembangunan sedia ada.
Sistem pencocok menapis cangkuk kepada alatan dan corak fail tertentu. Kod keluar dan output JSON mengawal aliran keputusan. Pelaksanaan asinkron menghalang penyekatan pada operasi perlahan. Skema konfigurasi lengkap menyokong segala-galanya daripada pemformatan auto ringkas kepada pengesahan berbilang peringkat yang kompleks.
Mulakan dengan cangkuk PostToolUse asas untuk pemformatan kod. Tambah pengesahan PreToolUse apabila polisi muncul. Eksperimen dengan cangkuk gesaan untuk pengubahsuaian tingkah laku. Bina integrasi HTTP untuk penguatkuasaan seluruh pasukan.
Semak dokumentasi rasmi Claude Code untuk rujukan cangkuk lengkap dan skema konfigurasi yang dikemas kini apabila keupayaan baharu dihantar.
