Claude Code Prompt'larını Tekrar Yazma: 4 İş, 4 Dosya

Claude Code uzantıları, aynı prompt'u tekrar tekrar yazmaman için bir reponun tutabileceği dosyalardır: bir skill, bir hook, bir subagent ve bir MCP sunucusu. Gerçek bir repoda, veritabanı olarak bir JSON dosyası kullanan küçük bir fatura API'sinde, tekrar eden dört işi çalıştırdık. Her işe önce yanlış uzantıyı verdik ve yanlış seçim her seferinde ekranda başarısız oldu. Sonra her iş commit edilmiş bir dosya oldu. Bu sayfa dört hareketi ve hangi türün kullanılacağına karar veren seçim kartını anlatıyor.

İki sonuç aşağıdaki her şeyin çerçevesini çiziyor. Hook çoğu zaman bir garanti, bellek dosyasındaki kural ise bir rica olarak anlatılır; ama ilk hook'umuz çalıştı, uyarısını yazdı ve yazma işlemi yine de geçti. Çalışan bir hook'u engelleyen bir hook'a çevirenin ne olduğu hook bölümünde anlatılıyor. Bağladığımız ilk docs sunucusu hiçbir şeyi değiştirmedi, cevap veren aracın kendi docs sunucusu oldu. Çoğu insanın kopyaladığı hook tarifi ayrıca bir script dosyası da istiyor, ama bizimki tamamen ayar dosyasına sığıyor.

Dört dosyadan herhangi birini yazmadan önce, oturumunun zaten ne yüklediğini bilmen gerekiyor.

Bir Claude Code uzantısı, aynı talimatları prompt kutusuna tekrar tekrar yazmaman için repoya eklediğin bir dosyadır. Dört tür var; zaten bilenler bir sonraki bölüme geçebilir.

• Skill, reponda dosyalanmış bir çalışma kılavuzudur. Claude adımlarını yalnızca o iş gündeme geldiğinde yükler ve adını yazarak sen başlatabilirsin.
• Hook, git'teki commit hook'una benzer, ama Claude'un kendi eylemleri için. Bir olayda, örneğin bir düzenlemede, Claude ne amaçlamış olursa olsun çalışan bir script'tir.
• Subagent, boş bir masaya oturan bir yükleniciye benzer. Senin brief'ini alır, okumayı kendisi yapar ve yığını değil bir rapor gönderir.
• MCP sunucusu, Claude'un çağırabildiği bir API istemcisidir; diskinde olmayan veriler için, örneğin bir veritabanı ya da bir aracın docs'u.

Bir şeyi ölçmek için önce bir başlangıç değeri gerekir. Yeni bir oturum aç ve context komutunu çalıştır. İlk kelimenden önce yüklenen her şeyin tablosunu yazdırır. Bizim ölçüm ortamında toplam, 1m'lik bir pencerede 26.2k token'dı; hiç memory files satırı ve hiç MCP satırı yoktu. Bundan sonra Claude'a verdiğin her iş ya bu tabloya bir satır ekler ya da ona dokunmaz.

Skill, kendi klasöründe duran ve Claude'un yalnızca sen çağırdığında okuduğu bir kontrol listesidir. İlk iş, prompt kutusuna sürekli yapıştırdığın bir release kontrol listesi: tip kontrolü, testler, sürüm artırma, changelog satırı ekleme, commit ve tag.

Bunun için akla gelen yer bellek dosyasıdır ve bu yanlış seçimdir, çünkü o dosyadaki her şey her oturumun her turunda yüklenir. Adımları oraya koyduk ve context tablosunu yeniden okuduk. Tabloda 210 token'lık bir Memory files satırı belirmişti; release yapıp yapmadığına bakmadan yükleniyor. Docs da aynısını söylüyor: o dosyanın bir bölümü bir prosedüre dönüştüyse yeri bir skill'dir.

