settings.json vs CLAUDE.md — davranışı nereye yazarsın

Yaygın hata: kullanıcı bir kuralı CLAUDE.md’ye yazar, ama davranış değişmez. Çünkü o kural aslında harness seviyesinde zorlanmalıydı, model seviyesinde değil.

İki katmanlı sistem

Claude Code = harness (CLI, izinler, hooks, dosya işlemleri) + model (Claude’un kendisi). Kuralın hangi katmana ait olduğuna göre nereye yazılacağı değişir.

Katman	Dosya	Tetik
Harness	settings.json	Çalıştırma anında zorla uygulanır — model’in seçimi yok
Model	CLAUDE.md	Modele “talimat” gider; model isterse uyar, isterse kaçar

CLAUDE.md ne için?

Modele bağlam ve tercih iletmek için. Tipik içerikler:

• Proje hakkında genel bilgi (stack, amaç)
• Kod stili tercihleri (“Türkçe yorum yazma”, “yeni dosya yerine mevcut düzelt”)
• Domain bilgisi (“MemKraft hafıza dizini ./memory/”)
• Workflow rehberleri (deploy nasıl çalışır, hangi branch ne içindir)

Model bunu okur, çoğunlukla uyar; ama “hard rule” değildir — uzun session’da unutabilir, başka prompt baskın gelirse atlayabilir.

settings.json ne için?

Harness’a kural enjekte etmek için. Tipik içerikler:

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Read(*)"],
    "deny": ["Bash(rm -rf:*)", "Bash(git push --force:*)"]
  },
  "env": {
    "ANTHROPIC_API_KEY": "...",
    "DEBUG": "true"
  },
  "hooks": {
    "SessionStart": [...],
    "PostToolUse": [...]
  },
  "model": "claude-opus-4-7",
  "statusLine": "...",
  "outputStyle": "minimal"
}

Bu maddeler model’in kararına bırakılmaz — harness bunları ya zorlar ya engeller. Örnekler:

• “Co-Authored-By satırı commit’lere ekleme” → CLAUDE.md’ye yaz, model bazen unutur. Yerine: PreToolUse hook’u ile git commit çağrısını intercept et, mesajı düzenle.
• “Geliştirme sunucusu otomatik başlasın” → CLAUDE.md’de “lütfen başlat” demek model’e iş bindirir. Yerine: SessionStart hook’u ile npm run dev arkaplan başlat.
• “Belirli komutlar engellensin” → CLAUDE.md “yapma” der, model unutur. Yerine: permissions.deny.

Karar matrisi

Kural	Yer
”Türkçe cevap ver”	CLAUDE.md (tercih)
“rm -rf yasak”	settings.json deny
”PR description bu şablonu kullansın”	CLAUDE.md (referans)
“Her commit sonrası lint çalıştır”	settings.json hook
”Test database’i mock’lama, gerçek olsun”	CLAUDE.md (uyarı)
“Production env’e push yasak”	settings.json deny + branch protection
”memkraft komutlarını sormadan çalıştır”	settings.json allow
”Statusbar’da git branch göster”	settings.json statusLine
”Domain knowledge: müşteri segmentleri”	CLAUDE.md

Layering ipucu

Üç katmanlı settings.json var:

1. ~/.claude/settings.json — kullanıcı seviyesi (tüm projelerde geçerli)
2. <repo>/.claude/settings.json — proje seviyesi (commit edilir, takım paylaşır)
3. <repo>/.claude/settings.local.json — kişisel override (git-ignored)

Aynı şekilde ~/.claude/CLAUDE.md (kullanıcı), <repo>/CLAUDE.md (proje), <repo>/.claude/rules/*.md (lazy-load) hiyerarşisi var.

Pattern: paths: ile lazy-load rule’lar

Büyük CLAUDE.md kötüdür — token yer, dikkat dağıtır. Yerine .claude/rules/*.md dosyalarına böl:

---
paths:
  - "src/api/**"
  - "src/server/**"
---

API kuralları:
- Endpoint'lerde async/await kullan
- Hata kodları RFC 7807 formatında

Sadece o path’lerdeki dosyaya dokunulduğunda Claude’a enjekte edilir.

<important if="..."> etiketi

CLAUDE.md ihlal edilen bir kuralı koşullu olarak vurgulamak için (Dex/HumanLayer pattern):

<important if="creating commits">
Co-Authored-By satırı kullanma.
</important>

Model commit oluşturduğunda bu blok kararına dahil olur; başka iş yaparken bağlamı kirletmez.

Sıradaki

Workflow pattern’leri — kuralları, hooks’u ve subagent’ları birleştirmek.