Claude Code Kancaları: İş Akışı Otomasyonuna Pratik Bir Rehber

Claude Code ile çalışırken yaygın bir sorun fark edeceksiniz: İyi kod yazıyor ama biçimlendirme, testleri çalıştırma veya güvenlik protokollerine uyma gibi önemli adımları unutuyor. Aynı hatırlatmaları tekrar tekrar yapmak zorunda kalıyorsunuz. Claude Code Kancaları, iş akışınızın belirli noktalarında kabuk komutlarını otomatik olarak çalıştırarak bu hatırlatmaları otomatikleştirmenizi sağlar.

Bu eğitimde, kod biçimlendirme, test yürütme, bildirim ve dosya koruma için kancaların nasıl kurulacağını ele alıyorum. Manuel müdahale olmadan geliştirme standartlarınızı uygulayan bir otomasyon sistemi oluşturacaksınız.

Claude Code hakkında daha fazlası için Claude Code en iyi uygulamalar rehberimize ve Claude Yetenekleri eğitimimize göz atın. Proje düzeyinde talimatların nasıl yapılandırılacağını öğrenmek istiyorsanız, CLAUDE.md yazma rehberimize bakın.

Kısaca

• Claude Code Kancaları, Claude Code’un yaşam döngüsünün belirli noktalarında (araç çağrılarından önce/sonra, oturum başlangıcında, Claude durduğunda) otomatik olarak çalışan kabuk komutlarıdır

• Bunları JSON kullanarak olaylar, eşleştiriciler ve komutlarla .claude/settings.json (proje) veya ~/.claude/settings.json (genel) içinde yapılandırın

• Tehlikeli işlemleri gerçekleşmeden önce engellemek için PreToolUse kancalarını kullanın (çıkış kodu 2 = engelle)

• Claude kod yazdıktan sonra biçimlendirme, lint etme veya test çalıştırma gibi temizlik görevleri için PostToolUse kancalarını kullanın

• Kancalar stdin üzerinden JSON bağlamı alır ve sonuçları çıkış kodları, stdout ve stderr aracılığıyla iletir

Claude Code Kancaları Nedir?

Claude Code Kancaları, yapay zekâ ile kodlama oturumunuz sırasında belirli olaylar meydana geldiğinde otomatik olarak çalışan kabuk komutlarıdır. Bunları, özel betiklerinizi tam zamanında çalıştıran otomatik tetikleyiciler olarak düşünün—Claude bir dosya yazmadan önce, bir komut çalıştırdıktan sonra veya size bir bildirim gönderdiğinde.

Sistem, Claude Code’un eylemlerini izler ve bunları bir yapılandırma dosyasında tanımladığınız kurallarla eşleştirir. Eşleşme olduğunda, belirttiğiniz komut az önce ne olduğuna dair bağlama erişerek çalışır. Bu da Claude’un davranışını kontrol etmenizi sağlar ve aksi halde manuel müdahale gerektirecek tekrarlı görevleri otomatikleştirmenize imkân tanır.

İşte Claude her Python dosyası yazdığında bir kod biçimlendiricisini çalıştıran temel bir kanca:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black ."
          }
        ]
      }
    ]
  }
}

Bu kanca üç bölümden oluşur: 

• Olay: PostToolUse (Claude bir eylemi bitirdikten sonra)

• Eşleştirici: Write (yalnızca dosya yazarken)

• Komut: python -m black . (geçerli dizindeki Python dosyalarını biçimlendirir)

Kanca, betiğin girdisine gönderilen JSON verileri aracılığıyla Claude’un az önce ne yaptığına dair ayrıntılı bilgi alır; böylece belirli dosya değişikliklerine yanıt veren daha gelişmiş otomasyonlar kurabilirsiniz.

Claude Code otomasyonunda daha ileri gitmek isterseniz, Claude Code Rutinleri eğitimimiz, kancaları ve ajanları bulutta yinelenen şekilde nasıl zamanlayacağınızı gösterir.

Şimdi sıfırdan kanca oluşturmayı ve bunları Claude Code’a kaydetmeyi inceleyelim.

Ön Koşullar

Başlamadan önce birkaç şeye ihtiyacınız olacak:

• Claude Code kurulu ve çalışıyor: Claude Code’u temel kodlama görevleri için kullanmaya aşina olmalısınız

• Komut satırı aşinalığı: Kancalar kabuk komutları çalıştırır; bu nedenle işletim sisteminiz için temel terminal komutlarını yazmayı bilmeniz gerekir

• Metin düzenleyici erişimi: Kancalarınızı kurmak için JSON yapılandırma dosyalarını düzenleyeceksiniz

• Proje dizini: Önemli işleri etkilemeden kancaları güvenle test edebileceğiniz bir kodlama projesi

Bir kabuk betikleme uzmanı olmanıza gerek yok; ancak ls, cd ve temel dosya işlemleri gibi komutları nasıl çalıştıracağınızı bilmek örnekleri takip etmenize yardımcı olur. Bash betiklemeye veya terminale yeniyseniz, Kabuklara Giriş kursumuzu öneririm.