Doğru seçim, skills dizini altında adımların .claude/skills/release/SKILL.md içinde durduğu bir klasör, en üstte kısa bir açıklama ve frontmatter'da fazladan bir satır: disable-model-invocation: true. Bu satır skill'i Claude'un kendi listesinin dışında tutar; yani yalnızca sen başlatabilirsin, commit ve tag atan bir iş için istenen de budur. Sonra bir slash ve adını yazarsın, kontrol listesi çalışır.

Context okuması	Toplam	Memory files satırı
Başlangıç, yeni oturum	26.2k / 1m	yok
Kontrol listesi bellek dosyasında	26.4k / 1m	210 token
Kontrol listesi skill olarak	26.2k / 1m	yok, skill listede değil

Çalıştırdığımızda Claude altı adımın hepsini bir dakikadan kısa sürede tamamladı: tip kontrolü, 34 test, sürümü 0.4.0'dan 0.4.1'e çıkarma, changelog satırı, commit ve tag. Kendi kontrol listemizdeki bir kusuru da yakaladı. Yazdığımız haliyle commit komutu izlenmeyen dosyaları atlıyor, bu yüzden Claude önce yeni changelog'u stage etti ve bunu söyledi. Release artık yazdığın bir komut, tüm ekip için repoda duruyor ve sen yazana kadar context'e hiçbir maliyeti yok.

Hook, Claude Code'un bir araç çalışmadan önce, burada herhangi bir düzenleme ya da yazmadan önce, çalıştırdığı bir script'tir ve script'in verdiği cevap sonraki adımı belirler. İkinci iş asla bozulmaması gereken bir kural: bu repoda saklanan veri dosyası elle asla düzenlenmez, her değişiklik bir migration'dan geçer.

Bu kuralı bellek dosyasına büyük harflerle yazmak onu zorunlu kılmaz. Docs açık konuşuyor: o dosya bağlamdır, zorunlu yapılandırma değil, ve "never edit this file" gibi bir talimat bir ricadır, garanti değil; düzenlemeyi engelleyen bir hook ise zorunluluktur.

İlk akla gelen hook, bizim yazdığımız hook. Ayar dosyasında veri dosyasına yazmaları izliyor, bir uyarı yazdırıyor ve bir loglama script'i gibi sıfır koduyla çıkıyor. Sonra Claude'dan bir fatura tutarını migration olmadan doğrudan dosyada değiştirmesini istedik. Hook çalıştı ve uyarı yazıldı, ama yazma işlemi geçti: üçüncü faturadaki birim fiyat 8000'den 12000'e çıktı. Claude'un cevabı hook'tan hiç söz etmedi, çünkü temiz çıkan ve hiçbir şey yazdırmayan bir hook karar vermemiştir ve uyarıları Claude'a hiç ulaşmaz.

Garanti, hook'un çalışması değil, verdiği cevaptır. Düzeltme aynı hook'u tutuyor ve ona bir deny kararı döndürtüyor: Claude'un okumasını istediğin gerekçeyi taşıyan kısa bir JSON satırı. İki çıkış koduyla çıkmak da aynı şekilde engeller. Hook'un tamamı .claude/settings.json içinde tek bir satır içi komut, script dosyası yok:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c 'if (.tool_input.file_path // \"\") | test(\"data/.*\\\\.json$\") then {hookSpecificOutput: {hookEventName: \"PreToolUse\", permissionDecision: \"deny\", permissionDecisionReason: \"Stored data is never edited by hand: write a migration in src/store/migrations.ts (README § Conventions).\"}} else empty end'"
          }
        ]
      }
    ]
  }
}

Aynı istekle düzenleme reddedildi ve veri dosyası dokunulmadan kaldı. Claude şu hatayı gördü: PreToolUse:Edit hook error: Stored data is never edited by hand: write a migration in src/store/migrations.ts (README § Conventions). Hiçbir şeyi değiştirmediğini söyledi ve korumayı aşmak mı yoksa migration yazmak mı istediğimizi sordu.

