Claude Kod Kancaları Nedir ve Nasıl Kullanılır

Vibe Coders için Anthropic'in Claude Code gibi araçları, geliştiricilerin projelerini yazma, hata ayıklama ve yönetme şeklini dönüştürüyor. Claude Code, terminalinizde yaşayan, tüm kod tabanınızı anlama, dosya sisteminizle etkileşime girme, komutları çalıştırma ve hatta dokümantasyon için web'de gezinme yeteneğine sahip "ajanik bir kodlama aracı" olarak işlev görür. Doğal dil istemleri aracılığıyla yeni özellikler yazma, hataları düzeltme ve kodu yeniden düzenleme gibi görevlerde üstündür.

Ancak, Büyük Dil Modellerinin (LLM'ler) temel bir özelliği olasılıksal doğalarıdır. Bu, yaratıcı problem çözmeye izin verirken, bazen öngörülemezliğe yol açabilir. Bir dosya değiştirildikten sonra linting yapmak veya yeni bir fonksiyon yazıldıktan sonra testleri çalıştırmak gibi belirli eylemlerin her seferinde hatasız bir şekilde gerçekleşmesini isteyebilirsiniz. LLM'nin bunu her durumda hatırlamasına güvenmek tutarsız olabilir.

İşte burada Claude Code Kancaları devreye giriyor. Kancalar, Claude Code'un davranışları üzerinde deterministik, programatik kontrol sağlayan güçlü bir özelliktir ve LLM'nin bunları çalıştırmayı seçmesine güvenmek yerine belirli eylemlerin her zaman gerçekleşmesini sağlar.

Bu makale, tamamen otomatikleştirilmiş ve düzenli bir geliştirme iş akışı oluşturmak için Claude Code Kancalarını anlama, yapılandırma ve bunlardan yararlanma konusunda kapsamlı bir rehber niteliğindedir.

Claude Code Kancaları Nedir?

Özünde, Claude Code Kancaları, Claude Code'un yaşam döngüsündeki belirli noktalarda otomatik olarak yürütülen kullanıcı tanımlı kabuk komutlarıdır. Belirli eylemlerden önce veya sonra tetiklenecek şekilde yapılandırabileceğiniz tetikleyiciler olarak işlev görürler ve kendi özel mantığınızı, betiklerinizi ve komutlarınızı doğrudan Claude'un işlemlerine enjekte etmenize olanak tanır.

Kancalar, yapay zeka destekli yardım ile kural tabanlı otomasyon arasındaki boşluğu kapatır. Standartları uygulamanıza, tekrarlayan görevleri otomatikleştirmenize ve harici araçları iş akışınıza tam güvenilirlikle sorunsuz bir şekilde entegre etmenize olanak tanır.

Bir kancanın tetiklenebileceği dört ana yaşam döngüsü olayı vardır:

1. PreToolUse: Claude belirli bir aracı kullanmadan önce yürütülür (örn. bir dosyaya yazmadan önce).
2. PostToolUse: Bir araç başarıyla kullanıldıktan sonra yürütülür (örn. bir dosya değiştirildikten sonra).
3. Notification: Claude bir bildirim gönderdiğinde yürütülür (örn. kullanıcı girişi gerektiğinde veya uzun bir görevi tamamladığında).
4. Stop: Claude yanıtını oluşturmayı bitirip durduğunda yürütülür.

Bu olayları hedefleyerek, sürekli entegrasyon (CI) kontrolleri gibi modern yazılım geliştirmenin en iyi uygulamalarını yansıtan güçlü otomasyonlar oluşturabilirsiniz, ancak yerel geliştirme hızında.

Claude Code Kancalarının Anatomisi: Bir Yapılandırma Derinlemesine İncelemesi

Kancaları kullanmak için, bunları Claude Code ayarlar dosyanızda tanımlamanız gerekir. Bu, projenizdeki .claude/ dizininde bulunan settings.toml dosyanıza bir [[hooks]] tablosu eklenerek yapılır. Her kanca yapılandırmasının birkaç temel bileşeni vardır.

# .claude/settings.toml dosyasında Örnek Kanca

[[hooks]]
# Kancayı tetikleyen olay.
event = "PostToolUse" 

# (İsteğe Bağlı) Kancanın çalışması için koşullar.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# Yürütülecek kabuk komutu.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (İsteğe Bağlı) Komutun arka planda çalıştırılıp çalıştırılmayacağı.
run_in_background = false 

Her bir bölümü ayrıntılı olarak inceleyelim.

Claude Code Kancalarında event Alanı (Zorunlu)

Bu dize, dört yaşam döngüsü olayından hangisinin kancayı tetikleyeceğini belirtir.

• "PreToolUse"
• "PostToolUse"
• "Notification"
• "Stop"

Claude Code Kancalarında hooks.matcher (İsteğe Bağlı)

Eşleştirici, bir kancanın tam olarak ne zaman çalışması gerektiğini tanımlamanızı sağlayan şeydir. Eşleştiriciyi atlarsanız, kanca belirtilen event'in her örneği için çalışır. Örneğin, eşleştiricisi olmayan bir PostToolUse kancası, her araç çağrısından sonra tetiklenir.

Eşleştiricinin, olayları filtrelemek için kullanabileceğiniz üç alanı vardır:

• tool_name: Kullanılan aracın adıyla eşleşen bir dize. Bu, edit_file, git_commit veya run_command gibi belirli eylemleri hedeflemek için mükemmeldir.
• file_paths: Glob desenleri içeren bir dize dizisi. Kanca, yalnızca araç kullanımına dahil olan dosyalar bu desenlerden biriyle eşleşiyorsa çalışır. Örneğin, ["*.py"] tüm Python dosyalarını hedeflerken, ["src/components/**/*.jsx"] belirli bir dizindeki JSX dosyalarını hedefler.
• query: Bir araca verilen girişle eşleşen bir dize. Bu, npm içeren bir komutla run_command aracı yalnızca kullanıldığında bir kancayı çalıştırmak gibi daha spesifik tetikleyiciler için kullanışlıdır.

Claude Code Kancaları için command Alanı (Zorunlu)

Bu, kancanın kalbidir—tetikleyici koşullar karşılandığında yürütülecek kabuk komutu. Bu komut, kullanıcı hesabınızla aynı izinlerle çalışır, bu nedenle terminalinizde yapabileceğiniz her şeyi yapabilir.

Komutları dinamik hale getirmek için Claude Code, kancayı tetikleyen olaydan gelen bağlamla doldurulan bir dizi ortam değişkeni sağlar.

Mevcut Ortam Değişkenleri:

• $CLAUDE_EVENT_TYPE: Olayın türü (PreToolUse, PostToolUse, vb.).
• $CLAUDE_TOOL_NAME: Kullanılan aracın adı (örn. edit_file).
• $CLAUDE_TOOL_INPUT: Araca JSON formatında iletilen ham giriş parametreleri.
• $CLAUDE_FILE_PATHS: Araç çağrısıyla ilgili dosya yollarının boşlukla ayrılmış listesi. Bu, dosyaları biçimlendiricilere, lint araçlarına veya test çalıştırıcılarına iletmek için inanılmaz derecede kullanışlıdır.
• $CLAUDE_NOTIFICATION: Bildirim mesajının içeriği (yalnızca Notification olayı için).
• $CLAUDE_TOOL_OUTPUT: Aracın yürütülmesinden gelen çıktı (yalnızca PostToolUse olayı için).

Claude Code Kancaları için run_in_background Ayarı (İsteğe Bağlı)

Bu bir boolean değerdir (true veya false). true olarak ayarlanırsa, kancanın komutu ayrı bir süreçte yürütülür ve Claude devam etmeden önce tamamlanmasını beklemez. Bu, Claude'un sonraki eylemlerini engellemek istemediğiniz kapsamlı test paketleri veya derleme süreçleri gibi uzun süren görevler için idealdir. Varsayılan değer false'tur.

Claude Code Kancaları için Pratik Kullanım Durumları ve Örnekler

Kancaların gerçek gücü, onları gerçek dünya geliştirme iş akışlarına uyguladığınızda ortaya çıkar. İşte başlamanız için bazı pratik örnekler.

1. Claude Code Kancaları ile Otomatik Linting ve Biçimlendirme

Projeniz genelinde tutarlı bir kod stilini otomatik olarak uygulayın. Bu kanca, Claude'un düzenlediği herhangi bir Python dosyasında ruff linter'ı ve black biçimlendiriciyi çalıştırır.

Dosya: .claude/settings.toml

[[hooks]]
event = "PostToolUse"

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py"]

# Düzenlenen Python dosyalarını lint etmek, düzeltmek ve biçimlendirmek için komut.
command = "echo 'Running auto-formatter...' && ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

2. Claude Code Kancaları ile Otomatik Test Çalıştırma

Test güdümlü geliştirmenin (TDD) temel bir uygulaması, testler yazmak ve ardından bu testleri geçmek için kod yazmak, her şey çalışana kadar yinelemektir. "Testleri çalıştır" adımını bir kanca ile otomatikleştirebilirsiniz. Bu örnek, src/ veya tests/ dizinindeki bir dosya her değiştirildiğinde pytest'i çalıştırır.

Dosya: .claude/settings.toml

[[hooks]]
event = "PostToolUse"
run_in_background = true # Testler yavaş olabilir, arka planda çalıştırın.

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["src/**/*.py", "tests/**/*.py"]

# Test paketini çalıştırmak için komut.
command = "pytest"

3. Claude Code Kancaları aracılığıyla Özel Masaüstü Bildirimleri

Claude'dan uzun süreli bir görev gerçekleştirmesini isterseniz, bilgisayarınızdan uzaklaşabilirsiniz. Bu kanca, Claude'un dikkatinizi çekmesi gerektiğinde telefonunuza veya masaüstünüze bir anlık bildirim göndermek için ntfy (basit bir HTTP tabanlı yayın-abonelik bildirim hizmeti) gibi bir komut satırı aracı kullanır.

Dosya: .claude/settings.toml

[[hooks]]
event = "Notification"

# Bildirim içeriğini herkese açık bir ntfy.sh konusuna gönderir.
# Gizlilik için kendinizinkini barındırabilirsiniz.
command = 'ntfy publish my-claude-alerts "$CLAUDE_NOTIFICATION"'

4. Claude Code Kancalarını Kullanarak Ön-Commit Sağlık Kontrolleri

Git kancalarına benzer şekilde, bir commit yapılmadan önce kaliteyi sağlamak için Claude Code Kancalarını kullanabilirsiniz. Bu örnek, Claude'un git_commit aracını kullanmasına izin verilmeden hemen önce API anahtarlarını kontrol etmek veya diğer doğrulama adımlarını gerçekleştirmek için özel bir betik çalıştırır.

Dosya: .claude/settings.toml

[[hooks]]
event = "PreToolUse"

[hooks.matcher]
tool_name = "git_commit"

# Bir ön-commit kontrol betiği çalıştırmak için komut.
# Betik, commit'i durdurmak için sıfır olmayan bir kodla çıkmalıdır.
command = "sh ./.claude/pre-commit-checks.sh"

Claude Code Kancalarınızı Kurma ve Hata Ayıklama

Kancalarla başlamak kolaydır, ancak beklendiği gibi çalıştıklarından emin olmak için doğrulama ve hata ayıklama çok önemlidir.

1. Yapılandırmanızı Oluşturun: Projenizin kök dizininde bir .claude/settings.toml dosyanız olduğundan emin olun. [[hooks]] yapılandırmalarınızı oraya ekleyin.
2. Yapılandırmayı Doğrulayın: settings.toml dosyanızı kaydettikten sonra, Claude Code terminal arayüzünde /hooks komutunu çalıştırın. Bu özel komut, şu anda yüklü olan kanca yapılandırmalarınızı görüntüleyerek Claude'un bunları doğru bir şekilde ayrıştırıp ayrıştırmadığını anında görmenizi sağlar.
3. Hataları Kontrol Edin:

• Geçersiz TOML: settings.toml dosyanızın geçerli bir sözdizimine sahip olduğundan emin olun. Yanlış yerleştirilmiş bir parantez veya tırnak işareti, yüklenmesini engelleyebilir.
• Komut Sorunları: command'ınızı doğrudan kabuğunuzda test ederek beklendiği gibi çalıştığından emin olun. Yazım hatalarını kontrol edin ve gerekli yürütülebilir dosyaların (black, pytest, ntfy, vb.) sisteminizin PATH'inde olduğundan emin olun.
• Hata Ayıklama Değişkenleri: Ortam değişkenlerinin hangi değerleri tuttuğunu görmek için, bunları bir günlük dosyasına yazmak için echo kullanın. Örneğin: command = "echo 'Araç: $CLAUDE_TOOL_NAME, Dosyalar: $CLAUDE_FILE_PATHS' >> /tmp/claude_hook.log"

Sonuç: Claude Code Kancalarının Gücü

Claude Code Kancaları, aracı son derece yetenekli bir kodlama yardımcısından, tamamen entegre, deterministik bir geliştirme ortağına yükseltir. Basit, güçlü kurallar tanımlayarak, iş akışınızın sıradan ama kritik kısımlarını otomatikleştirebilir, böylece yazılım mühendisliğinin karmaşık, yaratıcı yönlerine odaklanmanızı sağlayabilirsiniz. İster kod kalitesini zorlamak, ister TDD döngünüzü basitleştirmek veya üçüncü taraf hizmetlerle entegre olmak olsun, kancalar Claude Code'u tam ihtiyaçlarınıza göre uyarlamak için gerekli sağlam çerçeveyi sağlar.

Claude Code'un yeteneklerine daha aşina oldukça, basit bir biçimlendirme kancasıyla başlayın ve ardından daha karmaşık otomasyonları keşfedin. Bu özelliğin, öngörülebilir, verimli ve gerçekten kişiselleştirilmiş bir yapay zeka destekli geliştirme ortamı oluşturmak için vazgeçilmez olduğunu hızla göreceksiniz.