Claude Code Kancalarına Başlangıç

Artık kancaların ne olduğunu anladığınıza göre, ilk otomasyonunuzu kuralım. Süreç; ihtiyacınız için doğru olayı seçmeyi, basit bir kuralı yapılandırmayı ve bunu temel bir komutla test etmeyi içerir.

Kanca olaylarını anlama

Claude Code 25’ten fazla kanca olayı sunar. Aşağıdaki tablo en sık kullanacağınız 10’unu kapsar. Tam liste için resmî kanca referansına bakın.

PreToolUse ve PostToolUse en yaygın olaylardır. PreToolUse, Claude bir dosya yazma veya bir komut çalıştırma gibi bir eylemi gerçekleştirmeden önce çalışır; bu da doğrulama veya tehlikeli işlemleri engelleme için idealdir. PostToolUse, Claude bir eylemi tamamladıktan sonra çalışır; bu da kod biçimlendirme veya test çalıştırma gibi temizlik görevleri için uygundur.

UserPromptSubmit, Claude’a bir istem gönderdiğinizde, işleme başlamadan önce tetiklenir. Bunu, konuşmanıza bağlam eklemek veya istemlerin belirli gereklilikleri karşıladığını doğrulamak için kullanabilirsiniz.

Notification, Claude sizden komut çalıştırma izni istemesi veya girdinize ihtiyaç duyması gibi uyarılar gönderdiğinde çalışır. PermissionRequest, Claude Code bir izin iletişim kutusu görüntülediğinde tetiklenir ve kullanıcının yerine isteği otomatik olarak onaylamanıza veya reddetmenize olanak tanır.

Stop ve SubagentStop, Claude yanıt vermeyi bitirdiğinde tetiklenir; bu da son kontroller veya rapor üretimi için kullanışlıdır. İkisi arasındaki fark, Stop’un Claude genel yanıtını bitirdiğinde, SubagentStop’un ise bir araç tarafından başlatılan yardımcı bir “alt ajan” işini bitirdiğinde tetiklenmesidir.

Kalan olaylar PreCompact, SessionStart ve SessionEnd yaşam döngüsüne özgü durumları ele alır. PreCompact, Claude konuşma geçmişini kısaltmadan hemen önce çalışır. ‘SessionStart’ yeni bir oturumun başında varsayılanları ayarlamak için ateşlenir ve SessionEnd oturum kapandığında tetiklenir; bu da temizlik veya son raporlama için olanak sağlar.

Eşleştiricileri anlama

Eşleştiriciler, hangi Claude Code eylemlerinin bir kancayı tetikleyeceğine karar veren filtrelerdir. Teknik olarak, onlar düzenli ifadeler olarak yorumlanan dizelerdir; bu nedenle bire bir eşleşmeler veya daha esnek kalıplar kullanabilirsiniz. 

En ilgili eşleştiriciler, Write (Claude bir dosya yazdığında tetiklenir) veya Edit (içerik düzenlerken tetiklenir) gibi basit olanlar ile birden çok eylemi kapsayan Edit|Write gibi kombinasyonlardır. 

“Notebook” ile başlayan tüm araçları eşleştirmek için Notebook.* gibi önek kalıpları da kullanabilirsiniz. Kancanın her eylemde tetiklenmesini istiyorsanız evrensel regex .*’i, boş bir dizeyi ("") veya matcher’ı boş bırakmayı kullanın.

Eşleştiriciler büyük/küçük harf duyarlıdır ve yalnızca eylem adlarında çalışır; bu nedenle mümkün olduğunca belirli tutmak en iyisidir. Daha ince ayar gerektiğinde (örneğin, kancayı belirli dosya türleriyle sınırlamak için) Claude’un kancaya aktardığı JSON yükünü okuyabilir ve kendi regex’inizi veya koşullarınızı orada uygulayabilirsiniz.

Claude Code’da ilk kancanızı oluşturma

Claude Code, kancaları kurmak için iki yol sunar: etkileşimli /hooks komutu veya yapılandırma dosyalarını doğrudan düzenlemek. Başlangıç için daha kullanıcı dostu olduğundan etkileşimli yaklaşımla başlayalım.

/hooks komutunu kullanma:

1. Claude Code’u açın ve sohbet arayüzüne /hooks yazın

2. Tetikleyici olayınızı seçin (bu örnek için PostToolUse’u seçin)

3. Menüden "Yeni kanca ekle"yi seçin

4. Eşleştirici kalıbınızı ayarlayın (dosya yazmayı hedeflemek için Write girin)

5. Komutunuzu girin:

• Mac: say "Task complete"

• Windows: powershell -c [console]::beep()

• Linux: spd-say "Task complete"

6. Yapılandırmayı kaydedin ve Esc’e üç kez basarak Claude Code’a geri dönün

/hooks komutu ayarlar dosyanızı otomatik olarak günceller ve yapılandırmayı yeniden yükler. Mevcut kancalarınızı görüntülemek veya değişiklik yapmak için istediğiniz zaman /hooks kullanabilirsiniz.