Claude'un kendisinin söylediği sınır: bu hook yalnızca düzenleme ve yazma araçlarını izliyor ve sonraki bir çalıştırmada Claude değişikliği shell üzerinden yapmayı önerdi. Hook shell'i de kapsamalı, ya da shell izin listende durmamalı, çünkü yalnızca tek bir kapıyı kapsayan bir koruma hâlâ bir ricadır. Hook, konuşmanın dışında çalıştığı için context'e hiçbir şeye mal olmaz.

Subagent, kendi boş context'ine sahip ayrı bir Claude oturumudur. Brief'ini alır, ihtiyacı olanı okur ve sana yalnızca bir özet döner. Üçüncü iş, konuşmanı taşıran bir denetim: kaynak klasöründeki her dosyayı README kurallarına göre kontrol et ve her ihlali dosya ve satırla listele.

Doğrudan sorulduğunda Claude her dosyayı konuşmana okur ve bu içeriğin hepsi oturumun geri kalanında orada kalır. Bizim çalıştırmamızda Claude 19 kaynak dosyasının hepsini okudu, context tablosundaki Messages satırı şişti ve bulgular yığının altında kayboldu.

Doğru seçim .claude/agents/ altında bir dosya, burada .claude/agents/conventions-auditor.md; bir ad, ne zaman kullanılacağına dair bir açıklama, kullanabileceği araçlar ve sabitlenmiş bir model içeriyor. Modeli sabitlemek önemli, çünkü aksi halde subagent oturumunun çalıştığı modeli devralır ve çoğu okuma işi büyük modele ihtiyaç duymaz.

Aynı soruyu tekrar sorduk ve Claude dosyaları yine kendisi okudu. Her iki denemede de listede olmasına rağmen agent'ı hiç çağırmadı: 2 delegasyonun 0'ı. İşe yarayan, prompt'un başında adını yazmaktı: "use the conventions auditor subagent". Tek bir çağrı gitti ve kısa bir özet döndü.

Çalıştırma	Toplam context	Messages satırı
Doğrudan denetim	46.1k	19.3k
Adı verilen subagent	34.1k	7.2k

Bulgular da aynı kalitedeydi: subagent, doğrudan çalıştırmanın kaçırdığı bir yol hatasını yakaladı ve doğrudan çalıştırmanın bulduğu birini kaçırdı. Yani dosya subagent'ı var eder, prompt'un Claude'a onu kullandırır; Claude onu kendiliğinden seçene kadar adını sen yazarsın. Bir sınır: fatura değişmedi. İki çalıştırma da aynı maliyetteydi, çünkü okuma yine de gerçekleşiyor, sadece senin pencerende değil.

MCP sunucusu, Claude'un çağırabildiği bir API istemcisidir ve var olma sebebi, modelden daha yeni verilerdir ya da diskinin dışında duran veriler. Buradaki refleks seçim yanlış, bu yüzden onu ilk biz yaptık.

Test kütüphanemiz için herkese açık bir docs sunucusu bağladık ve Claude'dan sahte zamanlayıcılarla bir test yazmasını istedik. Hiçbir şey değişmedi: Claude o kütüphaneyi zaten biliyordu ve sunucuyu yalnızca biz adını verince çağırdı. Modelin zaten bildiği docs, ulaşamayacağı veri değildir.

Gerçek test, Claude Code'un kendisi hakkında, modelden daha yeni bir hook ayarı hakkında bir soru: başarısız bir hook'u hangi ayar engelletir, hangi sürüm ekledi ve tam JSON nedir. Sunucu olmadan Claude, kendi kurulumunun ayar şemasını okudu, hiçbir şey bulamadı ve o ayarı bulamadığını, tahmin etmeyeceğini söyledi. Bu cevap dürüst ve işe yaramaz, çünkü ayar var; modelin bilgisinden sonra geldi.

Çözüm, Claude Code'un kendi docs sunucusunu repoya eklemek, project kapsamıyla; böylece yapılandırma reponun kökünde, tüm ekibinin alacağı bir dosyaya düşer:

claude mcp add --transport http claude-docs --scope project https://code.claude.com/docs/mcp

