Hızlı Özet: Claude Code kancaları, AI kodlama oturumları sırasında belirli yaşam döngüsü noktalarında çalışan otomasyon komut dosyalarıdır. Bu, geliştiricilerin özel komutlar çalıştırmasına, eylemleri doğrulamasına, kodu biçimlendirmesine, bildirimler göndermesine ve proje kurallarını uygulamasına olanak tanır. Bu kancalar, SessionStart, PreToolUse ve PostToolUse gibi olaylar aracılığıyla Claude'un iş akışıyla bütünleşir ve yapılandırılabilir zaman aşımları ve çıkış kodu davranışlarıyla komut tabanlı, HTTP tabanlı ve komut dosyası tabanlı yürütme modellerini destekler.
Claude Code'un kanca sistemi, Yapay Zeka kodlama yardımcısını faydalı bir araçtan tam otomatik bir geliştirme ortamına dönüştürür. Çoğu geliştirici, kancalar aracılığıyla kullanılabilen kontrol düzeyinin farkında değildir.
Ancak mesele şu ki, kancalar sadece dosya düzenlemelerinden sonra komut dosyası çalıştırmakla ilgili değil. Claude'un tüm karar verme sürecinin tamamı boyunca kesme noktaları sağlarlar. Bir komut çalıştırmadan önce. Bir araç çağrısı başarısız olduktan sonra. İzin gerektiğinde. Kullanıcı komut dosyalarını işlemeden önce bile.
Bu kılavuz, resmi belgelerde sağlanan her şeyi ve topluluk tartışmalarının üretim ortamlarında gerçekten işe yaradığını ortaya koyduğu pratik desenleri kapsamaktadır.
Claude Code Kancaları Gerçekten Ne İşe Yarar
Resmi Claude Code belgelerine göre kancalar, Claude Code'un yaşam döngüsünün belirli noktalarında çalışan, kullanıcı tarafından tanımlanan kabuk komutları, HTTP uç noktaları veya komut dosyası enjeksiyonlarıdır. Standart girdiden yapılandırılmış JSON girdisi alırlar ve çıkış kodları veya HTTP yanıtları aracılığıyla iş akışını kontrol ederler.
Otomasyon, çoğu kılavuzun önerdiğinden daha derine iner. Kancalar, araç yürütülmesini tamamen engelleyebilir, Claude'un akıl yürütmesine ek bağlam enjekte edebilir, harici hizmetleri tetikleyebilir ve Claude'un uyması gereken doğrulama kurallarını uygulayabilir.
Üç ana kanca türü vardır:
- Komut kancaları: Stdout, stderr ve çıkış kodları aracılığıyla iletişim kuran kabuk komut dosyaları
- HTTP kancaları: POST istekleri alan ve JSON yanıtları döndüren uzak uç noktalar
- Komut dosyası kancaları: Belirli olaylarda Claude'un bağlamına enjekte edilen dinamik talimatlar
Her tür farklı otomasyon desenlerine hizmet eder. Komut kancaları yerel doğrulama ve biçimlendirme işlemlerini halleder. HTTP kancaları harici hizmetler ve veritabanlarıyla entegre olur. Komut dosyası kancaları, harici süreçler olmadan Claude'un davranışını değiştirir.
Kanca Yaşam Döngüsü ve Olay Sistemi
Resmi belgeler, Claude Code'un yürütme akışı sırasında tetiklenen birden fazla kanca olayı (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification ve diğerleri) tanımlar. Her birinin ne zaman tetiklendiğini anlamak, hangi otomasyonun mümkün olduğunu belirler.
| Olay | Ne Zaman Tetiklenir | Engelleyebilir |
|---|---|---|
| SessionStart | Oturum başladığında veya devam ettiğinde | Hayır |
| UserPromptSubmit | Claude işlemeden önce, bir komut dosyası gönderdiğinizde | Evet |
| PreToolUse | Bir araç çağrısı yürütülmeden önce | Evet |
| PermissionRequest | Bir izin iletişim kutusu göründüğünde | Evet |
| PostToolUse | Bir araç çağrısı başarılı olduktan sonra | Hayır |
| PostToolUseFailure | Bir araç çağrısı başarısız olduktan sonra | Hayır |
| Notification | Claude Code bir bildirim gönderdiğinde | Hayır |
| SubmitMessage | Claude kullanıcıya bir mesaj gönderdiğinde | Hayır |
| ContextCompaction | Bağlam penceresi limitlere yaklaştığında | Hayır |
Engelleme yeteneği en çok önem taşıyor. PreToolUse kancaları, tehlikeli işlemleri yürütülmeden önce engelleyebilir. Çıkış kodu 1 eylemi engeller. Çıkış kodu 0 devam etmesine izin verir. Çıkış kodu 2, Claude'un yeniden değerlendirmesini ister.
Ancak bekleyin. PostToolUse kancaları, araç zaten yürütüldüğü için eylemleri geri alamaz. Bu sınırlama, doğrulama mantığının nasıl yapılandırıldığını şekillendirir. Kritik kontroller PreToolUse'da bulunmalıdır. Temizlik ve biçimlendirme PostToolUse'da bulunmalıdır.
Claude Code Kurulumu Sırasında Yapay Zeka Aracı Avantajlarını Göz Atın
Claude Code kancalarıyla çalışıyorsanız, iş akışınızın etrafındaki diğer Yapay Zeka araçlarını da seçiyor olabilirsiniz. Get AI Perks, Yapay Zeka ve bulut araçları için başlangıç kredilerini ve yazılım indirimlerini tek bir yerde toplar. Platform, her biri için 200'den fazla teklif içerir; avantaj koşulları ve talep kılavuzları bulunur.
Claude veya Diğer Yapay Zeka Aracı Avantajları mı Arıyorsunuz?
Şunu kontrol etmek için Get AI Perks'e göz atın:
- Claude ve diğer Yapay Zeka aracı tekliflerini inceleyin
- Başvurmadan önce avantaj koşullarını karşılaştırın
- Araç yığınınız genelinde başlangıç indirimleri bulun
👉 Mevcut Yapay Zeka yazılım avantajlarını keşfetmek için Get AI Perks'i ziyaret edin.
Yapılandırma ve Dosya Yapısı
Kancalar, bir proje içindeki .claude/settings.json dosyasında tanımlanır. Yapılandırma şeması, küresel kancaları ve kancaların ne zaman yürütüleceğini filtreleyen araca özgü eşleştiricileri destekler.
Temel komut kancası yapısı:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
${file} değişkeni, araç girdisinden gelen gerçek dosya yolunu genişletir. Resmi belgelere göre kancalar, komut ve argüman alanlarında bu değişken genişletmelerini destekler.
Kanca Konum Hiyerarşisi
Claude Code, kanca tanımları için birden fazla konumu denetler, açık bir öncelik sırası ile:
- Proje düzeyinde: Mevcut çalışma alanındaki .claude/settings.json
- Kullanıcı düzeyinde: Tüm oturumlar için ~/.claude/settings.json
- Eklenti tarafından sağlanan: Yüklü eklentilerle birlikte gelen kancalar
Proje kancaları, aynı olay için kullanıcı kancalarını geçersiz kılar. Bu, küresel bildirim işleyicileri korurken proje özel biçimlendirme kurallarına izin verir.
Seçici Yürütme İçin Eşleştirici Desenleri
Eşleştirici sistemi, kancaları belirli araçlara veya koşullara göre filtreler. Eşleştiriciler olmadan, kancalar olaylarının her oluşumunda tetiklenir.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
pathPattern alanı globu sözdizimini kabul eder. toolName alanı, edit_file, execute_command, read_file ve create_directory gibi Claude'un yerleşik araçlarına karşı eşleşir.
Topluluk tartışmaları, eşleştirici kombinasyonlarının VE mantığıyla çalıştığını ortaya koyuyor. Kancanın yürütülmesi için belirtilen tüm eşleştiriciler eşleşmelidir.
Komut Kancaları: Kabuk Komut Dosyası Entegrasyonu
Komut kancaları, yapılandırılmış JSON girdisiyle kabuk komutlarını veya komut dosyalarını yürütür. Yerel otomasyon için en yaygın kanca türünü temsil ederler.
Resmi belgeler, komut kancalarının bu yapıya sahip JSON'u standart girdi aracılığıyla aldığını belirtir:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Bu girdiyi yorumlayan komut dosyaları kararlar alır. Bir Python doğrulama kancası şöyle görünebilir:#!/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) |
Çıkış kodu 0 işlemi devam ettirir. Çıkış kodu 1 engeller ve stderr mesajını Claude'a gösterir. Çıkış kodu 2, olaya bağlı olarak özel bir davranışı tetikler.
Çıkış Kodu 2 Davranışı
Resmi kanca referans belgelerine göre, çıkış kodu 2'nin olaya özgü anlamı vardır (PreToolUse: engeller ve yeniden değerlendirmeyi ister; UserPromptSubmit: engellemeden bağlam sağlar; PermissionRequest: izni engeller):
- PreToolUse: Aracı engeller ve stderr mesajını bağlam olarak kullanarak yeniden değerlendirmeyi ister
- UserPromptSubmit: Engellemeden ek bağlam olarak stderr çıktısını sağlar
- PermissionRequest: İzin verilmesini engeller
Bu, sert engelleme ile izin verme arasında bir orta zemin oluşturur. Claude, eylemin neden sorunlu olabileceğine dair geri bildirim alır ve yaklaşımını ayarlayabilir.
Asenkron Komut Kancaları
async: true bayrağı, kancaları Claude'un iş akışını engellemeden arka planda çalıştırır. Bu, dağıtım bildirimleri veya metrik toplama gibi yavaş işlemler için önemlidir.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Asenkron bir kanca tetiklendiğinde, Claude Code süreci başlatır ve hemen devam eder. timeout alanı, saniye cinsinden maksimum yürütme süresini ayarlar. Belirtilmezse, asenkron kancalar 10 dakikalık varsayılan zaman aşımı kullanır.
Gerçekten söylersek: asenkron kancalar işlemleri engelleyemez çünkü Claude devam ettikten sonra çalışırlar. Günlük kaydı, bildirimler ve temizlik için çalışırlar - doğrulama için değil.
HTTP Kancaları: Harici Hizmet Entegrasyonu
HTTP kancaları, karar kontrolü için uzak uç noktalara JSON yükleri gönderir ve yanıtları ayrıştırır. Doğrulama hizmetleri, veritabanları ve üçüncü taraf araçlarla entegrasyona olanak tanır.
Temel HTTP kancası yapılandırması:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Yük yapısı komut kancası girdisiyle eşleşir ancak HTTP POST gövdesi olarak gelir. Yanıt, Claude'un sonraki eylemini belirler.
HTTP Yanıt İşleme
Resmi belgelere göre, HTTP kancaları yanıtları durum koduna ve gövde içeriğine göre yorumlar:
| Durum Kodu | Etki | Mesaj Kaynağı |
|---|---|---|
| 200 | İşleme İzin Ver | Yanıt gövdesi (isteğe bağlı) |
| 400 | İşlemi Engelle | Claude'a gösterilen yanıt gövdesi |
| 500 | Kanca hatası, işlemi izin ver | Kaydedilir ancak Claude'a gösterilmez |
| Diğer | İşleme İzin Ver | Kanca hatası iş akışını engellemez |
Yanıt gövdesi, Claude'un bağlam olarak gördüğü bir mesaj alanı içerebilir. Bu, doğrulama hizmetlerinin bir işlemin neden engellendiğini açıklamasını sağlar.
Ortam Değişkeni Enterpolasyonu
HTTP kancaları, url, başlıklar ve diğer dize alanlarında ${VAR} sözdizimini destekler. Değişkenler, Claude Code'un çalıştığı ortamdan genişler.
Resmi MCP belgelerine göre, ortam değişkeni genişletmesi varsayılan bir yedek sözdizimini içerir: ${VAR:-default}, VAR ayarlanmışsa genişler, aksi takdirde varsayılan değeri kullanır.
Güvenlik kısıtlaması: GitHub sorunu #28044'e göre, HTTP kancaları yalnızca allowedEnvVars yapılandırma alanında açıkça listelenen ortam değişkenlerine erişebilir. Bu, kazara kimlik bilgisi sızmasını önler.
Komut Dosyası Kancaları: Bağlam Enjeksiyonu
Komut dosyası kancaları, belirli olaylarda Claude'un bağlamına dinamik talimatlar enjekte eder. Harici işlemler veya API çağrıları olmadan davranışı değiştirirler.
| { “event”: “SessionStart”, “prompt”: “You are working on a TypeScript project. Always use strict null checks and prefer async/await over promises.” } |
Enjekte edilen metin, o oturum için Claude'un sistem talimatlarının bir parçası haline gelir. Komut dosyası kancaları ayrıca olay verilerine dayalı olarak genişleyen şablon değişkenlerini de kullanabilir.
Dinamik Komut Dosyası Oluşturma
Resmi belgelere göre, komut dosyası kancaları dinamik komut dosyaları oluşturan komut alanlarını destekler:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Komut, standart JSON girdisini standart girdi aracılığıyla alır ve komut metnini stdout'a çıkarır. Bu, proje durumuna dayalı bağlama duyarlı talimat oluşturmaya olanak tanır.
Ajan Tabanlı Kancalar
Ajan kancaları, doğrudan komut dosyası enjeksiyonu yerine olayı işleyen bir alt ajanı belirtir. Alt ajan, olayla ilgili bağlam alır ve çok adımlı akıl yürütme yapabilir.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “A tool call failed. Analyze the error and suggest fixes.” } |
Adlandırılmış alt ajan, proje yapılandırmasında tanımlanmalıdır. Ajan kancaları, basit komut dosyası enjeksiyonunun sağlayamayacağı karmaşık karar mantığını etkinleştirir.
Pratik Kanca Desenleri
Topluluk tartışmaları ve resmi örnekler, üretimde güvenilir şekilde çalışan belirli otomasyon desenlerini ortaya koymaktadır.
Düzenlemelerden Sonra Kodu Otomatik Biçimlendirin
En yaygın desen, Claude dosyaları düzenledikten sonra kodu otomatik olarak biçimlendirir:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
${toolInput.path} değişkeni, düzenlenmiş dosya yoluna genişler. PostToolUse, başarılı düzenlemelerden sonra biçimlendirmenin gerçekleşmesini sağlar ancak Claude'un iş akışını engellemez.
Korumalı Dosya Değişikliklerini Engelleyin
PreToolUse kancaları dosya koruma kurallarını zorunlu kılar:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Komut dosyası, hedef yolu korumalı desenlere karşı doğrular ve yasaklanmış düzenlemeleri engellemek için 1 koduyla çıkar.
Claude Giriş Gerektirdiğinde Bildirim Alın
Resmi iş akışı kılavuzuna göre, Notification kancaları masaüstü uyarılarını tetikleyebilir veya harici hizmetlere mesaj gönderebilir:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Bu, Claude Code bir bildirim gönderdiğinde, kullanıcı girdisi beklerken veya görev tamamlandıktan sonra tetiklenir.
Sıkıştırmadan Sonra Bağlamı Yeniden Enjekte Edin
ContextCompaction kancaları, konuşma penceresi dolduğunda önemli bağlamı geri yükler:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Komut çıktısı, sıkıştırma eski mesajları kaldırdıktan sonra Claude'un bağlamına geri enjekte edilir. Bu, kritik proje özel talimatlarının kaybını önler.
Yapılandırma Değişikliklerini Denetleyin
Claude'un yapılandırma dosyalarını ne zaman değiştirdiğini izleyin:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asenkron yürütme, git işlemlerinin tamamlanmasını beklerken Claude'u engellemeyi önler. Bu, manuel hazırlık olmadan yapılandırma değişikliklerinin bir denetim izini oluşturur.
JSON Çıktısı ve Karar Kontrolü
Komut kancaları, basit çıkış kodlarının ötesinde ayrıntılı geri bildirim sağlamak için yapılandırılmış JSON çıktı verebilir. Resmi referansa göre, JSON çıktısı Claude'un karar verme için yorumladığı çok alanlı yanıtları etkinleştirir.
| { “allowed”: false, “message”: “Bu dosya ekip politikası tarafından korunmaktadır”, “suggestion”: “Bunun yerine src/features/ altında yeni bir dosya oluşturun” } |
allowed alanı işlemin devam edip etmeyeceğini kontrol eder. mesaj, Claude'a bağlam olarak görünür. suggestion alanı alternatif yaklaşımlar sunar.
JSON çıktısı veren kancalar için şunlar gerekir:
- Stdout'a geçerli JSON yazın
- 0 (izin verildi) veya 1 (engellendi) koduyla çıkın
- En azından allowed boolean alanını içerin
Claude Code JSON'u ayrıştırır ve geri bildirim döngüsünü geliştirmek için kullanır. Çıkış kodları hala birincil kararı belirler, ancak JSON daha zengin bağlam sağlar.
Kanca Girdisi Alanları Referansı
Tüm kancalar, yaygın alanlar artı olaya özgü verilerle standart girdi aracılığıyla bir JSON nesnesi alır. Tam şemayı anlamak daha gelişmiş kanca mantığını sağlar.
Ortak Girdi Alanları
Her kanca bu temel alanları alır:
- event: Kanca olayı adı (örn. "PreToolUse")
- sessionId: Mevcut Claude oturumu için benzersiz tanımlayıcı
- turnId: Mevcut konuşma turu için tanımlayıcı
- timestamp: Olayın tetiklendiği ISO 8601 zaman damgası
Araç Olay Alanları
PreToolUse, PostToolUse ve PostToolUseFailure olayları şunları içerir:
- toolName: Çağrılan aracın adı (edit_file, execute_command, vb.)
- toolInput: Aracın girdi parametrelerini içeren nesne
- toolResponse: Araç çıktı verileri (yalnızca PostToolUse)
- error: Mesaj ve kod dahil hata ayrıntıları (yalnızca PostToolUseFailure)
toolInput yapısı araca göre değişir. edit_file için yol ve içerik içerir. execute_command için komut ve argümanlar içerir.
İzin Olay Alanları
PermissionRequest olayları şunları içerir:
- permissionType: İsteneen izin türü (file_write, command_execute, vb.)
- requestedAction: İzin gerektiren belirli eylem
- resourcePath: Etkilenen dosya yolu veya kaynak tanımlayıcısı
MCP Araç Kancaları
Resmi kanca referansına göre, kancalar mcpTool eşleştirici alanını kullanarak Model Bağlam Protokolü (MCP) araçlarıyla eşleşebilir. Bu, Claude harici MCP sunucularından sağlanan araçları kullandığında kanca yürütülmesini sağlar.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
mcpTool değeri, sunucu adı/araç adı biçimindeki araç adıyla eşleşir. Bu, veritabanı sorguları, API çağrıları veya diğer harici işlemler için doğrulama mantığına izin verir.
GitHub özellik istekleri, kancaların MCP sunucu bildirimlerini denetleyebilmesi ve harici olaylara yanıt verebilmesi dahil olmak üzere daha derin MCP entegrasyonu için artan bir ilgi olduğunu göstermektedir.
Güvenlik Hususları
Kancalar, Claude Code ile aynı izinlerle yürütülür. Bu, çok kullanıcılı ortamlar ve paylaşılan yapılandırmalar için güvenlik sonuçları yaratır.
Komut Yürütme Sanal Alanı
GitHub sorunu #28044'e göre, HTTP kancaları ağ erişimini kısıtlayan ve ortam değişkenlerini filtreleyen bir sanal alan proxy'sinden geçer. Komut kancaları bu tür kısıtlamalara sahip değildir - tam kabuk erişimiyle çalışırlar.
Belgeler şu uygulamaları önerir:
- Kanca komutlarında asla kimlik bilgileri saklamayın
- Hassas veriler için ortam değişkenlerini kullanın
- ${…} genişletmelerinden gelen tüm girdileri doğrulayın
- Harici hizmetler için zaman aşımı sınırları uygulayın
- Hatalarda engellemeyi önlemek için kritik olmayan işlemler için asenkron kancalar kullanın
Kanca Yürütme İzolasyonu
~/.claude/settings.json adresindeki kullanıcı düzeyindeki kancalar tüm projeler için geçerlidir. Bu, farklı güven sınırları arasında çalışırken riskler oluşturur. Proje düzeyindeki kancalar kullanıcı kancalarını geçersiz kılar ancak onları tamamen devre dışı bırakamaz.
Claude Code'daki /hooks menüsü, mevcut oturum için tüm aktif kancaları gösterir. Hassas projelerde çalışmadan önce bu listeyi gözden geçirmek olası güvenlik endişelerini belirlemeye yardımcı olur.
Hata Ayıklama ve Sorun Giderme
Kanca hataları her zaman Claude'un konuşmasında net bir şekilde görünmez. Resmi belgeler birden fazla hata ayıklama yaklaşımı sağlar.
Kanca Yürütme Günlükleri
Claude Code, oturum hata ayıklama çıktısına kanca yürütülmesini kaydeder. Sorun giderme kılavuzuna göre, hata ayıklama günlüğünü etkinleştirmek şunları ortaya çıkarır:
- Her olay için hangi kancaların eşleştiği
- Her kancaya gönderilen JSON girdisi
- Kanca işlemlerinden stdout ve stderr çıktıları
- Çıkış kodları ve yürütme süresi
- HTTP kancaları için HTTP yanıt kodları ve gövdeleri
Claude Code'u başlatmadan önce ortamda CLAUDE_DEBUG=1 ayarını yaparak hata ayıklama günlüğünü etkinleştirin.
Kancaları Bağımsız Olarak Test Edin
Komut kancaları, JSON girdisini manuel olarak oluşturarak Claude Code dışında test edilebilir:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Bu, gerçek Claude işlemlerini tetiklemeden kanca mantığını doğrular. Çıkış kodu ve stdout/stderr çıktıları beklenen davranışla eşleşmelidir.
Yaygın Kanca Hataları
Topluluk tartışmaları şu sık karşılaşılan sorunları tanımlar:
- Zaman aşımı hataları: Varsayılan 10 dakikalık zaman aşımı yavaş işlemler için çok kısa—timeout alanıyla artırın
- Yol genişletme hataları: Dosya bağlamı içermeyen olaylar için ${file} gibi değişkenler tanımsızdır
- İzin hataları: Kanca komut dosyalarının yürütme izinleri yok—chmod +x script.sh komutunu çalıştırın
- JSON ayrıştırma hataları: Kancalardan gelen bozuk JSON çıktısı—döndürmeden önce jq ile doğrulayın
- Ortam değişkeni kullanılamaması: Değişkenler kanca işlemine yayılmıyor—Claude Code'un ortamını kontrol edin
Kanca Performans Etkileri
Senkron kancalar, tamamlanana veya zaman aşımına uğrayana kadar Claude'un iş akışını engeller. Varsayılan 10 dakikalık zaman aşımı sonsuz takılmaları önler, ancak kısa gecikmeler bile birden fazla işlemde birikir.
Uygulayıcılar, basit doğrulama kancalarının ihmal edilebilir performans etkisine sahip olduğunu bildirmektedir. Dosya biçimlendirme kancaları belirgin ancak kabul edilebilir performans etkisi yaratır. Harici API çağrıları iş akışı sürtünmesi yaratabilir. Ağır hesaplama işlemleri asenkron yürütmeden yararlanır.
Kanca Gruplama
Aynı olaya birden fazla kanca eşleşebilir. Referans belgelerine göre, kancalar tanımlama sırasına göre sırayla yürütülür. Herhangi bir kanca işlemi engellerse, kalan kancalar yürütülmez.
Bu performans için önemlidir. 200 ms'lik beş senkron kanca, olay başına bir saniye ekler. İlgili doğrulamaları tek bir kancada birleştirmek ek yükü azaltır.
Gelişmiş Desenler
Temel otomasyonun ötesinde, kancalar gelişmiş iş akışı özelleştirmesini etkinleştirir.
Durumlu Kanca Zincirleri
Kancalar, dosyalar veya veritabanları kullanarak yürütmeler arasında durum tutabilir. Bir PostToolUse kancası, daha sonra bir PreToolUse kancasının doğruladığı başarılı işlemleri kaydedebilir:
| #!/bin/bash # Başarılı düzenlemeleri kaydet echo “${toolInput.path}” >> .claude/edit-history.txt |
Buna eşlik eden bir PreToolUse kancası, gereksiz işlemleri önlemek veya sipariş kısıtlamalarını zorlamak için bu geçmişi kontrol edebilir.
Koşullu Kanca Aktivasyonu
Ortam değişkenleri, çalışma zamanında kanca davranışını kontrol eder. CLAUDE_SKIP_HOOKS=1 ayarı, acil durumlar için kancaları devre dışı bırakır.
Kancalar kendileri ortam bayraklarını kontrol edebilir:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Sıkı doğrulama uygula exit 1 fi exit 0 |
Bu, yapılandırma değişiklikleri olmadan geliştirme modu ve üretim modu davranışlarını etkinleştirir.
Çok Aşamalı Doğrulama
PreToolUse kancaları, çıkış kodu 2'nin Claude'un uyarılarla devam etmesine izin verdiği çok katmanlı doğrulama uygulayabilir:
- Sert hatalar (çıkış 1): Tehlikeli işlemleri engelle
- Yumuşak uyarılar (çıkış 2): Claude'un yeniden değerlendirmesi için uyar
- Bağlamla geç (çıkış 0 + JSON): Ek bilgi sağla
Bu, ikili izin verme/reddetme yerine daha incelikli bir doğrulama spektrumu oluşturur.
CI/CD ile Entegrasyon
Resmi platform entegrasyon belgelerine göre, Claude Code otomatik kod incelemesi ve hata ayıklama için CI/CD ortamlarında çalışır. Kancalar bu otomasyonu genişletir.
GitHub Actions iş akışları, otomatik oturumlar sırasında ekip politikalarını zorlayan kancalar tanımlayabilir:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
STRICT_MODE bayrağı, komut dosyası kancalarında koşullu doğrulama mantığını etkinleştirir. Bu, otomatik oturumların etkileşimli geliştirmeden daha katı kurallara uymasını sağlar.
Denetim İzleri Oluşturma
CI ortamlarındaki PostToolUse kancaları, tüm Claude işlemlerinin ayrıntılı denetim günlükleri oluşturur:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Arka plan günlük kaydı performansı etkilemez ancak uyumluluk ve hata ayıklama için eksiksiz işlem geçmişi sağlar.
Hooks Menüsü
Claude Code, mevcut oturum için tüm aktif kancaları görüntüleyen bir /hooks komutu sağlar. Resmi belgelere göre, bu menü şunları gösterir:
- Kanca olayı türü
- Eşleştirici desenleri
- Komut veya URL uç noktası
- Kancanın asenkron çalışıp çalışmadığı
- Yapılandırma kaynağı (proje, kullanıcı veya eklenti)
Bir kanca seçmek, tüm yapılandırmasını gösterir ve mevcut oturum için geçici olarak devre dışı bırakılmasına izin verir.
Kancaları Devre Dışı Bırak veya Kaldır
Kancalar, "enabled": false değerini kanca tanımına ekleyerek yapılandırmayı kaldırmadan devre dışı bırakılabilir. Bu, yapılandırmayı korurken yürütülmesini engeller.
Bir kancayı kalıcı olarak kaldırmak için, ilgili settings.json dosyasındaki girişini silin. Değişiklikler, bir sonraki oturum yeniden başlatıldığında veya /reload komutu çalıştırıldığında etkili olur.
Beceriler ve Ajanlarda Kancalar
Resmi belgelere göre, beceri veya alt ajan yapılandırmaları içinde tanımlanan kancalar yalnızca o beceri veya ajan yürütülürken geçerlidir. Bu, belirli iş akışları için özel otomasyon sağlar.
Bir hata ayıklama alt ajanı, tüm araç çağrılarını günlüğe kaydeden kancalar içerebilir:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Bu kancalar, normal Claude Code çalışması sırasında değil, yalnızca hata ayıklayıcı ajan oturumları sırasında tetiklenir.
Betikleri Yola Göre Başvurma
Kanca komutları hem göreceli hem de mutlak yolları destekler. Göreceli yollar, Claude Code'un çalıştığı proje kökünden çözümlenir.
Topluluk tartışmalarından en iyi uygulamalar:
- Kanca komut dosyalarını .claude/hooks/ dizinine kaydedin
- Açıklayıcı adlar kullanın: validate-typescript.sh yerine hook1.sh
- Komut dosyalarını çalıştırılabilir hale getirin: chmod +x .claude/hooks/*.sh
- Shebang satırı ekleyin: #!/usr/bin/env bash veya #!/usr/bin/env python3
- Bash komut dosyalarında set -e ile hata işleme ekleyin
Gelecek Kanca Yetenekleri
GitHub özellik istekleri planlanan ve istenen kanca geliştirmelerini ortaya koymaktadır:
- Satır içi komut dosyası kancaları: Harici dosyalara ihtiyaç duymadan doğrudan settings.json'da kanca mantığı tanımlayın
- MCP araç entegrasyonu: Kabuk komutları yerine MCP sunucu araçlarını kancalardan çağırın
- Çoklu ajan işbirliği: Farklı makinelerdeki Claude örnekleri arasında koordinasyon sağlayan kancalar
- Gelişmiş yazım: Kanca girdi/çıktı şemaları için TypeScript tür tanımları
GitHub sorunu #4274'e göre, entegre kanca türleri (MCP aracı, satır içi komut dosyası, API çağrısı) isteği, yapılandırmayı basitleştirmeyi ve geliştirici deneyimini iyileştirmeyi amaçlamaktadır.
Sıkça Sorulan Sorular
Kancalar Claude'un tehlikeli komutları yürütmesini engelleyebilir mi?
Evet. PreToolUse kancaları, 1 koduyla çıkarak herhangi bir araç yürütülmesini engelleyebilir. Bu, dosya düzenlemelerini, komut yürütülmesini ve MCP araç çağrılarını içerir. Kanca, işlemin yapılmasına izin verilmeden önce tüm araç girdisini alır ve herhangi bir kritere karşı doğrulayabilir.
Çalışmayan bir kancayı nasıl hata ayıklarım?
Claude Code'u başlatmadan önce CLAUDE_DEBUG=1 ile hata ayıklama günlüğünü etkinleştirin. Hangi kancaların eşleştiği, gönderilen JSON girdisi, stdout/stderr çıktısı ve çıkış kodları dahil olmak üzere kanca yürütme ayrıntıları için oturum günlüklerini kontrol edin. Örnek JSON'u kanca komut dosyasına yönlendirerek kancaları bağımsız olarak test edin.
Kancalar tüm Claude Code platformlarıyla çalışır mı?
Kancalar CLI, masaüstü uygulaması ve VS Code uzantısında çalışır. Resmi belgelere göre, kancalar dosya sistemine erişimi olan Claude Code'un çalıştığı her yerde yürütülür. Tarayıcı tabanlı Claude ve mobil uygulamalar, sanal alan kısıtlamaları nedeniyle kancaları desteklemez.
Kancalar Claude'un yanıtlarını veya davranışını değiştirebilir mi?
Komut dosyası kancaları, Claude'un davranışını etkileyen talimatları enjekte eder. Ajan kancaları, olayı özel alt ajanlara devreder. Ancak, kancalar Claude'un ürettiği metni veya akıl yürütme sürecini doğrudan değiştiremez—bağlam sağlayarak ve işlemleri engelleyerek çalışırlar.
Async ve sync kancalar arasındaki fark nedir?
Senkron kancalar, tamamlanana veya zaman aşımına uğrayana kadar Claude'un iş akışını engeller. Asenkron kancalar arka planda engellemeden çalışır. Sync kancalar çıkış kodları aracılığıyla işlemleri önleyebilir. Async kancalar, Claude kanca tamamlanmadan devam ettiği için engelleyemez. Günlük kaydı ve bildirimler için async, doğrulama için sync kullanın.
Kancaları bir ekiple nasıl paylaşabilirim?
.claude/settings.json dosyasını sürüm kontrolüne işleyin. Proje düzeyindeki kancalar, depoyu klonlayan tüm ekip üyeleri için geçerlidir. Kuruluş genelindeki politikalar için, ekipler üyelerin ~/.claude/settings.json dosyasına kopyaladığı paylaşılan bir kullanıcı düzeyinde ayarlar dosyası tutabilir.
HTTP kancaları güvenlik duvarlarının arkasındaki dahili API'leri çağırabilir mi?
Evet, Claude Code o API'lere ağ erişimi olan bir ortamda çalışıyorsa. HTTP kancaları, Claude Code'u çalıştıran makineden standart POST istekleri yapar. Kurumsal güvenlik duvarları ve VPN'ler normal şekilde geçerlidir. Belgelerde bahsedilen sanal alan proxy'si, ağ yönlendirmesini değil, ortam değişkeni maruziyetini kontrol eder.
Kancalar Claude Code'un belirteç kullanımını artırır mı?
Komut dosyası kancaları, metni Claude'un bağlamına enjekte ederek belirteçleri tüketir. Komut ve HTTP kancaları doğrudan belirteç kullanımını etkilemez, ancak çıktıları (hata mesajları, öneriler) konuşma bağlamının bir parçası haline gelir. Açıklayıcı mesajlarla çıkış kodu 2, basit engelleme ile çıkış kodu 1'den daha fazla bağlam ekler.
Sonuç
Claude Code kancaları, yapay zeka yardımcısını güçlü bir araçtan tam otomatik bir geliştirme platformuna dönüştürür. Olay sistemi, oturum başlatmadan bağlam sıkıştırmaya kadar Claude'un iş akışının tüm noktalarında kesme noktaları sağlar.
Komut kancaları yerel doğrulama ve biçimlendirmeyi ele alır. HTTP kancaları harici hizmetleri ve veritabanlarını entegre eder. Komut dosyası kancaları bağlam enjeksiyonu yoluyla davranışı değiştirir. Birlikte, ekip politikalarını zorlayan, kod kalitesini koruyan ve mevcut geliştirme altyapısıyla entegre olan otomasyon desenlerini etkinleştirirler.
Eşleştirici sistemi, kancaları belirli araçlara ve dosya desenlerine göre filtreler. Çıkış kodları ve JSON çıktısı karar akışını kontrol eder. Asenkron yürütme, yavaş işlemlerin engellenmesini önler. Tam yapılandırma şeması, basit otomatik biçimlendirmeden karmaşık çok aşamalı doğrulamaya kadar her şeyi destekler.
Kod biçimlendirme için temel PostToolUse kancalarıyla başlayın. Politikalar ortaya çıktıkça PreToolUse doğrulaması ekleyin. Davranış değişikliği için komut dosyası kancalarıyla deney yapın. Ekip çapında uygulama için HTTP entegrasyonları oluşturun.
Yeni yetenekler çıktıkça eksiksiz kanca referansı ve güncellenmiş yapılandırma şeması için resmi Claude Code belgelerini kontrol edin.