Yapılandırma dosyalarını doğrudan düzenlemeyi tercih ediyorsanız, kancalar genel ayarlar için ~/.claude/settings.json içinde, proje dizininizde .claude/settings.json içinde (ekip paylaşımı kancalar için depoya bunu ekleyin) veya varsayılan olarak gitignore edilen kişisel kancalar için .claude/settings.local.json içinde bulunur. Örneğimiz için şu şekilde görünür:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Task complete'"
          }
        ]
      }
    ]
  }
}

Dosyayı elle düzenledikten sonra, Claude Code’u yeniden başlatın veya yapılandırmanızı yeniden yüklemek için /hooks komutunu kullanın. Artık Claude her dosya yazdığında bir sesli bildirim duyacaksınız.

Kancanızı test etme

İlerlemeden önce, kancanızın gerçekten çalıştığını doğrulayın:

1. Claude’dan herhangi bir Python dosyası yazmasını isteyin (örn. "hello.py adında hello world yazdıran bir dosya oluştur")

2. Claude yazma işlemini tamamladığında sesli bildirimi duymalısınız

3. Bir şey duymuyorsanız, hata iletilerini görmek için Ctrl-O tuşuna basarak Claude Code’un dökümünü kontrol edin

4. Yaygın sorunlar arasında kanca komutunun bulunamaması, yanlış dosya izinleri veya yapılandırma dosyanızda sözdizimi hataları yer alır

Bu temel testin çalışır hale gelmesi, daha karmaşık kancalar oluştururken size hata ayıklama zamanı kazandırır. Kısa süre önce ayarlar dosyasını elle düzenlediyseniz, eşleştiriciyi veya olayı değiştirdiyseniz ya da bir kanca komutunda kullanmak istediğiniz yeni araçlar kurduysanız, yapılandırmayı yeniden yüklemek için /hooks’u yeniden açmak veya Claude’u yeniden başlatmak yardımcı olabilir.

Bu temel model (olay, eşleştirici, komut) tüm kanca otomasyonunun temelini oluşturur. Aynı olay tetiklendiğinde eşzamanlı olarak çalıştırılacak birden fazla komut ekleyerek bunu genişletebilirsiniz. Örneğin, Claude bir dosya yazdığında hem bir ses çalmak hem de bir yedek oluşturmak isteyebilirsiniz. 

Aynı olay içinde farklı araçlar için ayrı eşleştiriciler de oluşturabilirsiniz; böylece dosya yazma, kod düzenlemeden farklı eylemleri tetikler. Aynı araç kalıbıyla eşleşen tüm kancalar paralel çalışır. Aynı olay için birden fazla eşleştirici yapılandırırsanız, her kanca kendi eşleştiricisi tetiklendiğinde çalışır.

Kanca Girdileriyle Çalışma

Claude Code bir kancayı tetiklediğinde, standart girdi (stdin) üzerinden az önce ne olduğuna dair bilgi gönderir; bu, komutunuz çalıştığında doğrudan komutunuza akan bir veri akışıdır. Kancaları, rastgele zamanlarda çalışan betiklerden güçlü yapan şey bu veridir. 

Claude Code bu bilgiyi JSON olarak paketler ve ister basit bir terminal komutu olsun ister özel bir betik, yapılandırdığınız her komuta iletir.

Kanca girdilerinin yapısı

Her kanca, geçerli oturum hakkında temel alanları içeren bir JSON nesnesi alır:

{
  "session_id": "abc123",
  "transcript_path": "/Users/you/.claude/projects/my-project/conversation.jsonl", 
  "cwd": "/Users/you/my-project",
  "hook_event_name": "PostToolUse"
}

Her bir bileşeni çevirelim:

• session_id: geçerli konuşmanızı tanımlar

• transcript_path: konuşma geçmişini işaret eder

• cwd: çalışma dizinini gösterir

• hook_event_name: hangi olayın tetiklendiğini bildirir

Bu bağlama sahip olmak, kancalarınızın akıllı kararlar vermesini sağlar: Hangi konuşmanın bir eylemi tetiklediğini takip edebilir, gerekirse tüm sohbet geçmişine erişebilir veya komutları doğru dizinde çalıştırabilirsiniz.

Olaya dayalı girdi farklılıkları

PreToolUse ve PostToolUse gibi araç olayları eylem hakkında ekstra ayrıntılar içerir; kancaların otomasyon için gerçekten kullanışlı olduğu yer burasıdır. PreToolUse’ta tool_input belirtilir; PostToolUse’ta ise buna ek olarak tool_response bulunur:

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.py",
    "content": "print('Hello world')"
  },
  "tool_response": {
    "filePath": "/path/to/file.py", 
    "success": true
  }
}

Kanca girdisinde file_path, yazılan veya düzenlenen dosyanın yolunu gösterirken, content aracın yazmak üzere olduğu metnin tamamını içerir. Yürütmeden sonra, aracın yanıtı, hangi dosyaya gerçekten dokunulduğunu doğrulamak için son filePath’i (camelCase’e dikkat edin) tekrarlar ve işlemin doğru şekilde tamamlanıp tamamlanmadığını belirten bir success bayrağı içerir. 

