0. KISA VE ÖZ
Bu makale, Claude Code'u altı ay boyunca yoğun şekilde kullanmaktan ve iki hesaba aylık 40 dolar harcayarak edindiğim derslerden oluşuyor. Herkese değerli bilgiler sunmayı umuyorum.
Başlangıçta bir ChatBot olarak kullandım, ancak kısa sürede işlerin ters gittiğini fark ettim: bağlam karmaşıklaştı, araçlar arttı ama etkinlik azaldı, kurallar uzun olmasına rağmen dikkate alınmadı. Claude Code'un kendisini araştırdıktan sonra, bunun bir Prompt sorunu değil, sistem tasarımı sorunu olduğunu anladım.
Şunları tartışmak istiyorum: Claude Code'un perde arkasında nasıl çalıştığı, bağlamın neden karmaşıklaştığı ve nasıl yönetileceği, Skills ve Hooks'un nasıl tasarlanacağı, Subagent'ların doğru kullanımı, Prompt Caching'in mimari etkisi ve gerçekten kullanışlı bir CLAUDE.md'nin nasıl yazılacağı.
Bunu anlamanın en doğrudan yolu, Claude Code'u altı katmana ayırmaktır:
Sadece bir katmanı güçlendirmek dengesizliğe yol açar. CLAUDE.md çok uzunsa bağlamı kirletir; çok fazla araç kafa karışıklığına neden olur; çok fazla subagent durum kaymasına yol açar; doğrulamanın atlanması, hatanın nerede olduğunu bulmayı imkansız hale getirir.
1. Perde Arkasında Nasıl Çalışır
Claude Code'un özü "cevap vermek" değil, tekrarlayan bir ajan döngüsüdür:
1Bağlam Topla → Harekete Geç → Sonucu Doğrula → [Tamamla veya Döngüye Devam Et]2 ↑ ↓3 CLAUDE.md Hooks / İzinler / Sandbox4 Skills Tools / MCP5 Bellek
Darboğazların nadiren modelin yeterince zeki olmamasından kaynaklandığını, bunun yerine ona yanlış bağlam vermekten veya çıktının doğru olup olmadığını değerlendirecek ya da geri alacak bir yöntemin olmamasından kaynaklandığını fark ettim.
Odaklanılması Gereken Beş Katman:
Bu katmanlara bakmak sorun gidermeyi kolaylaştırır. Sonuçlar kararsız mı? Bağlam yükleme sırasını kontrol edin. Otomasyon kontrolden çıktı mı? Kontrol katmanını kontrol edin. Uzun oturumlarda kalite düşüyor mu? Ara ürünler bağlamı kirletti; yeni bir oturum başlatmak, prompt'ları ince ayar yapmaktan daha iyidir.
2. Kavramsal Sınırlar: MCP / Plugin / Tools / Skills / Hooks / Subagents
Basit kural: Yeni eylemler için Tools/MCP kullanın, iş akışları için Skills, izole ortamlar için Subagents, zorunlu kısıtlamalar/denetim için Hooks ve projeler arası dağıtım için Plugins kullanın.
3. Bağlam Mühendisliği: En Önemli Sistem Kısıtlaması
Birçok kişi bağlamı bir "kapasite sorunu" olarak görür, ancak darboğaz genellikle gürültüdür. Yararlı bilgiler alakasız içerikte kaybolur.
Gerçek Bağlam Maliyeti Bileşimi
Claude Code'un 200K bağlamı tamamen kullanılabilir değildir:
1200K Toplam Bağlam2├── Sabit Ek Yük (~15-20K)3│ ├── Sistem talimatları: ~2K4│ ├── Skill tanımlayıcıları: ~1-5K5│ ├── MCP Sunucu araç tanımları: ~10-20K ← En büyük gizli katil6│ └── LSP durumu: ~2-5K7│8├── Yarı-Sabit (~5-10K)9│ ├── CLAUDE.md: ~2-5K10│ └── Bellek: ~1-2K11│12└── Dinamik Kullanılabilir (~160-180K)13 ├── Sohbet geçmişi14 ├── Dosya içeriği15 └── Araç sonuçları
Tipik bir MCP Sunucusu (GitHub gibi) her biri ~200 token olan 20-30 araç tanımı içerir ve toplamda 4,000-6,000 token eder. 5 sunucuyu bağlamak 25,000 token (%12.5) tüketir. Bu, büyük miktarda kod okurken kritik öneme sahiptir.
Önerilen Bağlam Katmanlaması
1Her Zaman Yerleşik → CLAUDE.md: Proje sözleşmesi / derleme komutları / yasaklar2Yol Tabanlı → rules: Dil / dizin / dosya türüne özel kurallar3Talep Üzerine → Skills: İş akışları / alan bilgisi4İzole → Subagents: Büyük ölçekli keşif / paralel araştırma5Bağlam Dışı → Hooks: Belirleyici betikler / denetim / engelleme
Sadece ara sıra kullandığınız şeyleri yüklemeyin.
Bağlam En İyi Uygulamaları
- CLAUDE.md'yi kısa, net ve uygulanabilir tutun. Anthropic'in kendisininki ~2.5K token'dır.
- Büyük referans belgelerini Skills'in destek dosyalarına taşıyın.
- Yol/dil kuralları için .claude/rules/ kullanın.
- Tüketimi izlemek için /context kullanın.
- Görev değiştirmek için /clear ve yeni aşamalar için /compact kullanın.
- Neyin korunacağını kontrol etmek için CLAUDE.md'ye Compact Talimatları yazın.
Araç Çıktı Gürültüsü: Başka Bir Gizli Katil
Dinamik araç çıktısı (cargo test veya git log gibi) bağlamı kolayca doldurabilir. Claude'un her şeyi görmesi gerekmez.
RTK (Rust Token Killer) iyi bir yaklaşımdır: Claude'a ulaşmadan önce komut çıktısını filtreler. Örneğin, binlerce satırlık test çıktısını tek bir başarı mesajına sıkıştırabilir.
Sıkıştırma Tuzakları
Varsayılan sıkıştırma, mimari kararları ve kısıtlamaları silebilir.
Çözüm: Mimarî kararlara, değiştirilen dosyalara, doğrulama durumuna ve YAPILACAKLAR'a (TODO) öncelik vermek için CLAUDE.md'de Compact Talimatları belirtin.
Bir başka proaktif çözüm: Yeni bir oturuma başlamadan önce Claude'a ilerlemeyi ve çıkmaz sokakları açıklayan bir HANDOFF.md yazdırın.
Plan Modunun Mühendislik Değeri
Plan Modu, keşfi yürütmeden ayırır.
Karmaşık yeniden düzenlemeler için bu, aceleyle kod yazmaktan daha iyidir. İleri düzey ipucu: Planı yazması için bir Claude ve onu incelemesi için bir "Kıdemli Mühendis" olarak başka bir Claude kullanın.
4. Skills Tasarımı: Talep Üzerine Yüklenen İş Akışları
Skills, talep üzerine bilgi ve iş akışlarıdır.
İyi bir Skill'i ne oluşturur
- Açıklama "ne yaptığımı" değil, "beni ne zaman kullanacağını" söylemelidir.
- Tam adımlara, girdilere, çıktılara ve durma koşullarına sahip olun.
- Ana gövdeyi gezinme ve temel kısıtlamalar için saklayın; ayrıntıları destek dosyalarına taşıyın.
- Yan etkileri olan skill'ler için disable-model-invocation: true olarak ayarlayın.
Aşamalı Açıklama
Claude Code "aşamalı açıklamayı" vurgular: önce dizinler ve gezinme sağlayın, ardından gerektiğinde ayrıntıları çekin.
Üç Tipik Skill Türü
- Kontrol Listesi (Kalite Geçidi): örn., sürüm-kontrolü.
- İş Akışı (Standartlaştırılmış Operasyonlar): örn., geri almalı yapılandırma-geçişi.
- Alan Uzmanı (Karar Çerçevesi): örn., çalışma-zamanı-teşhisi.
Bağlam alanından tasarruf etmek için tanımlayıcıları kısa tutun.
5. Araç Tasarımı: Claude'un Doğru Seçim Yapmasına Yardımcı Olmak
Ajanlara yönelik araçlar, özellik eksiksizliğinden ziyade doğru kullanım kolaylığına odaklanmalıdır.
İyiye Karşı Kötü Araçlar
Tasarım ilkeleri: Ön ekler kullanın (github_pr_*), kısa biçimleri destekleyin, yararlı hata mesajları sağlayın ve çok fazla parçalanmış araç sunmaktan kaçının.
Dahili Araçların Evrimi
"AskUserQuestion" aracının evrimi, özel bir aracın işaretleme biçimlendirmesinden veya çıkış parametrelerinden daha kararlı olduğunu göstermektedir.
Modeller güçlendikçe Todo araçları bir "pranga" haline geldi. Arama araçları, daha iyi esneklik ve "aşamalı açıklama" için RAG'den Grep'e evrildi.
6. Hooks: İşlem Öncesi/Sonrası Zorunlu Mantık
Hooks, biçimlendirme, dosya koruma ve bildirimler gibi süreçler üzerinde belirleyici kontrolü yeniden kazanır.
Hook'lar İçin Uygun Olanlar
Korumalı dosyaları engelleme, düzenleme sonrası otomatik biçimlendirme, dinamik bağlam (Git dalı) ekleme ve bildirimler.
Erken Hata Tespiti
7. Subagents: Bağımsız Claude Örnekleri
Subagents izolasyon sağlar. Depoları tarama veya testleri çalıştırma gibi görevler, ana iş parçacığını karıştırmaması gereken büyük miktarda çıktı üretir.
Açık Kısıtlamalar
Araçları sınırlayın, doğru modeli seçin (keşif için Haiku, inceleme için Opus) ve maxTurns'ü ayarlayın.
8. Prompt Caching: Claude Code Mimarisi'nin Özü
Claude Code, Prompt Caching etrafında inşa edilmiştir. Yüksek isabet oranları paradan tasarruf sağlar ve hız sınırlarını artırır.
Önbelleğe Alma İçin Prompt Düzeni
Ön ek eşleştirme için sıra önemlidir: Sistem Prompt → Araç Tanımları → Sohbet Geçmişi → Kullanıcı Girdisi.
Oturum Ortasında Model Değiştirmeyin
Model değiştirmek önbelleği bozar. Bunun yerine devir teslim için Subagents kullanın.
Sıkıştırma Uygulaması
Sıkıştırma, önbellek isabetleri nedeniyle maliyetin 1/10'u kadar bir maliyetle geçmişi özetlemek için bir fork kullanır.
9. Doğrulama Döngüleri: Doğrulayıcı Yoksa, Mühendislik Ajanı da Yok
"Doğrulama olmadan "Claude bitti dedi" işe yaramaz. Doğrulamayı Prompt, Skill ve CLAUDE.md'de açıkça tanımlayın.
10. Sık Kullanılan Komutlar
/context, /clear, /compact ve /memory gibi komutlar bağlamı aktif olarak yönetmeye yardımcı olur.
Yönetişim ve Paralellik
Kullanışlı gizli komutlar: /simplify (kod incelemesi), /rewind (kontrol noktası oluşturma), /btw (yan sorular), /insight (CLAUDE.md güncellemeleri için oturumu analiz etme).
11. İyi Bir CLAUDE.md Nasıl Yazılır
Bu bir sözleşmedir, bir bilgi tabanı değil.
Derleme/test komutlarını, mimari sınırları, kodlama kurallarını, güvenlik önlemlerini ve Compact Talimatlarını ekleyin. Claude'dan hatalarını düzelttikten sonra CLAUDE.md'yi güncellemesini isteyin.
12. Son Deneyimler
Kaku'yu (Rust + Lua) oluştururken çıkarılan dersler: ortam şeffaflığı hayati önem taşır (bir 'doktor' komutu kullanın) ve Hooks çok dilli projeler için harikadır.
13. Anti-kalıplar
14. Sağlık Kontrolü
Yapılandırmanızı kontrol etmek için npx skills add tw93/claude-health komutunu kullanın.
15. Sonuç
Odak noktası "özelliklerin nasıl kullanılacağından", "ajanın kısıtlamalar altında nasıl çalıştırılacağına" kayar. "Bitti"yi tanımlayamıyorsanız, görev bir ajana hazır değildir.
