Claude Code’un yaratıcısı Boris Cherny, 2026-01-02’de X’te aracı nasıl kullandığına dair on üç maddelik bir dizi paylaştı; dizi, kurulumunun şaşırtıcı derecede sade olduğu notuyla açılıyor. 2026-11-08’de okuduğumuzda ilk gönderi yaklaşık 8,2 milyon, 13. madde yaklaşık 575 bin görüntülenme gösteriyordu. On ay Claude Code için uzun bir süre: varsayılan model, varsayılan izin modu, eğik çizgi komutlarının düzeni ve yerel ile bulut oturumları arasındaki devir biçimi değişti. Bu yüzden yazı diziyi yeniden anlatmak yerine her maddeyi o gün okunan belgelerin yanına koyuyor.
Boris Cherny: dizinin başlangıcı (2026-01-02) · Boris Cherny: 13. madde, doğrulama döngüsü
Ölçüt, resmi best practices sayfasından geliyor: her talimat ya belirsizdir (model için yazılır, uyup uymamaya model karar verir: istem, CLAUDE.md, bir skill) ya da belirlidir (model ne karar verirse versin harness olarak Claude Code tarafından yürütülür: hook, deny kuralı, yönetilen ayar). Dizideki alışkanlıkların bir kısmı ilk türe, bir kısmı ikinciye giriyor ve güvenilirlikleri bambaşka. Dizinin en güçlü iddiası 13. madde: Claude’a işini doğrulayacak bir yol verin, nihai sonuç iki üç kat iyileşsin. Yazının yapısı bu döngüyü izliyor.
Boris Cherny: 13. madde, doğrulama döngüsü · Claude Code belgeleri: Best practices
Önce sınırlar. Claude Code çalıştırmadık, bu hook’ları gerçek bir depoda etkinleştirmedik ve JSON, Markdown ile shell bloklarını yalnızca çevrimdışı kontrol ettik. Dizinin andığı bir model, komut ya da eklenti güncel belgelerle örtüşmüyorsa metin bunu açıkça söylüyor (dizide anlatıldığı şekliyle) ve güncel sayfayı gösteriyor. Görüntülenme sayıları ve sürüm numaraları 2026-11-08 okumalarıdır, sonradan geçerli olmayabilir.
1. Dizi ne diyor, biz neyi kontrol ettik
On üç madde dört gruba ayrılıyor. Oturum düzenleme: numaralı terminal sekmelerinde beş yerel Claude örneği ve biri girdi istediğinde sistem bildirimi (1. madde); claude.ai/code üzerinde beş ila on oturum daha, yerel oturumların bir ampersan ile web’e devredilmesi ve ara sıra --teleport ile geri alınması (2. madde); her iş için thinking açık Opus 4.5, Sonnet’ten büyük ve yavaş ama daha az yönlendirme gerektiriyor (3. madde). Bilgi biriktirme: Claude Code deposu için git’e alınmış tek bir CLAUDE.md, tüm ekip haftada birkaç kez düzenliyor, Claude yanlış bir şey yaptığında bir not ekleniyor (4. madde); iş arkadaşlarının PR’larında Claude’u etiketleyerek GitHub Action’ın dersi PR’ın parçası olarak CLAUDE.md’ye eklemesi, yazarın Dan Shipper’dan ödünç aldığı adıyla compounding engineering (5. madde).
Süreç ve izinler: oturumların çoğu plan modunda başlıyor, plan üzerinde gidip gelindikten sonra düzenlemeleri otomatik kabul etmeye geçiliyor (6. madde); sık tekrarlanan her iç döngü iş akışı için .claude/commands/ altında git’e alınmış bir eğik çizgi komutu (7. madde); birkaç alt ajan, Claude bitirdikten sonra temizlik yapan code-simplifier ve uçtan uca test talimatlarını tutan verify-app (8. madde); kodu biçimlendiren ve modelin kaçırdığı yaklaşık yüzde onu yakalayıp CI’ı yeşil tutan bir PostToolUse hook (9. madde); --dangerously-skip-permissions yok, bunun yerine güvenli komutları önceden onaylayan ve paylaşılan .claude/settings.json’a kaydedilen /permissions (10. madde); paylaşılan .mcp.json üzerinden MCP ile Slack, bq CLI ile BigQuery, Sentry’den günlükler (11. madde).
Ve doğrulama: uzun görevlerde Claude’dan bitince bir arka plan ajanıyla doğrulamasını istemek, bunu daha belirli yapmak için Stop hook kullanmak ya da ralph-wiggum eklentisi (12. madde); son öğüt olarak doğrulamanın muhtemelen en önemli şey olduğu, Claude’un claude.ai/code’daki her değişikliği Chrome uzantısıyla tarayıcı açıp arayüzü deneyerek ve yineleyerek test ettiği, doğru kontrolün alana göre değiştiği: bir bash komutu, bir test takımı, tarayıcı ya da telefon simülatörü (13. madde). Karşılaştırma hedefimiz code.claude.com belgelerinin 2026-11-08 tarihli hali; aşağıda güncel belgeler her zaman o tarihi ifade eder.
Boris Cherny: 13. madde, doğrulama döngüsü · Claude Code belgeleri: Best practices
2. 13 maddenin güncel belgelerle, mekanizma türüyle ve dosyayla eşlenmesi
Bu tablo yazının geri kalanının dizini. Mekanizma sütunu best practices tanımını izliyor: model karar verir, Claude talimatı okur ve seçer demek; harness zorlar, Claude Code her koşulda uygular demek. Aynı hedef çoğu zaman iki biçimde de var. Bitirmeden önce geçen bir typecheck, bir CLAUDE.md satırı (model) ya da bir Stop hook (harness) olabilir; belgelerin öğüdü, sürekli vurguladığınız bir CLAUDE.md satırının hook’a ait olduğu.
| Madde | Dizi (2026-01) | Güncel belgeler (2026-11-08) | Mekanizma | Dosya ya da komut |
|---|---|---|---|---|
| 1 | Paralel 5 yerel oturum, numaralı sekmeler, sistem bildirimleri | Terminal config: Ghostty, Kitty ve iTerm2 masaüstü bildirimi gösterebilir; paralel iş için oturum başına ayrı worktree (claude -w) | Araç katmanı, model davranışı değil | claude -w <name>; terminal bildirim ayarları |
| 2 | 5–10 bulut oturumu; ampersan ile devir; --teleport ile geri | Bulut oturumları sayfası: --cloud yeni bir bulut görevi başlatır; --teleport bulut oturumunu terminale çeker; CLI mevcut yerel oturumu buluta gönderemez (ampersan devri yalnızca dizide) | Araç katmanı | claude --cloud ...; claude --teleport |
| 3 | Her şey için thinking açık Opus 4.5 | Model config: çoğu planda varsayılan medium effort ile Opus 5.5; istem ifadesiyle değil /effort ile ayarlanır | Model karar verir (effort ne kadar düşüneceğini belirler) | /model; /effort high |
| 4 | Git’te tek ortak CLAUDE.md, her hatada bir not | Memory: CLAUDE.md 200 satırın altında kalsın; yalnızca depoda görünmeyeni yazın; /init, /doctor, /doctor prompt-audit | Model karar verir | CLAUDE.md; .claude/rules/*.md |
| 5 | GitHub Action ile CLAUDE.md’yi güncellemek için PR’da Claude’u etiketleme | GitHub Actions: /install-github-app uygulamayı ve workflow’u kurar; PR ya da issue yorumunda @claude (dizi /install-github-action diyor) | Model karar verir (Action belirli çalışır, metni model yazar) | /install-github-app; .github/workflows/claude.yml |
| 6 | Plan modunda başla (iki kez Shift+Tab), sonra düzenlemeleri otomatik kabul et | İzin modları: etkileşimli oturumlar auto modda başlar; Shift+Tab auto → default → acceptEdits → plan sırasıyla döner; ya da istemin başına /plan; planı onaylarken sonraki mod seçilir | Planı model belirler; planlama sırasında düzenlemeleri harness engeller | Shift+Tab; /plan; claude --permission-mode plan |
| 7 | .claude/commands/ içinde her iç döngü için bir eğik çizgi komutu | Skills: özel komutlar skill’lerle birleşti; .claude/commands/*.md çalışmaya devam eder; yeni biçim .claude/skills/<name>/SKILL.md, isteğe bağlı disable-model-invocation | Model karar verir (kimin çağırabileceği ayarlanabilir) | .claude/skills/verify-app/SKILL.md |
| 8 | code-simplifier ve verify-app alt ajanları | Sub-agents: name, description, tools, model ve daha fazlasıyla .claude/agents/<name>.md; tools listesini harness zorlar | Karma: devretmeyi model belirler, araç kapsamı zorlanır | .claude/agents/code-simplifier.md |
| 9 | PostToolUse hook kodu biçimlendirir | Hooks ve best practices sayfaları: matcher Edit|Write, komut .tool_input.file_path okur; isteğe bağlı onFailure block | Harness zorlar | .claude/settings.json hooks.PostToolUse |
| 10 | --dangerously-skip-permissions yok; /permissions önceden onaylar, paylaşılan settings.json | Permissions: allow, ask ve deny kuralları; deny her modda geçerli; paylaşılan dosyadaki allow kuralları herkesin güven iletişim kutusunu bekler | Harness zorlar | .claude/settings.json permissions |
| 11 | .mcp.json’da Slack MCP; bq CLI; Sentry | Best practices: CLI varsa onu tercih edin; yoksa claude mcp add --transport http; kullanılmayan sunucuları /mcp içinde kapatın | Araç katmanı | claude mcp add ...; .mcp.json |
| 12 | Uzun görevler: arka plan ajanı, Stop hook ya da ralph-wiggum eklentisi | Hooks: Stop hook 2 ile çıkarak Claude’u işe döndürür, üst üste 8 engelle sınırlı, CLAUDE_CODE_STOP_HOOK_BLOCK_CAP ayarlanabilir; /goal yerleşik alternatif; ralph-wiggum eklentisi kontrol ettiğimiz depo yolunda bulunamadı | Stop hook zorlanır; /goal bir modelce değerlendirilir | hooks.Stop; /goal <koşul> |
| 13 | Claude’a doğrulama yolu ver; kalite ×2–3; Chrome uzantısı arayüzü test eder | Best practices: pass ya da fail döndüren bir şey verin; kanıt isteyin (komut ve çıktı ya da ekran görüntüsü); Chrome: claude --chrome, /login ile giriş yapılmış doğrudan Pro, Max, Ultra, Team ya da Enterprise planı gerekir | Kontrol belirlidir; Claude’un ona güvenmesi model kararıdır; Stop hook zorlayabilir | scripts/verify.sh; claude --chrome; /verify |
Claude Code belgeleri: Best practices · Claude Code belgeleri: Hooks referansı · Claude Code belgeleri: alt ajanlar · Claude Code belgeleri: Memory ve CLAUDE.md · Claude Code belgeleri: Skills (slash-commands buraya yönlenir) · Claude Code belgeleri: Chrome entegrasyonu · Claude Code belgeleri: izin modları · Claude Code belgeleri: izin kuralları · Claude Code belgeleri: bulut oturumları (--cloud ve --teleport) · Claude Code belgeleri: GitHub Actions · Claude Code belgeleri: terminal yapılandırması ve bildirimler · Claude Code belgeleri: /goal · Claude Code belgeleri: model yapılandırması
Üç satır diziyle uyuşmuyor ve akılda tutulmaya değer. Birincisi, komut artık /install-github-action değil /install-github-app. İkincisi, yerel oturumun ampersan ile web’e devrinin bulut oturumları sayfasında karşılığı yok; sayfa CLI devrinin tek yönlü olduğunu söylüyor: --teleport bulut oturumunu terminalinize çeker, --cloud yeni bir bulut görevi oluşturur ve yerel oturumu buluta yalnızca masaüstü uygulaması gönderebilir. Üçüncüsü, baktığımızda anthropics/claude-code deposunun plugins dizininde yalnızca bir README vardı; ralph-wiggum eklentisinin yeri doğrulanmadı, bu yazı onu dizide anlatıldığı şekliyle anıyor ve kurulum adımı vermiyor.
Claude Code belgeleri: bulut oturumları (--cloud ve --teleport) · Claude Code belgeleri: GitHub Actions
3. Doğrulama döngüsü: plan, uygulama, doğrulama, kanıt, inceleme
6, 9, 12 ve 13. maddeleri birleştirince tek bir döngü çıkıyor. Plan modu neyin yapılacağını ve neyin bitmiş sayılacağını belirliyor. Onaydan sonra Claude acceptEdits ya da auto modda uyguluyor. Her düzenlemeyi PostToolUse hook biçimlendiriyor. Claude bitirmeye çalıştığında Stop hook typecheck ya da testleri çalıştırıyor ve başarısızlıkta derleyici çıktısını geri vererek Claude’un çalışmaya devam etmesini sağlıyor. Geçtiğinde Claude kanıt sunuyor: çalıştırdığı komutlar, çıkış kodları ve çıktıları ya da bir tarayıcı ekran görüntüsü. Son olarak kodu yazmamış biri inceliyor: /code-review ile başlatılan taze bir alt ajan ya da başka bir mühendis.
Hangi adımlar belirli? Biçimlendirme hook’u ve Stop hook harness tarafından çalıştırılır; test ve typecheck sonuçları modelin belleğinden değil derleyici ve test çalıştırıcısından gelir; plan modunun kaynak dosyaları düzenlemeyi reddetmesi de harness tarafından zorlanır. Planın sağlam olup olmadığı, kanıtın yeterli olup olmadığı ve inceleme bulgularının kabulü ise modelin ya da bir kişinin yargısı olarak kalır. Döngüyü tasarlarken asla atlanmaması gereken birkaç adımı belirli tarafa koyun, gerisini modele bırakın.
Best practices sayfası kanıt konusunda nettir: tüm testler geçti cümlesi neredeyse hiçbir bilgi taşımaz; komutu ve çıktısını okuyun, izlemediğiniz bir oturumda elinizdeki tek kanıt budur. 8. bölümdeki verify.sh betiği bu adım için var: her kontrolün çıkış kodunu, süresini ve günlük yolunu zaman damgalı bir Markdown dosyasına yazar; böylece Claude, Stop hook ve inceleyen kişi aynı belgeye atıf yapar.
- Plan modu: kodu oku, öner, bitmiş tanımında uzlaş (Shift+Tab ya da /plan)
- Planı onayla → acceptEdits ya da auto’ya geç; Claude uygular
- Her Edit/Write sonrası PostToolUse hook dosyayı biçimlendirir (harness zorlar)
- Claude CLAUDE.md’deki kontrol komutunu çalıştırır, çıktıyı okur, geçene kadar düzeltir
- Claude durmaya çalışır → Stop hook tsc ya da verify.sh çalıştırır; çıkış 2 onu geri gönderir (harness zorlar, üst üste 8 sınırı)
- Geçti → kanıt: komutlar, çıkış kodları, günlük yolları, ekran görüntüleri (scripts/verify.sh .claude/evidence/ yazar)
- Bağımsız inceleme: taze bir /code-review alt ajanı ya da başka bir mühendis kanıtı planla karşılaştırır
- Birleştirmeyi bir kişi onaylar; dal koruması son belirli kapıdır
Claude Code belgeleri: Best practices · Claude Code belgeleri: Hooks referansı · Claude Code belgeleri: izin modları
4. CLAUDE.md: ortak, hatalardan büyüyen, kısa
4. madde memory ve best practices sayfalarında iki sınırla yaşıyor. Uzunluk: memory sayfası CLAUDE.md dosyası başına 200 satırın altını hedefliyor, çünkü uzun dosyalar bağlam tüketir ve uyumu düşürür; ağacın yalnızca bir kısmı için önemli kurallar, paths: front matter’lı .claude/rules/ dosyalarına taşınır ve yalnızca Claude eşleşen dosyalara dokunduğunda yüklenir. İçerik: yalnızca Claude’un depodan okuyamayacağını yazın; bir toplantıda alınan karar, tek bir kişinin aklındaki dağıtım süreci, entegrasyon testlerinin gerektirdiği ortam değişkeni ve iki kez düzelttiğiniz her şey. Mimari ve dizin yapısı oraya ait değil; Claude depoyu kendisi okur.
Claude Code belgeleri: Best practices · Claude Code belgeleri: Memory ve CLAUDE.md
Claude her tökezlediğinde bir satır eklemek hâlâ işe yarıyor ama belgeler tavanı açıkça çiziyor: CLAUDE.md belirsizdir ve bir satır ne kadar sert yazılırsa yazılsın ona uymak Claude’un kararıdır. Kalın yazı ve IMPORTANT’tan sonra bir kural hâlâ kaçırılıyorsa ya dosya onu gömecek kadar uzundur ya da kural istisna kabul etmez; o zaman yeri bir hook ya da deny kuralıdır. Aşağıdaki örnek bu kurallara uyuyor. Son bloğu, bitmiş tanımı, 3. bölümün kanıt gereğine hizmet eder; Claude’un kanıt gösterme olasılığını yükseltir, zorlama ise Stop hook’ta yaşar.
# Commands
- Install: pnpm install
- Typecheck: pnpm tsc --noEmit
- Run one test file: pnpm vitest run path/to/file.test.ts
- Full verification with evidence file: bash scripts/verify.sh
# Conventions
- Use the error helpers in src/lib/errors.ts; never throw raw strings
- src/legacy/ is still live, but do not copy its patterns into new code
# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
- src/gen/ is generated (2026-10-30: edited by hand once); run pnpm gen instead
# Definition of done
- Before saying a task is complete, show the command you ran and its output,
or the screenshot. "Tests pass" without output does not count.Dosyayı üç komut ayakta tutar. /init kod tabanından bir taslak çıkarır ve mevcut dosyanın üzerine yazmak yerine iyileştirme önerir; /doctor Claude’un koddan çıkarabileceği her şeyi kesmeyi önerir; /doctor prompt-audit eski modeller için yazılmış, artık var olmayan dosyaları gösteren ya da birbiriyle çelişen talimatları işaretler. Oturumda /context all dosyanın yüklendiğini doğrular. 5. madde, PR incelemesi sırasında Claude’un CLAUDE.md’yi düzeltmesi, GitHub Action’a dayanır: güncel kurulum komutu /install-github-app GitHub App’i kurar, kimlik doğrulama sırrını kaydeder, workflow dosyalarıyla bir dal gönderir ve bir pull request açar; birleştirildikten sonra issue ya da PR yorumunda @claude yazmak onu tetikler. Bu adımın çıktısı modelin yazdığı metindir; CLAUDE.md’ye girip girmeyeceği hâlâ bir insan inceleme kararıdır.
Claude Code belgeleri: Best practices · Claude Code belgeleri: Memory ve CLAUDE.md · Claude Code belgeleri: GitHub Actions
5. Plan modu, izin kuralları ve tek settings.json’da iki hook
6. madde plan modu için iki kez Shift+Tab diyor; bu, Ocak 2026’daki varsayılan manuel moddan sayılan tuş sayısıydı. İzin modları sayfası artık Claude Code v2.1.283’ten itibaren etkileşimli terminal ve VS Code oturumlarının auto modda başladığını, riskli eylemleri sizin yerinize bir sınıflandırıcı modelin incelediğini söylüyor; auto’dan Shift+Tab default (manuel), sonra acceptEdits, sonra plan’a geçer. Tek bir istemin başına /plan koymak ya da claude --permission-mode plan ile başlamak daha hızlı. Plan modunda Claude dosyaları okur, keşif komutları çalıştırır ve plan yazar ama kaynak düzenleyemez; bunu harness garanti eder. Planı onaylarken sonraki modu siz seçersiniz; dizideki düzenlemeleri otomatik kabule geçiş budur.
10. madde permissions sayfasında olduğu gibi duruyor: allow kuralları önceden onaylar, ask kuralları soru sormaya zorlar, deny kuralları auto ve bypassPermissions dahil her modda geçerlidir. İki kenar önemli. Read(./.env) üzerindeki bir deny, Claude Code yaygın dosya okuma komutlarını tanıdığı için cat .env’i de durdurur ama dosyayı açan bir betiği durdurmaz; WebFetch için bir alan adı deny’ı, sandbox açık değilse curl’e hiçbir şey yapmaz. Best practices, auto modun sınıflandırıcısının sert bir kural değil bir yargı olduğunu ekler; dolayısıyla asla kurallarınız deny kurallarına ya da hook’lara aittir. Dizinin --dangerously-skip-permissions’tan kaçınması güncel belgelerle örtüşüyor; belgeler bypassPermissions’ı tek kullanımlık konteynerlere ayırıyor.
Claude Code belgeleri: Best practices · Claude Code belgeleri: izin kuralları · Claude Code belgeleri: izin modları
{
"permissions": {
"allow": [
"Bash(pnpm tsc --noEmit)",
"Bash(pnpm vitest run *)",
"Bash(bash scripts/verify.sh)",
"Bash(git status *)",
"Bash(git diff *)"
],
"ask": ["Bash(git push *)"],
"deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
},
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "npx prettier --write --ignore-unknown \"$(jq -r '.tool_input.file_path')\""
}
]
}
],
"Stop": [
{
"hooks": [
{ "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
]
}
]
}
}İki hook 9. ve 12. maddeler. PostToolUse matcher’ı Edit|Write; komut stdin’deki JSON’dan jq ile .tool_input.file_path alıp Prettier’e verir. Belgeler, bir Bash komutu ya da dış süreç tarafından yeniden yazılan dosyanın bu hook’u tetiklemediğini, bunun için FileChanged olayının bulunduğunu not eder. Stop hook sözleşmesi, durmayı engellemek için çıkış kodu 2’dir; stderr, bitirememe nedeni olarak Claude’a döner, bu yüzden örnek derleyici çıktısını oraya yönlendirir. Hooks sayfası iki emniyet supabı ekler: arada araç çağrısı olmadan üst üste sekiz Stop engelinden sonra Claude Code bir sonraki engeli geçersiz kılar ve turu bitirir (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP sınırı yükseltir); girdideki stop_hook_active alanı tur zaten bir hook devamıysa true olur, betikler asla sağlanamayacak bir koşulda dönmemek için bunu okumalıdır.
Claude Code belgeleri: Hooks referansı · Claude Code belgeleri: Best practices
Ya hook’un kendisi bozulursa? Varsayılan olarak başarısız olan ya da zaman aşımına uğrayan hook eylemi geçirir ve bir hata notu bırakır. Bir güvenlik hook’u için onFailure: block ayarlayabilirsiniz; böylece başlayamayan hook bile eylemi engeller. Ancak hooks sayfası, Stop olaylarında engelin Claude’u işe geri gönderdiğini ve Claude’un çalışmayan bir hook’u onaramayacağını uyarır; bu yüzden örnek Stop hook’a bunu koymuyor. Best practices hatırlatmasını da aklınızda tutun: zorlanan küme küçük kalmalı; kırk kurala vardığınızda çoğu muhtemelen modelin kendi tartabileceği tercihlerdir.
Claude Code belgeleri: Hooks referansı · Claude Code belgeleri: Best practices
| Dosya ya da konum | Kime uygulanır | Ne konur | Not |
|---|---|---|---|
| ~/.claude/settings.json | Siz, bu makinedeki her proje | Tema, varsayılan model, kişisel allow kuralları, autoMode yapılandırması | autoMode bloğu yalnızca burada çalışır; proje ayarlarında sınıflandırıcı onu yok sayar |
| .claude/settings.local.json | Siz, yalnızca bu proje | Kişisel geçersiz kılmalar; Evet, bir daha sorma buraya kaydedilir | Claude Code dosyayı oluştururken git dışlamalarına ekler; elle oluşturduysanız .gitignore’a kendiniz ekleyin |
| .claude/settings.json | Klasördeki herkes | Ekip allow/ask/deny, hook’lar, eklentiler, ortam değişkenleri | Deny hemen uygulanır; allow kuralları ve hook’lar herkesin güven iletişim kutusunu bekler |
| Yönetilen ayarlar (managed-settings.json ve diğerleri) | Kuruluşun dağıttığı herkes | Güvenlik politikası, uyumluluk | Hiçbir kişisel dosya geçersiz kılamaz; güvenlik ekibinin politikası için tek yer |
| CLAUDE.md | Klasördeki herkes | Komutlar, kurallar, tuzaklar, ekip kararları | Belirsiz; 200 satırın altında |
| CLAUDE.local.md | Siz, yalnızca bu proje | Tercihler, yerel URL’ler, test verisi | .gitignore’da; CLAUDE.md ile birlikte yüklenir |
| .claude/rules/*.md | Herkes, ama yalnızca eşleşen yollarda | Tek bir dizin ya da dosya türü için kurallar | paths: front matter yüklemeyi denetler |
| .claude/skills/, .claude/agents/ | Herkes | Çok adımlı prosedürler, alt ajan tanımları | Skill disable-model-invocation ayarlayabilir; alt ajanın tools listesini harness zorlar |
Claude Code belgeleri: ayar dosyaları ve öncelik · Claude Code belgeleri: Best practices · Claude Code belgeleri: Memory ve CLAUDE.md · Claude Code belgeleri: alt ajanlar · Claude Code belgeleri: Skills (slash-commands buraya yönlenir)
6. Eğik çizgi komutları skill oldu; alt ajanlar front matter kazandı
7. madde komutları .claude/commands/ içinde tutuyor. 2026-11-08’de slash-commands belge adresi skills sayfasına yönleniyor ve sayfa, özel komutların skill’lerle birleştiğini söyleyerek açılıyor: .claude/commands/deploy.md ve .claude/skills/deploy/SKILL.md ikisi de /deploy oluşturur, eski dosyalar çalışmaya devam eder, yeni biçim destek dosyaları için bir dizin, front matter ve kimin çağıracağı denetimini ekler. Yan etkisi olan ya da uzun süren bir iç döngü iş akışı için belgeler disable-model-invocation: true öneriyor; böylece yalnızca siz /verify-app yazdığınızda çalışır ve Claude kendi başına başlatamaz. $ARGUMENTS, komuttan sonra yazdığınız şeyle değiştirilir.
Claude Code belgeleri: Skills (slash-commands buraya yönlenir)
Aşağıdaki verify-app, 8. maddede uçtan uca test talimatlarını tutan alt ajana karşılık geliyor; ama biz onu alt ajan değil skill olarak yazdık, çünkü mevcut oturumda tarayıcıyı sürmesi ve kanıtı geri vermesi gerekiyor. allowed-tools yalnızca onu çağıran turda geçerlidir ve verify.sh ile kanıt dosyasını okumayı önceden onaylar. İçerik Claude’dan her adımda ne yaptığını, ne beklediğini ve ne gördüğünü kaydetmesini ister ve kanıt olmadan çalışıyor demeyi yasaklar. Skills sayfasının, bir değişikliği doğrulamak için uygulamanızı derleyip çalıştıran yerleşik bir /verify listelediğini unutmayın; kayıtlı tarif yoksa işe yarayan adımları .claude/skills/verify/SKILL.md’ye yazar ve depo kökündeki kayıtlı skill yerleşik olanın yerini alır; bu yüzden kendi skill’inize yalın verify adını vermeyin.
Claude Code belgeleri: Skills (slash-commands buraya yönlenir)
---
name: verify-app
description: End-to-end check of the web app after a change. Runs the evidence script, drives the changed flow in the browser and reports what was seen. Use before opening a PR.
disable-model-invocation: true
argument-hint: [flow-name]
allowed-tools: Bash(bash scripts/verify.sh) Read
---
1. Run `bash scripts/verify.sh`, then read .claude/evidence/latest.md.
If any step shows a non-zero exit code, stop and report it.
2. Start the app with the command from CLAUDE.md and open it in the
connected browser (http://localhost:3000).
3. Exercise the flow named in $ARGUMENTS: the happy path, one invalid
input, one empty state.
4. For each step write down what you did, what you expected, what you saw.
Take a screenshot of the final state.
5. Report: commands with exit codes, the evidence file path, screenshot
paths, and every mismatch against the plan. Never write "works" without
attaching the evidence.Alt ajanlar, proje için .claude/agents/ altında (git’e alınır) ya da kendiniz için ~/.claude/agents/ altında birer Markdown dosyasıdır. Güncel sub-agents sayfası front matter’ı listeler: name ve description zorunlu; tools, disallowedTools, model, permissionMode, maxTurns, skills, memory, isolation ve diğerleri isteğe bağlı. tools alanı belirlidir: Read, Grep, Glob verilen bir alt ajan düzenleyemeyen bir incelemecidir ve bu sınırı bir istem rica etmez, Claude Code zorlar. Dizideki code-simplifier dosya değiştirip kontrol çalıştırmalı; bu yüzden örnek Edit ve Bash verir; model: inherit ana oturumun modelini korur. Ana oturumun ona devredip devretmeyeceğine Claude description’dan karar verir; istemde adını da verebilirsiniz.
---
name: code-simplifier
description: Simplifies code that was just written without changing behaviour. Use after the implementation passes its tests and before review.
tools: Read, Grep, Glob, Edit, Bash
model: inherit
---
You are cleaning up a diff you did not write. Work only on files changed
since the base branch: `git diff --name-only main...HEAD`.
- Remove dead code, duplicated helpers and abstraction layers used once.
- Keep public interfaces and observable behaviour identical. Add no features.
- After each file, run `pnpm tsc --noEmit` and the test file for that module.
- Finish with a table: file, lines before, lines after, commands run and
their exit codes. If a check fails, revert that file and say so.Best practices sayfasından bir maliyet notu: her alt ajan isteği kullanımınıza sayılır ve taze bir alt ajan önce konuşmanızın zaten sahip olduğu bağlamı toplar, bu yüzden daha yavaş olabilir; aynı görevi alt ajana vermek daha akıllı bir yanıt üretmez, yalnızca paralellik, ana konuşmadan uzak tutulan uzun çıktı ve akıl yürütmeyi izlememiş bir çift göz sağlar. Basit işler için model: haiku ayarlayın ve her alt ajan türünün maliyetini /usage ile kontrol edin.
Claude Code belgeleri: Best practices · Claude Code belgeleri: alt ajanlar
7. Doğrulama alana göre değişir: hangi kontrol, hangi kanıt, kim zorlar
13. maddenin özü Chrome uzantısı değil, Claude’a pass ya da fail döndüren bir şey vermek. Best practices sayfası test dosyalarını, bir derlemenin çıkış kodunu, bir linter’ı, çıktıyı bir fixture ile karşılaştıran betiği ve taslağın yanındaki tarayıcı ekran görüntüsünü sayar; depoda bunlardan biri varsa CLAUDE.md’deki en yararlı satırın onu çalıştıran komut olduğunu söyler. Sıkılık dört düzeyde gelir: istemde (Claude ne zaman tatmin olduğuna kendi karar verir), /goal olarak (ayrı bir model her turdan sonra koşulu denetler, uzun arka plan çalışmaları için yararlı), Stop hook olarak (geçene ya da sınıra ulaşana kadar harness zorlar) ve kodu yazmamış biri tarafından (/code-review taze bir alt ajanda).
Claude Code belgeleri: Best practices · Claude Code belgeleri: /goal
| Alan | Kontrol | Kanıt | Kim zorlar |
|---|---|---|---|
| Kütüphane / saf mantık | Birim testleri, typecheck, lint | Komut, çıkış kodu, başarısız vakaların adları | Araç zinciri değerlendirir; Stop hook çalışmayı garanti eder |
| CLI aracı | Beklenen çıktıya karşı tek bash komutu; fixture diff’i | Komut ve stdout/stderr kesiti | Betik çıkış kodu; Stop hook |
| Web arayüzü | Chrome entegrasyonu yerel sayfayı açar, form doldurur, konsolu okur; /verify derler ve çalıştırır | Ekran görüntüleri, konsol hata listesi, adım notları | Tarayıcıyı model sürer; ekran görüntülerini bir kişi okur |
| Mobil uygulama | Dizide anlatıldığı gibi simülatörde çalıştırma; özel belge sayfası bulunamadı | Ekran görüntüleri, derleme günlüğü | Model karar verir; araç zincirinize bağlı |
| Veri / betikler | Sabit girdiyle yeniden çalıştırma, çıktı özeti ya da satır sayısı karşılaştırma | Çıktı özeti, satır sayıları, diff | Betik değerlendirir; verify.sh içinde yaşayabilir |
| Uzun gözetimsiz çalışma | /goal koşulu artı Stop hook artı --max-turns | Kanıt dosyası artı PR açıklaması | /goal’ü model değerlendirir; hook ve tur sınırını harness |
Claude Code belgeleri: Best practices · Claude Code belgeleri: Chrome entegrasyonu · Claude Code belgeleri: Skills (slash-commands buraya yönlenir) · Claude Code belgeleri: /goal
Chrome kendi ön koşul kontrolünü hak ediyor. Güncel Chrome sayfası Chrome, Edge ya da başka bir Chromium tarayıcı ile Claude in Chrome uzantısının 1.0.36 veya üstünü ister; /login ile giriş yapılmış doğrudan bir Anthropic Pro, Max, Ultra, Team ya da Enterprise planı gerekir, çünkü API anahtarı ya da uzun ömürlü token ile entegrasyon kapalı kalır; üçüncü taraf bulut sağlayıcıları desteklenmez; WSL desteklenmez. claude --chrome ile ya da /chrome içinde Enabled by default seçerek başlarsınız; sürekli açık tarayıcı araçlarının bağlam kullanımını artırdığı uyarısıyla. Claude giriş sayfalarında ve CAPTCHA’larda durur ve bunları sizin halletmenizi ister. Dizinin claude.ai/code’daki her değişikliği test etme alışkanlığından kopyalayabileceğiniz şey, Claude’un localhost’taki sayfayı açması, değişen akışı yürümesi, konsol hatalarını okuması ve ekran görüntüsü alması; kopyalayamayacağınız şey diğer ekibin test içeriği.
Her düzeyde kanıt isteyin. Best practices sayfası özünde şunu söylüyor: tüm testler geçti çok az şey anlatır, çıktıyı okumak kontrolü yeniden çalıştırmaktan hızlıdır ve izlemediğiniz bir oturumda elinizdeki tek kanıt budur. Sezgiye aykırı bir inceleme öğüdü de veriyor: incelemeciye stili atlamasını söyleyin, çünkü sorun bulması istenen bir incelemeci her zaman bir şey bulur ve her bulguyu düzeltmek soyutlama katmanları ile olamayacak durumlar için testler yığar.
8. Kanıt betiği: Claude, Stop hook ve incelemeci için tek dosya
Aşağıdaki verify.sh bu yazının kendi örneği; çevrimdışı bash -n’den geçti ve gerçek bir projede çalıştırılmadı. Sırayla typecheck, testler ve derlemeyi çalıştırır; her adımın çıkış kodunu, süresini ve günlük yolunu .claude/evidence/ altında zaman damgalı bir .md adıyla yazar, latest.md’yi en yeni dosyaya yönlendirir ve sonunda dosyanın tamamını stderr’e basar; böylece Stop hook olarak kullanıldığında (bash scripts/verify.sh || exit 2) Claude’un bitirememe nedeni olarak gördüğü şey kanıtın kendisidir. CLAUDE.md örneği ve verify-app skill’i aynı komuta atıf yapar; üçü de tek bir çıktıyı alıntılar.
Claude Code belgeleri: Best practices · Claude Code belgeleri: Hooks referansı
#!/usr/bin/env bash
# scripts/verify.sh - run the project's checks and write an evidence file
# that Claude, a Stop hook and a human reviewer can all quote.
set -u
OUT_DIR=".claude/evidence"; mkdir -p "$OUT_DIR"
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
OUT="$OUT_DIR/$STAMP.md"
status=0
run() { # run <label> <command...>
local label="$1"; shift
local start; start=$(date +%s)
local rc=0
"$@" >"$OUT_DIR/$label.log" 2>&1 || rc=$?
printf -- '- %s: exit %s, %ss, log %s/%s.log\n' \
"$label" "$rc" "$(( $(date +%s) - start ))" "$OUT_DIR" "$label" >>"$OUT"
[ "$rc" -ne 0 ] && status=1
return 0
}
{
echo "# Verification evidence $STAMP"
echo "- commit: $(git rev-parse --short HEAD 2>/dev/null || echo none)"
echo "- changed files: $(git diff --name-only HEAD 2>/dev/null | wc -l | tr -d ' ')"
} >"$OUT"
run typecheck pnpm tsc --noEmit
run tests pnpm vitest run
run build pnpm build
echo "- overall: $([ "$status" -eq 0 ] && echo PASS || echo FAIL)" >>"$OUT"
ln -sfn "$STAMP.md" "$OUT_DIR/latest.md"
cat "$OUT" >&2 # stderr, so "bash scripts/verify.sh || exit 2" works as a Stop hook
exit "$status"Üç ödünleşim. Betiğin tamamını Stop’a bağlamak: Claude her bitirmek istediğinde tüm testleri ve derlemeyi çalıştırmak yavaş olabilir; bu yüzden 5. bölümdeki settings.json Stop’ta yalnızca tsc çalıştırır ve tam betiği skill’e ya da isteme bırakır; takımınız bir iki dakika sürüyorsa tamamını bağlamak da olur. Betik stop_hook_active’i bilerek yok sayar, çünkü her şeyi yeniden hesaplar ve asla sağlanamayacak bir koşulu yoktur; kontrolünüz bir dış hizmete bağlıysa başta stdin’deki JSON’u okuyun ve stop_hook_active true iken başarısızlık tekrarlanıyorsa 0 ile çıkıp sorunu bir kişiye devredin. Kanıt dizinini git’e almak: .gitignore’a ekleyin ve latest.md’yi PR açıklamasına yapıştırın; yoksa her çalışma commit gürültüsüne döner.
Betiği CLAUDE.md ile birleştirirken rolleri ayrı tutun. CLAUDE.md Claude’a komutun var olduğunu söyler ve Claude genellikle bitirince onu çalıştırır; Stop hook tur bitmeden en az bir kez çalışıp geçtiğini garanti eder; kanıt dosyası bir kişinin yeniden çalıştırmadan kontrol etmesini sağlar. Best practices’in CLAUDE.md’deki typecheck satırını yalnızca komutla sınırlı tutmasının nedeni budur: komut model için, zorlama hook için.
9. Ocak ile Kasım arasında ne değişti
1, 2, 3 ve 11. maddeler çoğunlukla ortam ve araç seçimleri ve kopyalamadan önce güncellenmeleri gerekiyor. Thinking açık Opus 4.5 o zaman yazarın tercihiydi; model config sayfası artık çoğu plan ve sağlayıcıda varsayılan olarak medium effort ile Opus 5.5’i listeliyor ve best practices effort’u Claude’un ne kadar düşüneceğinin ana denetimi yapıyor; think hard gibi ifadeler sıradan istem metni. Dizinin akıl yürütmesi, daha az yönlendirme isteyen daha büyük bir modelin sonuçta daha hızlı olduğu, hâlâ geçerli; model adı /model’den gelmeli. Paralel oturumlar için belgeler artık düzenlemelerin çarpışmaması adına oturum başına bir worktree (claude -w feature-x) öneriyor; terminal config sayfası Ghostty, Kitty ve iTerm2’nin masaüstü bildirimi gösterebildiğini, iTerm2’de önce uyarı ayarlarının açılması gerektiğini söylüyor.
Claude Code belgeleri: model yapılandırması · Claude Code belgeleri: Best practices · Claude Code belgeleri: terminal yapılandırması ve bildirimler
| Dizi (2026-01) | Belgeler 2026-11-08 | Ekip için anlamı |
|---|---|---|
| Thinking açık Opus 4.5 | Varsayılan medium effort ile Opus 5.5; /effort ayarlar | CLAUDE.md’ye model adı gömmeyin; istem ifadesi yerine /effort kullanın |
| Plan modu için iki kez Shift+Tab | Oturumlar auto’da başlar; auto’dan üç basış ya da /plan | Belgelerinize /plan yazın |
| Ampersan yerel oturumu web’e devreder | CLI devri tek yönlü: --cloud oluşturur, --teleport geri çeker; masaüstü uygulaması yerel oturumu gönderebilir | Ampersan devri yalnızca dizide; güncel komutları belgeleyin |
| Eğik çizgi komutları için .claude/commands/ | Skill’lerle birleşti; eski dosyalar çalışır; yeni biçim SKILL.md | Yeni iş akışlarını skill olarak yazın ve kimin çağıracağını denetleyin |
| /install-github-action | /install-github-app | Komut yeniden adlandırıldı |
| --dangerously-skip-permissions yok | Hâlâ var; belgeler tek kullanımlık konteynerlerle sınırlıyor | Aynı tutum; deny kuralları o modda da geçerli |
| ralph-wiggum eklentisi | Kontrol ettiğimiz depo yolunda bulunamadı | Diziden kurmayın; önce kaynağı doğrulayın |
| Arka plan ajanı uzun görevleri doğrular | Alt ajanlar varsayılan olarak arka planda çalışır; /goal yerleşik alternatif | Uzun görevlerde /goal ya da Stop hook’u tercih edin |
Claude Code belgeleri: model yapılandırması · Claude Code belgeleri: izin modları · Claude Code belgeleri: bulut oturumları (--cloud ve --teleport) · Claude Code belgeleri: Skills (slash-commands buraya yönlenir) · Claude Code belgeleri: GitHub Actions · Claude Code belgeleri: Hooks referansı · Claude Code belgeleri: alt ajanlar · Claude Code belgeleri: /goal
11. maddenin ilkesi değişmedi: CLI varsa onu tercih edin; gh kurulu ve giriş yapılmışken Claude açıklama gerekmeden pull request açar ve incelemeleri okur. CLI’sı olmayan sistemler için claude mcp add --transport http komutunun ardından bir ad ve sunucu adresiyle MCP kullanın; sunucu sonra /mcp altında görünür. Best practices bir maliyet notu ekler: bağlı sunucular kullanılmasalar bile araç adlarını ve talimatlarını bağlama ekler; ihtiyaç duymadıklarınızı kapatın. Slack yapılandırmasını dizideki gibi .mcp.json ile paylaşmak bununla tutarlı; kimlik bilgilerini dosyada değil ortam değişkenlerinde tutun.
10. Bir haftada ekipte yeniden üretmek: sıra ve kabul
İşi bağımlılığa göre sıralayın ve testlerin doğrulayabileceğiyle başlayın. Sıra, depoda zaten bir test ya da typecheck komutu olduğunu varsayar; yoksa önce pass ya da fail döndüren tek bir komut ekleyin, çünkü sonraki her adım ona dayanır. Her adım etkisinin nasıl doğrulanacağını söyler ve her doğrulama yöntemi güncel belgelerden gelir.
- 1. gün: 4. bölüm şablonuyla CLAUDE.md’yi yalnızca komutlar, kurallar, tuzaklar ve bitmiş tanımıyla yazın; /init taslağı çıkarsın, sonra 200 satırın altına kesin; /context all ile doğrulayın ve /doctor önerilerini okuyun.
- 2. gün: .claude/settings.json’ın permissions kısmını commit edin; her üye klasör için güven iletişim kutusunu kabul etsin, yoksa allow kuralları etkisiz kalır; geçerli kuralları /permissions ile inceleyin ve reddi doğrulamak için Claude’dan .env okumasını isteyin.
- 3. gün: PostToolUse biçimlendirme hook’unu ekleyin; Claude’dan Prettier’in işlediği bir dosyaya kötü girintili bir satır eklemesini isteyin ve kaydedilen dosyanın düzeltilmiş döndüğünü doğrulayın; kayıtlı hook’ları /hooks ile listeleyin.
- 4. gün: scripts/verify.sh ve Stop hook’u ekleyin (önce yalnızca tsc); Claude’dan bir tipi bozan değişiklik isteyin ve derleyici hatalarını alıp durmak yerine çalışmaya devam ettiğini doğrulayın; sekiz engel sınırı görünürse koşulun kendisi yanlıştır.
- 5. gün: verify-app skill’ini ve code-simplifier alt ajanını ekleyin; /verify-app <flow> komutunu bir kez çalıştırıp kanıt dosyasını ve ekran görüntülerini kontrol edin; Claude’dan code-simplifier’ı çağırmasını isteyip raporladığı çıkış kodlarını inceleyin.
- Her hafta: tekrarlanan inceleme düzeltmelerini CLAUDE.md’ye taşıyın (ya da GitHub Action yapsın); ayda bir /doctor prompt-audit çalıştırın; zorlanan küme bir düzine kuralı aşınca hangilerinin aslında tercih olduğunu sorun.
Claude Code belgeleri: Best practices · Claude Code belgeleri: Hooks referansı · Claude Code belgeleri: Memory ve CLAUDE.md · Claude Code belgeleri: Skills (slash-commands buraya yönlenir) · Claude Code belgeleri: izin kuralları
Tek bir kabul ölçütü yeter: Claude’un tamamladığı herhangi bir değişiklikte incelemeci, hiçbir komutu yeniden çalıştırmadan PR açıklamasından ya da kanıt dosyasından neyin çalıştığını, hangi çıkış kodlarıyla ve hangi ekran görüntüleriyle görebilmeli. Bu sağlandığında 13. maddedeki döngü var demektir. İki üç kat kalite iddiası yazarın deneyimidir; çarpanı yeniden üretmenin bir yolu yoktu ve denemedik.
Doğrulamadıklarımız: Claude Code çalıştırmadık, bu yüzden sekiz engellik Stop sınırını, PostToolUse tetiklenme anını ve Chrome entegrasyonunu pratikte gözlemlemedik; ralph-wiggum eklentisinin güncel yerini doğrulamadık; yerel oturumun ampersan ile web’e devrinin güncel belgelerde karşılığı yok ve hâlâ çalışıp çalışmadığını söyleyemiyoruz; görüntülenme sayıları 2026-11-08 okumalarıdır; iki üç kat kalite artışı yazarın kişisel deneyimidir ve yeniden üretilmedi. Bu yazı Anthropic’in herkese açık belgelerini ve bir mühendisin herkese açık dizisini inceler; bu site Anthropic ile bağlantılı değildir. Aşağıdaki ilgili yazılar gözetimsiz çalışma sınırlarını, hesap e-postasının User-Agent’a yazılması olayını ve araştırmacı kullanım raporunu kapsar.