Bu ayrıntılı bilgi, kancalarınızın fiilen olanlara göre farklı şekilde yanıt vermesini sağlar. Yalnızca Python dosyalarını biçimlendirebilir, yalnızca önemli dizinleri yedekleyebilir veya yalnızca belirli dosya türleri değiştirildiğinde bildirim gönderebilirsiniz.

UserPromptSubmit gibi olaylar, araçları içermediklerinden daha basittir:

{
  "session_id": "abc123",
  "hook_event_name": "UserPromptSubmit", 
  "prompt": "Write a function to calculate factorial"
}

UserPromptSubmit kancalarının yapılandırmalarında eşleştirici kullanılmadığını unutmayın. Araç işlemleri değil, tüm istemlerde tetiklenirler. Bu, konuşmaları günlüğe kaydetmek, proje bağlamını otomatik olarak eklemek veya Claude işlemeden önce istemleri doğrulamak için mükemmeldir.

Uygulamada kanca girdisini okuma

Her kullanıcı istemini günlüğe kaydeden bir kanca oluşturalım. Bu, özellikle uzun kodlama oturumlarında Claude’dan ne yapmasını istediğinizi takip etmeyi kaybetme sorununu çözer. Önce kanca yapılandırması:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/log_prompts.py"
          }
        ]
      }
    ]
  }
}

Sonra, ~/.claude/log_prompts.py konumunda aşağıdaki içerikle Python betiğini oluşturun:

#!/usr/bin/env python3
import json
import sys
from datetime import datetime

# Read JSON data from stdin
input_data = json.load(sys.stdin)

# Extract information
session_id = input_data.get("session_id", "unknown")
prompt = input_data.get("prompt", "")
timestamp = datetime.now().isoformat()

# Log the prompt
log_entry = f"{timestamp} | Session: {session_id[:8]} | {prompt}\n"
with open("prompt_history.txt", "a") as f:
    f.write(log_entry)

Betik, Claude Code’un gönderdiği JSON verisini okur ve istemi oturum bağlamıyla birlikte günlüğe kaydeder. Bu, haftalar sonra bir sorunu nasıl çözdüğünüzü hatırlamanız gerektiğinde paha biçilmez hale gelen aranabilir bir etkileşim geçmişi oluşturur.

Kanca Çıktılarıyla Çalışma

Kanca komutunuz çalıştıktan sonra, ne olduğunu ve normal şekilde devam edilip edilmeyeceğini Claude Code’a bildirmesi gerekir. Bu kontrol mekanizması, kancaları basit günlükleme araçlarından, Claude’un davranışını yönlendirebilen güçlü iş akışı otomasyonlarına dönüştürür. Bu, üç kanal aracılığıyla gerçekleşir: standart çıktı (stdout), standart hata (stderr) ve çıkış kodları.

Çıkış kanalları ve çıkış kodları

Standart çıktı (stdout) normal çıktı anlamına gelir. Örneğin bir şey yazdırırsanız, stdout’a gider. Çoğu kanca için, bu, Ctrl-O’ya bastığınızda Claude Code’un dökümünde görünen şeydir ve ana konuşmayı kalabalıklaştırmadan otomasyonunuzun ne yaptığının kaydını verir.

Standart hata (stderr) hata iletilerini ifade eder. stderr’e şu şekilde yazabilirsiniz: 

• Python: print("message", file=sys.stderr) veya

• Komut satırı: echo "message" >&2

Temel fark, stderr’in otomatik işleme için doğrudan Claude’a gönderilebilmesidir; bu da kancalarınızın tespit ettiği sorunlara yanıt vermesini sağlar.

Çıkış kodları, Claude Code’a sırada ne yapılacağını söyler:

• Çıkış kodu 0: Başarılı (kullanıcıya stdout gösterilir)

• Çıkış kodu 2: Engelleyici hata (stderr, Claude’a gönderilir)

• Diğer kodlar: Engelleyici olmayan hata (stderr kullanıcıya gösterilir, ancak devam edilir)

Bu sistem, Claude’un ne zaman durması, devam etmesi veya otomasyonunuzun keşfettikleri hakkında geri bildirim alması gerektiği üzerinde ince ayar kontrolü sağlar. Şimdi en önemli iki çıkış kodu için örneklere bakalım.

Çıkış kodu 0: Normal işlem

Çoğu kanca, her şeyin yolunda gittiğini belirtmek için çıkış kodu 0’ı kullanır. İşte dosya işlemlerini günlüğe kaydeden ve kullanıcıyı bilgilendiren eksiksiz bir kanca:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import datetime; open('activity.log','a').write('File written: ' + datetime.datetime.now().isoformat() + '\\n'); print('Logged file operation')\""
          }
        ]
      }
    ]
  }
}

Bu kanca iki komut çalıştırır: bir dosyaya günlük kaydı ve ardından dökümde bir ileti yazdırma. Bunu yapmanın birçok yolu vardır; ancak bu yaklaşım çapraz platformdur ve komut satırı özellerine bağımlı değildir.

