CLAUDE.md 300 satırdan fazla yazılmış, takımın kodlama standartları, isimlendirme kuralları, deployment süreçlerinin hepsi içine tıkıştırılmış, sonuçta Claude Code çalışırken unutması gerekeni unutuyor. Biraz karmaşık bir görev verince kendi kendine çelişmeye bile başlıyor.
Ben de eskiden böyle yapıyordum. Ta ki bir gün Anthropic’in resmi dokümantasyonunda bir cümle görene kadar, özeti şu: “CLAUDE.md sadece 7 özelleştirme yönteminden biridir, tek yol değildir.”
7 yöntem mi? Kendi kullandıklarımı saydım, sadece CLAUDE.md ve .claude/commands/ olmak üzere 2 tane. Geri kalan 5’ini duymamıştım bile.
Sonra bir hafta boyunca bu 7 yöntemi tek tek inceledim ve acı bir gerçekle karşılaştım: Çoğu insan tüm kuralları bir çırpıda CLAUDE.md’ye tıkıştırıyor, tıpkı tüm kıyafetleri tek bir çekmeceye atmak gibi—görünüşte hepsi orada, ama aradığın zaman her şey birbirine karışıyor.
Bu yazı tekrar “7 yöntemi tek tek tanıtayım” tarzı düz bir yapı değil—o tür yazılar zaten yeterince var. Benim yapmak istediğim şu: Önce sana 5 gerçek senaryo vereceğim, kendini bul; sonra bir karar çerçevesi vereceğim, ileride kendin karar verebilesin; en sonda her yöntemin prensibini, kullanımını ve anti-pattern’lerini tek tek parçalayacağım.
Açıkçası, “ne zaman kullanmamalısın” bilgisi “nasıl kullanırsın” bilgisinden daha önemli.
İçindekiler
- Önce 5 senaryoya bak: Kaçını yaşadın?
- Bir tablo: 7 yönteme hızlı bakış
- Karar çerçevesi: Hangisini kullanmalısın?
- Tek tek parçalama: Her yöntemin prensibi + kullanımı + anti-pattern’i
- 1. CLAUDE.md: Hafıza sistemi
- 2. Skills: Yeniden kullanılabilir iş akışları
- 3. Hooks: Yaşam döngüsü kancaları
- 4. Rules: Yol bazlı kurallar
- 5. Sub-agents: Alt ajanlar
- 6. MCP Servers: Dış araç bağlantıları
- 7. Settings: Yapılandırma sistemi
- Sıkça sorulan sorular
Önce 5 senaryoya bak: Kaçını yaşadın?
“Nasıl kullanılır”ı anlatmadan önce kendini bul. Aşağıdaki 5 senaryodan herhangi birine basmışsan, yanlış yöntem kullanıyor olabilirsin demektir.
Senaryo 1: CLAUDE.md şişmesi
CLAUDE.md’n 200 satırı geçti. Kodlama standartları 50 satır, mimari açıklama 80 satır, deployment süreci 60 satır, çeşitli ufak tefek kurallar 40 satır. Her toplantıdan sonra içine bir şeyler daha ekliyorsun. Sonuçta Claude’un uyma oranı giderek düşüyor—uymak istemiyor değil, bağlam penceresi o kadar büyük değil, bu kadar kuralı “göremiyor”.
Senaryo 2: Her seferinde aynı talimatı elle yazmak
Claude Code’dan her Code Review istediğinde aynı metni yapıştırıyorsun: “Takım standartlarımıza göre kontrol et… Özellikle şu boyutlara dikkat et… Çıktı formatı şöyle olsun…” 20 kere yapıştırdıktan sonra hayatını sorgulamaya başlıyorsun.
Senaryo 3: Claude bazı dizinlere dokunmaması gerektiğini sürekli unutuyor
CLAUDE.md’ye “legacy/ dizinindeki kodlara dokunma” yazdın ama Claude ara sıra yine elini atıyor. Kasten ihlal etmiyor, CLAUDE.md kuralları “tavsiye” niteliğinde, zorunlu değil.
Senaryo 4: Claude’un dış sistemlere erişmesi gerekiyor
Claude’un doğrudan Jira’dan ticket açıklamasını okumasını, Sentry’den canlı hataları çekmesini, veritabanından tablo yapısını görmesini istiyorsun. Ama Claude Code native olarak bunları desteklemiyor, elle kopyala-yapıştır yapmak zorunda kalıyorsun.
Senaryo 5: Karmaşık görev bağlamı tüketiyor
Büyük bir refactor görevi, Claude’un aynı anda 10 dosyaya bakması, test çalıştırması, kod değiştirmesi gerekiyor. Konuşmanın ortasında bağlam sıkıştırılıyor, daha önce konuşulan mimari kararlar tamamen unutuluyor.
Eğer 2 veya daha fazlasını yaşadıysan, bundan sonraki kısım senin için değerli.
Bir tablo: 7 yönteme hızlı bakış
Önce genel bir tablo, sonra tek tek açacağız.
Yöntem | Tek cümlelik açıklama | Yapılandırma dosyası | Kapsam | Zorunluluk seviyesi ----------------|------------------------------------------------|-----------------------------------|---------------------------------|-------------------------------------- CLAUDE.md | Kalıcı talimatlar, her oturumda otomatik yüklenir | CLAUDE.md (Markdown) | Organizasyon / Kullanıcı / Proje / Yerel | Yumuşak (bağlama enjekte edilir) Skills | Yeniden kullanılabilir iş akışları, ihtiyaç halinde yüklenir | SKILL.md (dizin formu) | Kurumsal / Kişisel / Proje / Eklenti | Yumuşak (çağrıldığında yüklenir) Hooks | Yaşam döngüsü kancaları, sert şekilde çalıştırılır | settings.json (JSON) | Organizasyon / Kullanıcı / Proje / Yerel | Sert (exit code 2 ile engeller) Rules | Yol bazlı koşullu kurallar | .claude/rules/*.md | Proje seviyesi | Yumuşak (CLAUDE.md alt sistemi) Sub-agents | Özel alt ajanlar, bağlam izolasyonu | .claude/agents/*.md | Organizasyon / CLI / Proje / Kullanıcı | Sert (araç kısıtlamaları geçerli) MCP Servers | Dış araç ve veri kaynaklarına bağlantı | .mcp.json / CLI | Yerel / Proje / Kullanıcı | Sert (bağlantı kurulması gerekir) Settings | Global yapılandırma: yetkiler, model, ortam değişkenleri | settings.json (JSON) | Organizasyon / Kullanıcı / Proje / Yerel | Sert (istemci tarafından zorunlu uygulanır)Kritik ayrım: CLAUDE.md / Skills / Rules “tavsiye” niteliğindedir. Claude bu içerikleri görür ama uyup uymamaya kendisi karar verir. Hooks / Sub-agents / MCP / Settings ise “kural”dır. Bu kurallara uyulmazsa işlem engellenir veya gerçekleştirilemez.
Karar çerçevesi: Hangisini kullanmalısın?
Bir özelleştirme talebi geldiğinde aşağıdaki 3 soruyu kullanarak karar ver:
Soru 1: Bu kuralın “her oturum için geçerli olması mı gerekiyor, yoksa sadece belirli durumlarda mı uygulanması gerekiyor?”
- Her seferinde → Soru 2A
- Belirli senaryolar → Soru 2B
Soru 2A: Kural, “Claude’a ne yapması gerektiğini söylemek” midir, yoksa “Claude’un bir şeyi yapmamasını zorlamak” mıdır?
- Nasıl yapılacağını anlat → CLAUDE.md (Kodlama kuralları, isimlendirme yöntemleri, proje yapısı)
- Zorla yapılamaz → Hooks (rm -rf işleminin yürütülmesi yasaktır; otomatik biçimlendirme de yapılamaz) veya Settings (İzin reddetme kuralları uygulanır)
Soru 2B: Bu senaryo, “yeniden kullanılabilir bir iş akışı” mıdır, yoksa “dış araçlarla bağlantılı bir yapı” mıdır?
- Yeniden kullanılabilir iş akışları → Skills (Kod inceleme süreçleri, yayın kontrol listeleri, belge oluşturma)
- Dış araçlara bağlantı → MCP Sunucuları (Jira, Sentry, veritabanları, Figma)
Soru 3: Kurallar yalnızca kod havuzunun belirli bir alt dizini için mi geçerlidir?
- Evet → Rules (.claude/rules/, paths alanı ile birlikte kullanılır)
- Değil → Soru 2A/2B’ye geri dön
Ek değerlendirmeler:
- Bağlamın ayrılması, eşzamanlı işlem yapılması ve araçların yetkilerinin sınırlanması gerekiyor → Alt-ajanlar
- Modelin yapılandırılması, izinlerin belirlenmesi ve çevre değişkenlerinin ayarlanması gerekiyor → Ayarlar
- Hızlı özelleştirilebilir komutlar (Takımın mevcut arşivinde bulunanlar) → Komutlar (.claude/commands/, Skills ekosistemiyle entegre edilmiştir)
Tek cümleyle özet: CLAUDE.md “ne olduğu”nu yönetir, Skills “nasıl yapılacağı”nı yönetir, Hooks “yapılamayacaklar”ı yönetir, Rules “nerede geçerli olduğu”nu yönetir, Sub-agents “kimin yapacağı”nı yönetir, MCP “neye bağlanabileceği”ni yönetir, Settings “global anahtarlar”ı yönetir.
Tek tek parçalama: Her yöntemin prensibi + kullanımı + anti-pattern’i
1. CLAUDE.md: Hafıza sistemi
Prensip
CLAUDE.md, Claude Code’un “uzun süreli hafızasıdır”. Her oturum başladığında Claude bu dosyaların içeriğini otomatik olarak bağlam penceresine yükler. Tek seferlik talimat değildir, tüm oturum boyunca kalıcı bağlamdır.
Yükleme sırası (genişten dara, içerik birleştirilir, üzerine yazılmaz):
- Organizasyon seviyesi (en yüksek öncelik): macOS’ta /Library/Application Support/ClaudeCode/CLAUDE.md, Linux’ta /etc/claude-code/CLAUDE.md
- Kullanıcı seviyesi: ~/.claude/CLAUDE.md
- Proje seviyesi: ./CLAUDE.md veya ./.claude/CLAUDE.md
- Yerel kişisel seviye: ./CLAUDE.local.md (gitignore’lanır, commit edilmez)
Aynı seviyedeki CLAUDE.md ve CLAUDE.local.md birleştirilir, birbirinin üzerine yazmaz. Alt dizinlerdeki CLAUDE.md dosyaları Claude o dizindeki dosyaları okuduğunda ihtiyaç halinde yüklenir.
@path/to/file sözdizimini destekler, en fazla 4 katman atlama yapılabilir. Bu özellik oldukça kullanışlıdır—farklı konulara ait kuralları ayrı dosyalara bölüp @ ile içeri alabilirsin, tek dosyanın şişmesini engellersin.
Kullanım örneği
# CLAUDE.md ## Proje Mimarisi Bu proje Spring Boot 3.2 monolit, Java 17. Modül yapısı: api/ (arayüz katmanı), service/ (iş katmanı), dao/ (veri katmanı) ## Kodlama Standartları - 2 boşluk girinti kullan - İsimlendirme: Sınıf isimleri PascalCase, metot isimleri camelCase, sabitler UPPER_SNAKE_CASE - Controller’da iş mantığı olmaz, sadece parametre doğrulama ve yönlendirme yapılır ## Build ve Test - Build: `./gradlew build` - Test: `./gradlew test` - Lint: `./gradlew spotlessCheck` ## Alt kuralları içeri al @docs/database-conventions.md @api/rest-standards.mdAnti-pattern’ler
Anti-pattern 1: Dosya 200 satırı aşıyor
CLAUDE.md içeriği her oturumda bağlam penceresine enjekte edilir. Dosya büyüdükçe gerçek görev için kalan bağlam alanı küçülür. 200 satırı geçtikten sonra Claude’un uyma oranı belirgin şekilde düşer—uymak istemiyor değil, dikkati dağılıyor.
Çözüm: Parçala. Uzun kuralları .claude/rules/ içine taşıyıp paths alanı ile yol bazlı eşleştir, ya da @ sözdizimi ile alt dosyalara böl.
Anti-pattern 2: Belirsiz talimat yazmak
# Kötü yazım Kodu formatla, stili tutarlı tut. # İyi yazım 2 boşluk girinti kullan. Satır genişliği 120 karakter. Import sırası: java.* → javax.* → üçüncü parti → bu proje.Claude uzun talimattan korkmaz, belirsiz talimattan korkar. “Kodu formatla” gibi bir cümleyi ne istediğini anlayamaz.
Anti-pattern 3: CLAUDE.md içinde süreç adımları yazmak
Eğer CLAUDE.md içinde “Birinci adımda X yap, ikinci adımda Y yap, üçüncü adımda Z yap” yazdığını fark ediyorsan—bu CLAUDE.md’nin işi değil. Süreç adımları Skills ile paketlenecek, ihtiyaç halinde çağrılacak, günlük bağlamı işgal etmeyecek.
2. Skills: Yeniden kullanılabilir iş akışları
Prensip
Skills, Claude Code’un “senaryo defteridir”. Tekrarlanabilir bir iş akışını bir Skill olarak paketlersin, ihtiyaç olduğunda çağırırsın, olmadığı zaman bağlamı işgal etmez.
Bu, CLAUDE.md ile en kritik farktır: CLAUDE.md içeriği her oturumda bağlamda durur, Skills içeriği ise sadece çağrıldığında yüklenir. Skill’in description’ı Claude’un çağırıp çağırmayacağına karar vermesi için sürekli bağlamda kalır, ama tam içerik ihtiyaç halinde yüklenir.
Yapılandırma formatı
.claude/skills/
└── code-review/
└── SKILL.mdSKILL.md, YAML frontmatter + Markdown body’den oluşur:--- name: code-review description: "Takım standartlarına göre Code Review yap, güvenlik, performans, okunabilirlik kontrol et" when_to_use: "Kullanıcı review isterse veya PR göndermeden önce" argument-hint: "[file-or-pr]" model: sonnet effort: high paths: ["src/**/*.ts"] allowed-tools: Read, Grep, Glob, Bash(git *) --- ## Code Review Kontrol Listesi 1. Güvenlik kontrolü: SQL injection, XSS, hardcode edilmiş anahtarlar 2. Performans kontrolü: N+1 sorgu, büyük nesne döngüde oluşturma 3. Okunabilirlik: Metot 30 satırı geçmesin, isimlendirme kendini açıklasın $ARGUMENTS belirtilen dosya veya PR’ı review et.Birkaç kullanışlı frontmatter alanı:
- context: fork — izole alt ajanda çalıştırır, ana konuşma bağlamını kirletmez
- disable-model-invocation: true — sadece kullanıcı manuel /skill-name ile çağırabilir, Claude otomatik tetiklemez
- user-invocable: false — tam tersi, sadece Claude otomatik çağırabilir, kullanıcı manuel tetikleyemez
- model: haiku — bu Skill’i daha hızlı ve ucuz modelle çalıştır (arama, keşif tipi görevler için uygun)
Dinamik bağlam enjeksiyonu: SKILL.md içinde !`git diff HEAD` sözdizimi kullanılırsa, Claude içeriği görmeden önce shell komutunu çalıştırır ve çıktıyı bağlama enjekte eder. Bu özellik çok güçlüdür—Skill çalışırken otomatik olarak mevcut git durumunu, son değişiklikleri, test sonuçlarını vs. gerçek zamanlı bilgi olarak alabilirsin.
Anti-pattern’ler
Anti-pattern 1: Tüm Skill’leri disable-model-invocation: true yapmak
“Claude’un bu yetenekleri otomatik kullanmasını istemiyorum, ya yanlış kullanırsa?” diye düşünebilirsin. Ama otomatik çağrıyı tamamen kapatırsan Claude bu Skill’lerin varlığından asla haberdar olmaz—description bağlamda olsa bile Claude “Kullanıcı açıkça istemediği için otomatik çağırmamalıyım” diye düşünür. Sonuç olarak Skill kütüphanen süs eşyasına döner.
Çözüm: Çoğu Skill varsayılan kalsın (otomatik çağrıya izin verilsin). Sadece yan etkisi olan Skill’ler (deploy, silme gibi) için disable-model-invocation: true koy.
Anti-pattern 2: Skill body’si çok uzun
Skill’in tam içeriği çağrıldıktan sonra bağlamda kalır. 5000 token’lık bir Skill yazarsan her çağrıdan sonra bu 5000 token bağlam penceresini işgal eder. Compaction sonrası tekrar eklenir ama üst sınırı vardır (tek Skill en fazla 5000 token, toplam 25000 token).
Çözüm: Referans materyalleri Skill dizinindeki yardımcı dosyalara koy, SKILL.md sadece çekirdek akışı tutsun. @references/xxx.md ile içeri al.
Anti-pattern 3: context: fork ile sadece rehber tipi Skill çalıştırmak
context: fork izole bir alt ajan oluşturur. Eğer Skill’in sadece “Claude’a bazı standartları söylemek” ise, “bir dizi işlem yaptırmak” değilse, fork edilen alt ajan rehberi alır ama net bir çalıştırma prompt’u olmaz, sonuç fork etmemekten daha kötü olur.
3. Hooks: Yaşam döngüsü kancaları
Prensip
Hooks, Claude Code’un “otomatik çalıştırıcısıdır”. Belirli yaşam döngüsü olayları gerçekleştiğinde senin yapılandırdığın script’leri, HTTP isteklerini, hatta LLM prompt’larını otomatik çalıştırır. CLAUDE.md ile en büyük farkı: Hooks zorunlu çalışır—exit code 2 işlemi doğrudan engeller, tavsiye değildir.
Yapılandırma yeri: settings.json içindeki hooks alanı (kullanıcı veya proje seviyesi).
30’dan fazla olay destekler, en sık kullanılanlar:
Olay | Tetiklenme zamanı | Tipik kullanım ------------------|----------------------------|--------------------------------- PreToolUse | Araç çalışmadan önce | Tehlikeli komutları engelle, güvenlik kontrolü PostToolUse | Araç çalıştıktan sonra | Otomatik formatlama, otomatik lint SessionStart | Oturum başlatılırken | Ortam değişkenlerini yükle, bağımlılık kontrolü Stop | Claude cevabı bitirdikten sonra | Bildirim gönder, log kaydet UserPromptSubmit | Kullanıcı girdikten sonra | Girdi ön işleme, anahtar kelime değiştirme5 çeşit Hook tipi: command (Shell komutu), http (POST isteği), mcp_tool (MCP aracı çağır), prompt (tek tur LLM değerlendirmesi), agent (alt ajan değerlendirmesi).
Kullanım örneği: Dosya düzenlendikten sonra otomatik Prettier formatlama
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write",
"args": ["${CLAUDE_FILE_PATH}"],
"timeout": 30
}
]
}
]
}
}exit code anlamları (en çok karıştırılan kısım):- exit 0: Başarılı, devam et
- exit 1: Engelleyici olmayan hata (log kaydeder, ana akışı etkilemez)
- exit 2: Engelleyici hata (işlemi doğrudan durdurur)
Anti-pattern’ler
Anti-pattern 1: exit 1 ile işlemi engelleyebileceğini sanmak
En sık yapılan yanılgı. Hook script’inde tehlikeli komutu tespit edip exit 1 ile çıkıyorsun—Claude yine de çalıştırıyor. Sebep basit: exit 1 sadece engelleyici olmayan hatadır, Claude “Hook bir hata verdi” diye bir uyarı alır ama yok saymayı seçebilir.
Çözüm: İşlemi engellemek için mutlaka exit 2 kullan. Ya da stdout’a JSON bas: {"decision": "block", "reason": "rm -rf çalıştırılmasına izin yok"}
Anti-pattern 2: if filtresi koymadan her araç çağrısında Hook tetiklemek
{
"matcher": "*",
"hooks": [{ "type": "command", "command": "my-script.sh" }]
}Bu her araç çağrısında yeni bir process spawn eder. Claude bir konuşmada onlarca araç çağırabilir, senin script’in de onlarca kere çalışır. Hafifinde zaman kaybı, ağırında tüm konuşmayı yavaşlatır.Çözüm: matcher ile araç adını net eşleştir (örneğin "Bash", "Edit|Write"), if alanı ile daha da daralt (örneğin "if": "Bash(rm *)").
Anti-pattern 3: Hook içinde karmaşık mantık yapmak
Hook’un tasarım amacı “kısa ve hızlı” otomatik işlemlerdir. Eğer Hook script’inde 200 satır Python yazdığını fark ediyorsan—dur, bu iş Skills veya Sub-agents’ın işidir.
4. Rules: Yol bazlı kurallar
Prensip
Rules, CLAUDE.md sisteminin alt özelliğidir, somut bir sorunu çözer: Farklı dizinlerin farklı kurallara ihtiyacı vardır.
Monorepo’da frontend dizini ile backend dizininin kodlama standartları tamamen farklı olabilir. Tek bir CLAUDE.md’ye iki set kural yazmak karışıklık yaratır. Rules, farklı yollar için farklı kurallar tanımlamana izin verir, Claude sadece ilgili dizine eriştiğinde yüklenir.
Yapılandırma şekli: .claude/rules/ dizini altında .md dosyası oluştur, YAML frontmatter’daki paths alanı ile geçerli yolları belirt.
--- paths: ["src/api/**", "tests/api/**"] --- ## API Katmanı Standartları - Controller metotlarında mutlaka @Validated annotation olsun - Dönüş değeri ResponseEntity ile sarmalansın - Exception’lar @RestControllerAdvice ile global yönetilsin
--- paths: ["src/dao/**", "resources/mapper/**"] --- ## Veri Katmanı Standartları - DAO katmanında SQL birleştirmek yasak, mutlaka MyBatis XML kullan - Sayfalama için PageHelper kullan, elle LIMIT yazmaAnti-pattern’ler
Anti-pattern 1: Rules ile CLAUDE.md’ye tekrar eden hatta çelişen kurallar yazmak
Rules, CLAUDE.md’den sonra eklenerek yüklenir. İki tarafta çelişen içerik olursa Claude’un davranışı öngörülemez olur.
Çözüm: CLAUDE.md sadece global kuralları yazsın, Rules yol özel kuralları yazsın. Global ile lokal kesişmesin.
Anti-pattern 2: paths’i çok geniş yazmak
paths: ["**"] yazmak hiçbir şey yazmamakla aynıdır—doğrudan CLAUDE.md’ye koymakla farkı kalmaz. Rules’un değeri tam eşleştirmede yatar.
5. Sub-agents: Alt ajanlar
Prensip
Sub-agents, Claude Code’un “klonlama yeteneğidir”. Karmaşık bir görev olduğunda özel bir alt ajan oluşturup ona devredebilirsin. Kendi bağımsız bağlam penceresi vardır, ana konuşmayı kirletmez. İş bitince sonucu ana ajana döner.
Temel değerler:
- Bağlam izolasyonu: Alt ajanın işlem süreci ana konuşmanın bağlamını şişirmez.
- Araç kısıtlaması: Alt ajana sadece Read/Grep gibi salt okunur araçlar verilebilir, böylece kodda değişiklik yapması engellenir.
- Paralel çalıştırma: Birden fazla alt ajan aynı anda çalışabilir (en fazla 5 katman iç içe).
- Model yönlendirme: Keşif görevleri için ucuz ve hızlı Haiku, derin görevler için Sonnet/Opus kullanılabilir.
Yapılandırma şekli: .claude/agents/ dizini altında .md dosyası oluştur.
--- name: code-reviewer description: "Kod kalitesi, güvenlik ve best practice incelemesi yap" tools: Read, Glob, Grep, Bash disallowedTools: Write, Edit model: sonnet maxTurns: 50 isolation: worktree --- Sen bir kod inceleme uzmanısın. Kodu analiz et ve somut, uygulanabilir geri bildirim ver. Özellikle şunlara odaklan: güvenlik, performans, sürdürülebilirlik.Üç çağırma şekli:
- Doğal dil: Konuşmada görevi tarif et, Claude kendisi alt ajana devredip devretmeyeceğine karar verir
- @mention: @code-reviewer auth modülündeki değişikliklere bak, bir kere çalışmasını garanti et
- Oturum seviyesi: --agent code-reviewer, tüm oturum o alt ajanı kullanır
Yerleşik alt ajanlar (senin oluşturmana gerek yok):
- Explore: Haiku modeli, salt okunur, hızlı arama ve keşif için (CLAUDE.md ve git status yüklemesini atlar, en hızlısı)
- Plan: Mevcut modeli miras alır, salt okunur, planlama ve araştırma için
- general-purpose: Tüm araçlar, karmaşık çok adımlı görevler için
Anti-pattern’ler
Anti-pattern 1: description alanını çok belirsiz yazmak
# Kötü yazım description: "Bana bazı işler yap" # İyi yazım description: "TypeScript kodunun kalite, güvenlik ve performans sorunlarını incele, yapılandırılmış review çıktısı ver"Claude description’a bakarak ne zaman bu alt ajana görev devredeceğine karar verir. Belirsiz yazarsan ne zaman kullanacağını bilemez.
Anti-pattern 2: Yerleşik alt ajanın işlevini kopyalamak
Arama yapmak için “explorer” diye bir alt ajan oluşturmana gerek yok—yerleşik Explore zaten yapıyor ve daha ucuz Haiku modelini kullanıyor. Özel alt ajanlar yerleşiklerin yapamadığı işleri yapmalı.
Anti-pattern 3: Alt ajan iç içeliğini çok derin tutmak
Alt ajan başka alt ajan üretebilir, en fazla 5 katman. Ama her katman ekstra bağlam penceresi maliyeti demektir. Gerçekten gerekmedikçe 1-2 katman yeterlidir.
6. MCP Servers: Dış araç bağlantıları
Prensip
MCP (Model Context Protocol), Anthropic’in çıkardığı açık protokoldür, Claude Code’un dış araçlara, veritabanlarına ve API’lere bağlanmasını sağlar. Claude Code’un native olarak “sadece yerel dosya ve terminalle işlem yapabilme” sınırını kaldırır.
MCP Server sayesinde Claude doğrudan Jira ticket’ı okuyabilir, Sentry hatalarını çekebilir, veritabanı tablo yapısını görebilir, Figma tasarımını manipüle edebilir—senin elle kopyala-yapıştır yapmana gerek kalmaz.
Yapılandırma şekli:
CLI yöntemi (önerilen, tek satırda hallolur):
# Uzak HTTP servisi claude mcp add --transport http notion https://mcp.notion.com/mcp # Yerel stdio process claude mcp add --transport stdio airtable -- npx -y airtable-mcp-serverJSON yöntemi (.mcp.json, depoya commit edilip takımla paylaşılabilir):
{
"mcpServers": {
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer ${GITHUB_TOKEN}"
}
},
"database": {
"command": "/path/to/db-server",
"args": ["--config", "config.json"],
"env": {
"DB_URL": "${DB_URL}"
}
}
}
}Üç iletim protokolü:- http (önerilen): Uzak servisler için uygun, otomatik yeniden bağlanır, OAuth destekler
- stdio: Yerel process için uygun, Claude alt process başlatıp iletişim kurar
- ws (WebSocket): Olay push edilmesi gereken senaryolar için uygun
Anti-pattern’ler
Anti-pattern 1: .mcp.json içinde API Key hardcode etmek
// Asla böyle yazma
"headers": { "Authorization": "Bearer sk-xxxxx" }
// Ortam değişkeni kullan
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }.mcp.json genellikle Git deposuna commit edilir. Hardcode edilmiş anahtarlar depoyu klonlayan herkes tarafından görülür.Anti-pattern 2: Uzak MCP Server’ın güvenliğine körü körüne güvenmek
MCP Server temelde Claude’a dış veri ve araç enjekte eden bir yapıdır. Uzak Server saldırganın kontrolüne geçerse Claude’un bağlamına zararlı komut enjekte edebilir (prompt injection). Kurumsal ortamlarda allowedMcpServers / deniedMcpServers ile beyaz liste kontrolü yap.
Anti-pattern 3: SSE iletimini kullanmak (artık kullanımdan kaldırıldı)
SSE (Server-Sent Events) deprecated olarak işaretlendi, resmi olarak http kullanılması öneriliyor. Dokümantasyonda SSE yapılandırma örneği görürsen doğrudan http ile değiştir.
7. Settings: Yapılandırma sistemi
Prensip
Settings, Claude Code’un “kontrol panelidir”. Yetki kuralları, model seçimi, ortam değişkenleri, kullanıcı arayüzü tercihleri gibi global davranışları yönetir.
Yapılandırma seviyeleri (öncelik yüksekten düşüğe):
- Organizasyon seviyesi (managed settings): Yönetici yapılandırır, kişi üzerine yazamaz
- CLI parametreleri: Komut satırından geçirilir, geçici geçerlidir
- Yerel proje seviyesi: .claude/settings.local.json (gitignore)
- Proje seviyesi: .claude/settings.json (depoya commit edilir)
- Kullanıcı seviyesi: ~/.claude/settings.json (en geniş, önceliği en düşük)
Yetki kurallarının özel birleştirme mantığı vardır: Diğer ayarlar “yüksek öncelik düşük önceliği ezer”, ama yetki kuralları katmanlar arasında birleştirilir. Yani proje seviyesindeki allow kuralları ile kullanıcı seviyesindeki allow kuralları birleştirilir, birbirini ezmez.
Kullanım örneği
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Read(~/.zshrc)"
],
"deny": [
"Bash(curl *)",
"Read(./.env)",
"Read(./secrets/**)"
]
},
"model": "claude-sonnet-4-6",
"language": "chinese",
"autoCompactEnabled": true
}Anti-pattern’lerAnti-pattern 1: Doğrudan ~/.claude.json dosyasını düzenlemek
Bu dosya Claude Code tarafından dahili yönetilir, elle düzenlemek beklenmeyen davranışlara yol açabilir. Kullanıcı seviyesi ayarlar için ~/.claude/settings.json kullanılmalı.
Anti-pattern 2: $schema ile doğrulama yapmamak
Settings JSON formatındadır, bir virgül eksik olsa parse hatası verir. $schema alanı eklenince editör otomatik olarak alan adlarını ve tiplerini doğrular, hataları önceden yakalar.
Anti-pattern 3: Settings içinde davranış talimatı yazmak
Settings “yapılandırma” yönetir—yetkiler, model, ortam değişkenleri. Eğer settings.json içine “lütfen 2 boşluk girinti kullan” gibi davranış talimatı yazarsan çalışmaz. Davranış talimatları CLAUDE.md’ye aittir.
Gerçek bir proje yapılandırması
Sadece teori yetmez, gerçekten kullandığım bir proje yapılandırmasını vereyim:
my-project/ ├── CLAUDE.md # Global kurallar (< 100 satır) ├── .claude/ │ ├── settings.json # Yetki kuralları + Hooks │ ├── rules/ │ │ ├── api-rules.md # API katmanı özel kuralları │ │ └── dao-rules.md # Veri katmanı özel kuralları │ ├── skills/ │ │ ├── code-review/ │ │ │ └── SKILL.md # Code Review iş akışı │ │ └── deploy-check/ │ │ └── SKILL.md # Deploy öncesi kontrol listesi │ ├── agents/ │ │ └── security-auditor.md # Güvenlik denetimi alt ajanı │ └── mcp.json # MCP Server yapılandırması └── .claude/settings.local.json # Yerel kişisel override (gitignore)CLAUDE.md içinde sadece global ve kısa kurallar (< 100 satır) durur. Yol özel kurallar rules/ içine ayrılır. Yeniden kullanılabilir iş akışları skills/ içine ayrılır. İzolasyon gerektiren görevler agents/ ile yapılır. Dış araçlar mcp.json ile bağlanır. Yetkiler ve Hooks settings.json içine konur.
Böylece her dosya kendi işini yapar, 500 satırlık bir CLAUDE.md’ye her şeyin tıkıştırıldığı durum ortaya çıkmaz.
Sıkça sorulan sorular
Q: CLAUDE.md ile .claude/CLAUDE.md arasında ne fark var? Hangisine koymak daha iyi?
A: İki konum da yüklenir, etki aynıdır. Fark dosya sistemi konumundadır: Proje kökündeki CLAUDE.md daha görünürdür, .claude/CLAUDE.md daha temizdir (kök dizini kirletmez). Proje kökünde zaten README.md, package.json gibi bir sürü dosya varsa .claude/CLAUDE.md önerilir. İkisi de olur, takımın birini seçip tutarlı olması yeter.
Q: Skills ile .claude/commands/ arasındaki ilişki nedir? Eski commands’lerim hâlâ çalışır mı?
A: Skills, commands’in yükseltilmiş versiyonudur. Anthropic ikisini birleştirdi—commands dosyaları hâlâ geçerlidir ama yeni özellikler (context: fork, paths eşleştirme, yardımcı dosyalar) sadece Skills’te desteklenir. Mevcut commands’lerin varsa taşımana gerek yok, çalışmaya devam ederler. Ama yeni özel komutlar için Skills kullanman önerilir.
Q: Hooks ile CLAUDE.md kuralları arasındaki temel fark nedir?
A: CLAUDE.md “tavsiye”, Hooks “kural”dır. CLAUDE.md’ye “legacy/ dizinine dokunma” yazarsan Claude mümkün olduğunca uyar ama ara sıra ihlal edebilir. Hook ile PreToolUse’da legacy/ dizinine yazma işlemi tespit edilip exit 2 döndürülürse işlem doğrudan engellenir—Claude’un ihlal etme şansı bile olmaz.
Kuralın kesinlikle uyulması gerekiyorsa (güvenlik, uyumluluk, yanlış işlem önleme) Hooks kullan. Kodlama stili, tercih tavsiyesi ise CLAUDE.md kullan.
Q: Her proje için ayrı MCP Server mı yapılandırmam gerekiyor?
A: Şart değil. MCP Server’ın üç kapsamı vardır: Yerel (.mcp.json proje dizininde, sadece o proje için geçerli), Proje (.mcp.json depoya commit edilir, takım paylaşır), Kullanıcı (~/.claude.json içinde yapılandırılır, tüm projelerde geçerli). GitHub MCP gibi genel olanlar kullanıcı seviyesine, projeye özel veritabanı Server’ı proje seviyesine konur.
Q: 7 yöntem birbirleriyle çakışır mı?
A: Evet, en sık görülen iki çakışma vardır. Biri CLAUDE.md ile Rules’un çelişen içerik yazmasıdır—çözüm CLAUDE.md’nin sadece global kuralları, Rules’un yol özel kuralları yazması, kesişmemesidir. İkincisi Hooks ile Settings yetki kurallarının çakışmasıdır—Hooks settings.json içinde yapılandırılır, proje seviyesi Hook bir işlemi engellerken kullanıcı seviyesi Settings allow kuralı izin veriyorsa sonuç birleştirme mantığına bağlıdır. Takımın tek bir seviyede yapılandırması, dağılmaması önerilir.
Sonuç olarak, Claude Code’un 7 özelleştirme yöntemi “hangisi daha iyi” sorusu değil, “hangi senaryoda hangisi” sorusudur. Tüm kuralları CLAUDE.md’ye tıkıştırmak, tüm kıyafetleri tek çekmeceye atmak gibidir—sokarsın ama aradığın zaman her şey karışır. Ayrıştırıp her birinin kendi işini yapmasını sağlarsan Claude’un performansı çok daha iyi olur.
Bu yazı her yöntemin prensibini, kullanımını ve anti-pattern’ini parçaladı ama asıl çekirdek o karar çerçevesidir—bir sonraki özelleştirme ihtiyacında önce kendine üç soru sor, cevap kendiliğinden çıkar.