Bu komut .mcp.json yazar. Claude Code sunucuyu, bir sonraki oturumunda onaylayana kadar beklemede olarak listeler ve ondan sonra araçları Claude'un kullanımına açılır. Aynı soruyu sade kelimelerle, sunucunun adını vermeden sorduk. Claude docs'ta arama yaptı, sayfayı buldu ve ayarı, sürümü ve eklenecek JSON'u bağlantıyla birlikte cevapladı.

Ayar "onFailure": "block"; başarısız bir hook'un eylemi geçirmek yerine engellemesini sağlıyor. v2.1.295'te geldi, bizim kurulumumuz ise hâlâ 2.1.294'tü. Sınır da bu: Claude kurulumumuzun bunu kullanamayacağını hiç söylemedi, çünkü sürümü kontrol etmedi; sürümünü kendin kontrol edersin. Context tablosunda sunucu yalnızca araç adlarıyla görünür, Claude bunlardan birine uzanana kadar talep üzerine yüklenir.

Dört işten sonra git status tam olarak dört dosya gösteriyor, çünkü hook'un kendi script'ine ihtiyacı yok:

• .claude/skills/release/SKILL.md
• .claude/settings.json
• .claude/agents/conventions-auditor.md
• .mcp.json

Bunları commit et; bu repoda açılan bir sonraki oturum hepsine sahip olur, repoyu klonlayan herkes de.

Her seçimin neden doğru olduğunu gösteren, docs'un sunduğu bir tablo var ve onu bir karar kartı olarak saklayabilirsin:

Durum	Uzantı
Yine yapıştırdığın bir prosedür	Skill
Sormadan, her seferinde olması gereken bir şey	Hook
Bir daha okumayacağın çıktıyla konuşmanı dolduran yan bir iş	Subagent
Claude'un göremediği bir yerden sürekli kopyaladığın veri	MCP sunucusu

Türler birleştirilebilir de. Docs bir skill'i bir MCP sunucusuyla eşleştiriyor: sunucu bağlantıyı sağlar, skill Claude'a onu iyi kullanmayı öğretir. Bir skill ayrıca çatallanmış bir subagent'ın içinde de çalışabilir, böylece okuması senin pencerenin dışında kalır. Başka bir repo aynı kurulumu gerektirdiğinde plugin, hepsini birlikte taşıyan kutudur.

Kart türü belirler, kaliteyi değil. Yalnızca loglayan bir hook, adını hiç yazmadığın bir subagent ve modelin zaten bildiği docs için bir sunucu, her biri doğru türdeydi ve yine de başarısız oldu. Türü karttan seç, sonra dosyanın sadece var olmasını değil cevap vermesini sağla.

Eskiden tekrar tekrar yazdığın dört işin hepsi önce yanlış yoldan denendi, ekranda başarısız oldu ve şimdi repoda çalışan dosyalar. Release, yazdığın bir komut. Veri kuralı, düzenlemeyi reddeden ve Claude'a sordurtan bir hook. Denetim bir özet olarak geliyor. Docs sorusu, Claude'un tek başına bulamadığı ayarı ve sürümü alıyor.

Açılışta kullandığımız hook, çalışan ama yazmayı geçiren hook, her şeyin altındaki kuralı öğretti: bir hook yalnızca komutunun döndürdüğüyle karar verir, yani yalnızca loglayan bir hook kostüm giymiş bir ricadır.

Bazı durumlar bunların hiçbirini gerektirmez:

• Claude'un sürekli yanlış yaptığı bir kural yine bellek dosyasında durur, bir prosedür olarak değil, bir satır olarak.
• İleri geri yönlendirmen gereken, geçmişinin görünür olduğu bir iş ana thread'de kalır, subagent'ta değil.
• Modelin zaten bildiği bir kütüphane için docs sunucusu context'e mal olur ve hiçbir şeyi değiştirmez. Modelin sahip olamayacağı şeyi bağla, zaten sahip olduğunu değil.

Hatırlanacak kural: tekrar yazdığın her işe kendi dosyasını ver, türü karttan seç ve aralarında yalnızca hook'un asla sormadığını bil.