Açık bir çıkış kodu olmadığından varsayılan olarak 0’dır. Yazdırılan ileti Claude Code’un dökümünde görünür ve günlüklemenin çalıştığına dair geri bildirim sağlar. Bu model, denetim izleri oluşturmak veya Claude’un zaman içinde projenizde yaptığı değişiklikleri izlemek için idealdir.

Çıkış kodu 2: Geri bildirimle engelleme

Çıkış kodu 2, hata iletinizi doğrudan Claude’a gönderir ve onun otomatik olarak yanıt vermesine olanak tanır. İşte kancaların sadece otomasyon değil, bir güvenlik mekanizması haline geldiği yer. İşte tehlikeli dosya işlemlerini engelleyen bir kanca:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/security_check.py"
          }
        ]
      }
    ]
  }
}

Güvenlik kontrolü betiğini ~/.claude/security_check.py konumunda oluşturmanız gerekecek:

#!/usr/bin/env python3
import json
import sys

# Read hook input
input_data = json.load(sys.stdin)
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Check for dangerous patterns
dangerous_paths = ["/etc/", "/usr/", "production.conf"]
is_dangerous = any(pattern in file_path for pattern in dangerous_paths)

if is_dangerous:
    # Block the operation and tell Claude why
    print(f"Blocked modification of {file_path} - this appears to be a system or production file", file=sys.stderr)
    sys.exit(2)  # Sends stderr message to Claude
else:
    # Allow the operation
    print(f"Approved modification of {file_path}")
    sys.exit(0)  # Shows stdout in transcript

Bu kanca tehlikeli bir yol algıladığında 2 koduyla çıkar. Claude Code, stderr iletisini Claude’a gönderir; o da size işlemin neden engellendiğini açıklayabilir ve alternatifler önerebilir. Bu, sistem dosyalarına kazara zarar verilmesini önlerken Claude’u güvenlik ilkeleriniz hakkında bilgilendirmeye devam eder.

Claude Code için Akıllı Bir Bildirim Kancası Oluşturma

Girdi işlemeyi akıllı çıktı yönetimiyle birleştiren geliştirilmiş bildirim kancamızı oluşturalım. Bu, her dosya değişikliğinde uyarı veren orijinal kancamızdaki gürültü sorununu çözer:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/smart_notify.py"
          }
        ]
      }
    ]
  }
}

Bildirim betiğini ~/.claude/smart_notify.py konumunda oluşturun:

#!/usr/bin/env python3
import json
import sys
import os
import subprocess

# Read the hook input
input_data = json.load(sys.stdin)
tool_input = input_data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Categorize file importance
important_extensions = [".py", ".js", ".ts", ".java", ".cpp"]
config_files = ["Dockerfile", "requirements.txt", "package.json"]

is_code = any(file_path.endswith(ext) for ext in important_extensions)
is_config = any(filename in file_path for filename in config_files)

if is_code:
    # Important: notify and log
    print(f"Code file modified: {os.path.basename(file_path)}")
    subprocess.run(["say", "Code updated"], check=False)  # Mac
    sys.exit(0)  # Show message in transcript
elif is_config:
    # Very important: louder notification
    print(f"Configuration file changed: {os.path.basename(file_path)}")
    subprocess.run(["say", "Configuration updated - review changes"], check=False)
    sys.exit(0)
else:
    # Not important: silent success
    sys.exit(0)

Bu kanca, hangi dosyanın değiştirildiğini anlamak için girdiyi okur; dosya türüne göre bildirim önemine karar verir; önemli değişiklikleri döküme kaydetmek için stdout’u kullanır; dosya türüne bağlı olarak farklı sesli uyarılar tetikler ve bunlar engelleyici değil bilgilendirici eylemler olduğundan her zaman 0 koduyla çıkar.

Girdi analizi ve çıktı denetiminin birleşimi, bağlama göre akıllıca davranan ve hem size hem de Claude Code’a doğru düzeyde geri bildirim sağlayan bir kanca oluşturur. Her geçici dosya için rahatsız edici bildirimler almak yerine, yalnızca projeniz için gerçekten önemli olan değişiklikleri duyarsınız.

Lütfen bu örneğin macOS’ta bulunan say komutunu kullandığını unutmayın. Linux’ta notify-send kullanabilir, Windows’ta benzer bildirimler için bir PowerShell komutu tercih edebilirsiniz.

Claude Code Kancalarında Sık Karşılaşılan Tuzaklar

Kancalarla ilk haftasında çoğu kişinin tökezlediği birkaç nokta:

Kabuk profilindeki echo ifadeleri kancaları bozar. Kancalar, ~/.zshrc veya ~/.bashrc’inizi kaynak alan etkileşimsiz kabuklarda çalışır. Profilinizde koşulsuz echo ifadeleri varsa, bunlar kanca stdout’una metin ekler ve JSON ayrıştırmasını bozar. Bunları etkileşimli-kabuk kontrolüne sarın:

if [[ $- == *i* ]]; then
  echo "Welcome back"
fi

Stop kancaları sonsuza kadar döngüye girebilir. Çıkış kodu 2 ile çıkan bir Stop kancası, Claude’u çalışmaya zorlar. Betiğiniz girdideki stop_hook_active alanını kontrol etmiyor ve true olduğunda düzgün şekilde çıkmıyorsa, zaman aşımına kadar dönüp durursunuz. Her zaman erken çıkış önlemi ekleyin.

Eşleştiriciler büyük/küçük harf duyarlıdır. bash, Bash ile eşleşmez. Claude Code’da göründüğü hâliyle tam araç adını kullanın.

Çıktı 10.000 karakter ile sınırlıdır. Kancanız daha fazlasını üretirse, Claude’un bağlamına enjekte edilmeden önce kesilir. stdout’u özlü tutun ve modelin eyleme dökmesi gerekenleri yüzeye çıkarın.

Ekip düzeyi ve kişisel kancalar arasındaki karışıklık. .claude/settings.json içindeki kancalar ekip ile paylaşılır (depoya ekleyin). Paylaşmak istemediğiniz kişisel kancalar için varsayılan olarak gitignore edilen .claude/settings.local.json’u kullanın.

Kancalar ve yetenekler: hangisi ne zaman?

Kancalar ve Claude Yetenekleri farklı amaçlara hizmet eder ve birlikte en iyi şekilde çalışırlar. Bir yetenek, Claude’a bir şeyi nasıl yapacağını öğreten (prosedürler, kurallar, şablonlar) bir markdown dosyasıdır. Bir kanca ise, Claude’un ne karar verdiğinden bağımsız olarak bir kuralı deterministik şekilde uygular.

Bu ayrım önemlidir: bir yetenek, modelin baskı altında görmezden gelebileceği bir öneridir; bir kanca ise her seferinde çalışır. Ekibinizin geçiş prosedürünü belgelemek için bir yetenek yazın. Claude’un yazdığı her .sql dosyasında geçiş denetleyicisini çalıştırmak için bir PostToolUse kancası yazın. Yetenek Claude’u yetkin kılar; kanca ise Claude’u sorumlu kılar.

Claude Code Kancaları için İleri Düzey Kalıplar

Temel bildirim ve günlüklemenin ötesinde, kancalar ekiplerin her gün karşılaştığı gerçek geliştirme iş akışı sorunlarını çözebilir. Kendi projelerinize uyarlayabileceğiniz bazı fikirler burada.

Güzel olan şu ki, aslında bu kancaları elle inşa etmek zorunda değilsiniz. Aşağıdaki istem fikirlerinden birini ve dokümantasyondaki Kanca referansını Claude Code’a vererek ilgili kodu ve yapılandırma için JSON’u oluşturmasını sağlayabilirsiniz.

Bu kalıpların her biri, özel araçlarınıza ve iş akışınıza göre özelleştirilebilir. En büyük günlük sıkıntılarınızı çözenlerle başlayın ve kanca geliştirmede rahatladıkça otomasyonunuzu genişletin.

Güvenlik ve uyumluluk için ileri düzey kancalar

Kancalar, güvenlik kurallarını ve uyumluluk standartlarını uygulamak için harikadır. İşte dört kullanım durumu.

API anahtarı tarayıcısı

• Sorun: Sırların yanlışlıkla sürüm kontrolüne işlenmesi

• Tetikleyiciler: Herhangi bir dosya yazmadan önce

• Çözüm: Dosya içeriğini regex kalıplarıyla API anahtarları, belirteçler ve parolalar için tarama

“Kanca girdi JSON’unu okuyup dosya içeriğini çıkaran ve api_key=, token: veya password= gibi yaygın gizli biçimlerini tespit etmek için regex kalıpları kullanan bir Python betiği oluşturun.  Şüpheli her eşleşme için yerel doğrulama yapın ve asla ham sırları dışarıya göndermeyin. 

Yalnızca maskelenmiş parçaları (örn. 4 önek/sonek karakterini koruyun) veya hash’leri Anthropic API’sine göndererek şüpheli dizeleri analiz edin ve bunların gerçek sırlar mı yoksa değişken adları mı olduğunu belirleyin. Kod 2 ile çıkın ve tespit edilen sırlar ve daha güvenli alternatifler hakkında Claude’a geri bildirim sağlayın.”

Lisans başlığı uygulayıcı

• Sorun: Açık kaynak projelerinde yeni dosyalarda gerekli lisans başlıklarının eksik olması

• Tetikleyiciler: Kaynak kodu dosyalarını yazmadan önce

• Çözüm: Yeni .py, .js, .java dosyalarının uygun lisans metnini içerdiğini doğrulama

“Kanca girdisini ayrıştırarak dosya içeriğini alın ve ilk 10 satırın dize eşleştirmeyle lisans metni içerip içermediğini kontrol edin. Daha gelişmiş doğrulama için dosya başlığını, uygun telif hakkı bildirimleri ve lisans bilgileri içerdiğini doğrulaması için Anthropic API üzerinden Claude’a gönderin. Başlıklar eksikse 2 koduyla dosya oluşturmayı engelleyin ve Claude’a eklenecek doğru lisans şablonunu sağlayın.”

Üretim dosyası koruyucu

• Sorun: Kritik sistem yapılandırma dosyalarının yanlışlıkla değiştirilmesi

• Tetikleyiciler: Hassas dizinlerdeki dosyaları düzenlemeden önce

• Çözüm: /etc/, nginx.conf, database.yml ve diğer kritik yapılandırmalara yapılan değişiklikleri engelleme

“Kanca girdi JSON’undan dosya yolunu çıkarın ve /etc/, production.yml veya diğer kritik dosya adları gibi kalıplarla eşleşip eşleşmediğini kontrol edin. Dosya yolunun üretim sistemlerini etkileyebilecek bir yapılandırma dosyası olup olmadığını belirlemek için Claude’un API’sini kullanın. Tehlikeli yollar tespit edildiğinde 2 koduyla çıkın ve daha güvenli geliştirme uygulamaları hakkında özel yönlendirme sağlayın.”

Görüntü iyileştirici

• Sorun: Büyük görüntü dosyalarının uygulamaları ve depoları yavaşlatması

• Tetikleyiciler: Yeni görüntü dosyaları eklendikten sonra

• Çözüm: PNG/JPEG dosyalarını görsel kaliteyi koruyarak sıkıştırma

“Kanca girdisini ayrıştırarak dosya yolunu alın ve uzantı eşleştirme ile bunun bir görüntü dosyası olup olmadığını kontrol edin. imageoptim gibi sıkıştırma araçlarını çalıştırın veya kaliteyi korurken resmi sıkıştırmak için TinyPNG API’sini çağırın. Sıkıştırma sonuçlarını stdout’a kaydederek dosya boyutu tasarruflarını Claude’un dökümünde görün.”

Sürüm kontrol otomasyonu için ileri düzey kancalar

Git iş akışları ve dokümantasyon, kancaların ayrıca çok faydalı olduğu alanlardır. Bazı fikirlere bakalım.

Git dalı doğrulayıcı

• Sorun: Ekip üyelerinin yanlışlıkla korunan dallara değişiklik göndermesi

• Tetikleyiciler: Herhangi bir dosya yazma veya düzenleme işleminden önce

• Çözüm: Geçerli Git dalını kontrol edip main/master/production üzerinde işlemleri engelleme

“Geçerli dal adını almak için basit bir bash komutu git branch --show-current kullanın ve bunu korunan dallar listesiyle karşılaştırın. Korumalı bir daldaysanız, 2 koduyla çıkın ve dal koruma ilkelerini açıklayan bir hata iletisini Claude’a gönderin. Karmaşık dal adlandırma kuralları için dal adlarını analiz etmek ve koruma kalıplarıyla eşleşip eşleşmediklerini belirlemek üzere Claude’un API’sini kullanın.”

Akıllı otomatik commit

• Sorun: Değişiklikleri commit etmeyi unutmak veya zayıf commit iletileri yazmak

• Tetikleyiciler: Herhangi bir dosya değişikliğinden sonra

• Çözüm: AI ile üretilmiş açıklayıcı iletilerle değişiklikleri otomatik olarak aşamalandırma ve commit etme

“Kanca girdisinden değiştirilen dosya yollarını okuyun, değişiklikleri almak için git diff çalıştırın ve özlü bir commit iletisi istemiyle diff’i Claude’un API’sine gönderin. Üretilen iletiyi, değişiklikleri otomatik olarak commit etmek için git add ve git commit komutlarıyla kullanın. Commit iletilerinin geleneksel commit standartlarını takip etmesini sağlamak için API istemine dosya adlarını ve değişiklik türlerini dahil edin.”

Dokümantasyon oluşturucu

• Sorun: API dokümantasyonunun kod değişiklikleriyle senkron dışı kalması

• Tetikleyiciler: Arayüz dosyaları (denetleyiciler, modeller, API’ler) değiştirildikten sonra

• Çözüm: JSDoc, Sphinx veya OpenAPI oluşturucuları gibi dokümantasyon araçlarını otomatik çalıştırma

“Desen eşleştirme kullanarak değiştirilen dosya yolunun bir API uç noktası, model veya arayüz dosyası olup olmadığını belirleyin. Dosya içeriğini Claude’un API’sine göndererek API değişikliklerini çıkarmasını ve dokümantasyon güncellemeleri üretmesini isteyin. Uygun dokümantasyon oluşturma aracını (jsdoc, sphinx-build vb.) çalıştırın ve güncellenen dokümantasyonu otomatik olarak commit edin.

İşbirliği ve iş akışı entegrasyonu için ileri düzey kancalar

Son olarak, kancalar ekibinizin tüm üyelerinin güncel kalmasına yardımcı olabilir.

Slack entegrasyonu

• Sorun: Ekibin paylaşılan kod tabanlarındaki önemli değişikliklerden habersiz olması

• Tetikleyiciler: Önemli işlemler için bildirimler gönderildiğinde

• Çözüm: Dosya adları ve değişiklik özetleriyle biçimlendirilmiş iletileri ekip kanallarına gönderme

“Kanca girdisinden dosya bilgilerini çıkarın ve kaynak kodu veya yapılandırma dosyaları gibi önemli dosya türlerine göre filtreleyin. Dosya adları ve türlerine dayanarak nelerin değiştiğine dair insan tarafından okunabilir bir özet oluşturması için Claude’un API’sini kullanın. Kritik değişiklikler için ekip üyelerini etiketleyerek biçimlendirilmiş iletiyi webhook URL’leri aracılığıyla Slack’e gönderin.”

Webhook dağıtıcısı

• Sorun: Manuel CI/CD tetiklemeleri nedeniyle dağıtım gecikmeleri

• Tetikleyiciler: Belirli olaylar meydana geldiğinde (yapılandırma değişiklikleri, dağıtım dosyaları değiştirildiğinde)

• Çözüm: Derlemeleri, dağıtımları veya diğer otomatik süreçleri tetiklemek için harici API’leri çağırma

“CI/CD’nin tetiklenip tetiklenmeyeceğini belirlemek için değiştirilen dosya yolunu Dockerfile, package.json veya dağıtım yapılandırmaları gibi kalıplarla karşılaştırın. Kimlik doğrulama başlıkları ve değişikliklerle ilgili yük verileri ile webhook URL’lerini çağırmak için Python’da requests kitaplığını kullanın. Dış sistemlerin neyin derleneceği veya dağıtılacağına akıllıca karar verebilmesi için webhook yüküne dosya yollarını ve değişiklik meta verilerini dahil edin.”

Durum sayfası güncelleyici

• Sorun: Müşterilerin bakım veya dağıtım faaliyetlerinden habersiz olması

• Tetikleyiciler: Dağıtım veya altyapı dosyaları değiştirildiğinde

• Çözüm: Hizmet durum sayfalarını bakım bildirimleriyle günceller

“Kubernetes manifestoları veya Terraform yapılandırmaları gibi altyapı dosya değişiklikleri için dosya yolu kalıplarını kullanarak kanca girdisini ayrıştırın. Tespit edilen altyapı değişikliklerinin türüne göre Claude’un API’sini kullanarak bakım iletileri oluşturun. Uygun olay türleri ve tahmini süre ile StatusPage.io veya PagerDuty gibi hizmetlere REST API’leri üzerinden durum güncellemeleri gönderin.”

Ekip durum bildirici

• Sorun: Birden fazla geliştiricinin aynı özellikler üzerinde farkında olmadan çalışması nedeniyle çatışmalar

• Tetikleyiciler: Yeni bir Claude Code oturumuna başlarken

• Çözüm: Belirli bir proje veya bileşen üzerinde çalışmaya başladığınızı ekip kanallarına bildirme

“Kanca girdisinden proje dizinini okuyun ve ne tür bir çalışma yapıldığını anlamak için yakın tarihli dosyaları veya git geçmişini analiz etmek üzere Claude’un API’sini kullanın. Adınız, proje adı ve odak alanı ile ekip iletişim kanallarına biçimlendirilmiş bir ileti gönderin. Tahmini çalışma süresini ekleyin ve ilgili özellikler üzerinde çalışan ekip üyelerini koordinasyona davet edin.”

Son Düşünceler

Claude Code Kancaları, öngörülemeyen yapay zekâlı kodlama asistanlarını, tam da ihtiyaç duyduğunuz anda çalışan otomatik iş akışlarına dönüştürür. Bu eğitimde, hem etkileşimli /hooks komutunu hem de manuel yapılandırmayı kullanarak kancaları kurmayı, akıllı otomasyonu besleyen JSON girdi verisini anlamayı ve çıkış kodları ve yapılandırılmış çıktılarla Claude’un davranışını kontrol etmeyi öğrendiniz. 

Ele aldığımız pratik kalıplar arasında tehlikeli işlemleri engelleyen güvenlik doğrulayıcıları ve gürültüyü azaltan akıllı bildirimler yer alıyor. Bu örnekler, kancaların gerçek geliştirme sorunlarını nasıl çözdüğünü ve yapay zekâ asistanınız üzerinde tam kontrol sağladığını gösteriyor. Artık temelleri anladığınıza göre, ekibinizin özel iş akışı ihtiyaçlarına uyan otomasyonlar inşa edebilirsiniz. 

Yapay zekâ araçlarıyla çalışmayı daha fazla öğrenmek için DataCamp’in Prompt Engineering’i Anlama kursuna göz atın; bu kurs, kanca geliştirmeyle doğrudan çalışan istem stratejilerini kapsar. Daha geniş yapay zekâ ile kodlama becerileri için Orta Düzey ChatGPT kursumuzu deneyin; bu kurs, yapay zekâ asistanlarını geliştirme iş akışınızda daha güvenilir ortaklar hâline getiren becerileri geliştirmenize yardımcı olur.