"Claude Code kullanıyorum ancak ölçek büyüdükçe bağlam taşması oluyor ve doğruluk düşüyor."
"Sonunda, yapay zekaya düzeltme talimatları veren kendi ellerim en büyük darboğaz haline geldi."
Birçok kişi muhtemelen bu noktada takılıp kalıyor. Ben de başlangıçta aynıydım, kodu, testleri ve tasarım tartışmalarını tek bir oturuma tıkıştırıyor, geçmiş büyüdükçe Claude'un doğruluğunun düşüşünü izliyordum.
Son zamanlarda fark ettiğim şey, Claude Code'un resmi olarak birden fazla oturumu paralel çalıştırmak için üç mekanizma sağladığı.
Ayrıca, bu üçü benzer ancak farklıdır; karıştırmak kazalara yol açabilir. Tersine, onları rollere göre ayırırsanız, kendiniz tek satır kod yazmadan "komuta eden tarafa" geçebilirsiniz.
Bugün, bu üç mekanizmayı ve resmi dokümantasyondaki birincil bilgileri kontrol ederken rol sınırlarını düzeltmenin doğru yolunu düzenleyeceğim.
Spesifik olarak, Komut, Uygulama ve Kalite olmak üzere üç katmana yerleştirilmiş 8 oturumlu bir yapılandırmaya ayıracağım.
Bonus olarak, "CLAUDE.md'ye rol kimlikleri yazarak geçiş yapmak" veya "belleği SQLite ile paylaşmak" gibi yaygın açıklamaların neden resmi mekanizmadan biraz uzak olduğunu açıklamak için birincil bilgileri kullanacağım.
Ben tatsuki (@nobel_824).
Küçük ve orta ölçekli işletmeler için yapay zeka kullanımını destekliyor, Claude / Codex'in iş süreçlerine entegrasyonuna yardımcı oluyor ve aynı zamanda tüm gün Claude Code çalıştırıyorum. Paralel işlem, hem iş hem de kişisel projelerimde her gün dokunduğum bir alan.
İlgili Makale: Vibe Coding'e Giriş: Kodlayıcı Olmayanların Claude ile Uygulama Oluşturması İçin 6 Adım. Hafta Sonu Şirket İçi Üretim Çağı
https://note.com/nobel/n/n8192ec07d689
1. "Her Şeyi Tek Bir Oturuma Tıkıştırmanın" Neden Başarısız Olduğu
İlk tuzak, tek bir oturumu çok fazla bilgiyle aşırı yüklemektir. Claude modeli ne kadar akıllı olursa olsun, yapısal sınırlara takılır.
Spesifik olarak, şu üç sorunla karşılaşırsınız:
- Bağlam Kirlenmesi: Uygulama kodu, testler, hata ayıklama geçmişi ve tasarım tartışmaları aynı bağlamda karıştığında, muhakeme temeli bulanıklaşır ve doğruluk düşer.
- Talimat Çatışması: "Hız öncelikli uygula" ile "güvenlik konusunda katı ol" aynı yerde bulunuyorsa, kararlar yarım kalır.
- Token Şişkinliği: Her seferinde devasa bir geçmişi yüklemek hem zaman hem de maliyet israfıdır.
Çözüm, "tek bir komutan olup özelleşmiş Claude'ları sıralamak" fikridir. Bir CTO'nun bir Teknik Lider ve Bir Backend Liderine sahip olmasına benzer, ancak önemli olan havası değil, resmi Claude Code mekanizmalarını doğru kullanmaktır.
Bugün atabileceğiniz bir adım: Mevcut oturumunuzu düşünün ve "uygulama", "araştırma" ve "inceleme"nin aynı bağlamda bir arada bulunup bulunmadığını kontrol edin. Eğer öyleyse, bu onları bölmek için başlangıç noktanızdır.
2. Resmi Olarak Sağlanan "Üç Paralel Mekanizmayı" Düzeltmek
Bu makalenin özü. Claude Code'un paralellik için üç mekanizması vardır ve her birinin farklı bir kapsamı vardır.
Birincisi alt temsilci (ana konuşmadan ayrı bir bağlamda çalışan yardımcı bir AI). Kendi bağlam penceresini, özel sistem istemini ve sınırlı araç izinlerini kullanarak araştırma veya incelemeler gibi yan görevleri yürütür ve sonuçların yalnızca bir özetini ana oturuma döndürür. Kilit nokta, alt temsilcilerin aynı oturum içinde çalışması, yalnızca ana oturuma rapor vermesi ve alt temsilcilerin birbirleriyle konuşmamasıdır (Resmi Dokümanlar).
İkincisi, temsilci ekipleri (birden çok Claude Code oturumunun bir ekip olarak işbirliği yaptığı bir mekanizma). Bir oturum ekip lideri olur ve ekip arkadaşlarını oluşturur, paylaşılan bir görev listesi ve posta kutusu aracılığıyla işbirliği yapar. Alt temsilcilerin aksine, ekip arkadaşları birbirlerine doğrudan mesaj gönderebilir. Bu deneysel bir özelliktir ve varsayılan olarak devre dışıdır. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 ayarını yapmanız ve Claude Code v2.1.32 veya sonraki bir sürümü kullanmanız gerekir (Resmi Dokümanlar).
Üçüncüsü git worktree (aynı depodan birden çok çalışma dizinine izin veren bir Git özelliği). claude --worktree feature-auth ile başlatarak, Claude farklı bir dalda/dizinde izole bir ortamda başlar. Farklı bir terminalde başka bir tane çalıştırırsanız, birbirlerinin dosyalarına müdahale etmeden paralel olarak çalışabilirler (Resmi Dokümanlar). Masaüstü uygulamasını kullanırken, her yeni oturum için otomatik olarak bir worktree oluşturulur.
İşte üçünü karşılaştıran bir tablo:
Worktree'in dosya izolasyonunu, alt temsilciler ve temsilci ekiplerinin ise işin koordinasyonunu ele aldığını hatırlarsanız kafanız karışmaz.
Bugün atabileceğiniz bir adım: İlk olarak, izole bir oturum başlatma hissini yakalamak için claude --worktree bugfix-test yazmayı deneyin. Değişiklikleri yaptıktan sonra bitirdiğinizde, worktree'i koruyup korumamayı veya silmeyi soracaktır.
3. Pratik: "3 Katmanlı Yapıda" 8 Oturum Dağıtmak
Bu üç mekanizma 8 oturuma nasıl dönüşüyor? Komut, Yürütme ve Kalite katmanlarına bölünmüş bir düzen kullanıyorum.
Komut/Tasarım Katmanı (2 Oturum)
- Oturum 1 PM (Proje Yöneticisi): Genel ilerleme yönetimi, görev dağılımı, insanlara raporlama.
- Oturum 2 Mimar: Teknik tutarlılığa ve dizin yapısına karar verir. Kod yazmadan tasarımlar üretmek için plan onayı gerektirir.
Yürütme/Uygulama Katmanı (4 Oturum)
- Oturum 3 Frontend: Bileşen oluşturma, UI ayarlamaları.
- Oturum 4 Backend: Uç nokta uygulaması, sorgu optimizasyonu.
- Oturum 5 Altyapı/DevOps: Docker, CI/CD bakımı.
- Oturum 6 Güvenlik: Güvenlik açığı kontrolleri, kimlik doğrulamayı sağlamlaştırma.
Kalite/Bakım Katmanı (2 Oturum)
- Oturum 7 QA/İnceleyen: PR incelemeleri, uç durumlara işaret etme.
- Oturum 8 Teknik Yazar: README, API dokümantasyon bakımı.
Bu düzen için üç ipucu: Dört uygulama katmanı oturumunu worktree'ler ile izole edin, böylece birbirlerinin dosyalarına müdahale etmezler. Kalite katmanı için rolleri alt temsilci tanımları veya temsilci ekibi ekip arkadaşları olarak belirleyin. Ve her oturumun paylaşılan Markdown dosyaları (tasarım notları veya inceleme sonuçları) aracılığıyla bilgi aktarmasını sağlayın. Mimar tasarımı günceller, uygulama katmanı buna göre hareket eder ve İnceleyen sonuçları geri yazar. İnsanların yalnızca bu dosya güncellemeleriyle tetiklenen her oturuma talimat vermesi gerekir.
Bir not: Bir temsilci ekibi için resmi kılavuz 3–5 kişidir, bu nedenle 8 kişiyi aynı anda tek bir ekibe tıkıştırmayın (Resmi Dokümanlar). Worktree ile izole edilmiş oturumları, gerektiğinde 3–5 kişilik bir temsilci ekibi ve alt temsilcilerle birleştirerek toplam 8 işçiye ulaşmak daha güvenlidir.
Bugün atabileceğiniz bir adım: Yukarıdaki 8 rolden mevcut projenizde bölünmesi kolay görünen ikisini seçin. Çoğu durumda, Mimar ve İnceleyen ilk bölünme noktalarıdır.
4. Rol Sınırlarını "CLAUDE.md" ile Değil, "Alt Temsilci Tanımlarıyla" Belirleyin
Paralel işlemle ilgili yaygın bir yanlış anlaşılmayı düzelteyim. "CLAUDE.md'ye roller (ID: arch, ID: dev-main...) yazın ve başlangıçta kişilikleri değiştirin" gibi açıklamalar görebilirsiniz, ancak bu mekanizma aslında mevcut değildir.
CLAUDE.md, Claude Code'un başlangıçta okuduğu paylaşılan bir talimat dosyasıdır. Ancak, resmi dokümanlar CLAUDE.md'nin "bağlam olduğunu, zorunlu bir ayar olmadığını" açıkça belirtir. Sistem isteminden sonra bir kullanıcı mesajı olarak iletildiğinden, sıkı uyum garanti edilmez. Bir şeyi kesinlikle durdurmak istiyorsanız, hook'lar kullanmalısınız (Resmi Dokümanlar). Bunu mutlak bir "anayasa"dan ziyade güçlü bir tavsiye olarak düşünün.
Peki rolleri nerede sabitlersiniz? Cevap alt temsilci tanımlarıdır. .claude/agents/ altına ön bölümde bir ad, açıklama, mevcut araçlar ve model içeren bir dosya yerleştirerek, yeniden kullanılabilir bir uzmanı tamamlamış olursunuz. İşte minimal bir örnek:
name: security-reviewer
description: Kodu kimlik doğrulama, girdi doğrulama ve oturum yönetimi açısından eleştirel bir şekilde denetler.
tools: Read, Grep, Bash
model: sonnet
Kıdemli bir güvenlik incelemecisisiniz. Token işleme, oturum yönetimi ve girdi doğrulamaya odaklanın ve bulguları ciddiyet seviyeleriyle raporlayın.
Ayrıca, bu tanımlar temsilci ekiplerinde ekip arkadaşları olarak isimle çağrılabilir. "auth modülünü denetlemek için security-reviewer temsilci türünde bir ekip arkadaşı ayarla" derseniz, bu tanımdaki araçları ve modeli devralan bir üye haline gelir (Resmi Dokümanlar). Tasarım, bir rolü bir kez alt temsilci tanımı olarak yazmanıza ve onu hem bir alt temsilci hem de bir ekip üyesi olarak yeniden kullanmanıza olanak tanır.
Denemek için istem örneği (Claude'a bir rol tanımı oluşturma):
.claude/agents/ dizinine yerleştirilecek bir alt temsilci tanımı oluştur.
Rol, "uygulama kodundaki performans sorunlarına ve N+1 sorgularına işaret eden bir incelemecidir."
Ön bölüme name / description / tools / model ekleyin
ve gövdeyi kıdemli bir mühendis kişiliğinde yazın.
5. Doğruluğu Artırmak İçin Temsilci Ekipleriyle Bir "Mimar-İnceleyen" Takımı Oluşturmak
Paralel işlemde oldukça etkili bir yapılandırma, bir "yaratıcı" ve bir "şüpheci"yi ayrı ayrı kurmaktır. Bu sadece teori değil; resmi dokümantasyon gerçek dünya örnekleri sağlar.
Resmi "Paralel Kod İncelemesi" örneğinde, bir PR için güvenlik, performans ve test kapsamı için üç ekip arkadaşı ayarlanır, her biri farklı bir perspektiften bakarken lider sonuçları birleştirir. Ayrıca, "Rekabet Eden Hipotezler" örneğinde, bir hata için beş ekip arkadaşına farklı hipotezler atanır ve birbirlerinin teorilerini tartışıp çürütmeleri sağlanır, hayatta kalan teori kök neden olarak kabul edilir (Resmi Dokümanlar). Tek bir araştırmacı ilk teoriye çekilme eğiliminde olduğundan, bu yaklaşım doğruluğu artırmak için kasıtlı olarak çatışma yaratır.
Ayrıca, Mimar'ın resmi özellikleri kullanarak "kod yazmasına izin verilmediği" bir işlem de uygulayabilirsiniz. Bir ekip arkadaşı için plan onayı gerektirerek, ekip arkadaşı salt okunur bir plan modunda kalır ve lider onaylayana kadar yalnızca tasarımlar üretir. Onay kriterleri liderin isteminde yazılabilir, örneğin "yalnızca test kapsamı içeren planları onayla" gibi.
Denemek için istem örneği (tek seferde bir çatışma yapısı kurma):
PR #142'yi incelemek için bir temsilci ekibi oluştur. Üç ekip arkadaşı ayarla:
biri güvenlik, biri performans ve biri test kapsamı için.
Bağımsız olarak incelemelerini ve bulguları ciddiyetle çıktılamalarını sağla, ardından sonunda birleştir.
İki görüntüleme modu vardır: in-process (tüm ekip arkadaşları aynı terminalde çalışır, Shift+Down ile döngü) ve split panes (her ekip arkadaşı ayrı bir bölmede; tmux veya iTerm2 gerektirir). Ekstra kurulum gerektirmediği için in-process ile başlamak daha kolaydır.
6. Belleği "SQLite" ile Değil, Resmi Otomatik Bellek (Markdown) ile Paylaşın
Birden çok oturum çalıştırırken, bir sonraki engel "belleği oturumlar arasında paylaşmaktır." "Etiketli belleği SQLite'da depolamak ve dinamik olarak enjekte etmek" gibi ileri düzey teknikler bazen tanıtılsa da, bu standart bir Claude Code özelliği değildir. MCP (Model Context Protocol) aracılığıyla bir DB oluşturursanız mümkündür, ancak bunu resmi olarak sağlanan bellek mekanizmasından ayırmalısınız.
Resmi otomatik bellek, markdown dosyalarıyla çalışır. ~/.claude/projects/<proje>/memory/ içinde, MEMORY.md (dizin) ve debugging.md gibi konuya özel dosyalar bulunur ve Claude çalışırken bunlara yazar. Yükleme kuralları açıktır: her oturum MEMORY.md'nin ilk 200 satırını veya 25KB'ını okur ve Claude yalnızca gerektiğinde konuya özel dosyaları okumaya gider. Bu, Claude Code v2.1.59'dan itibaren kullanılabilir, depo başına kaydedilir (böylece worktree'ler arasında paylaşılır) ve yerel olarak depolanır (Resmi Dokümanlar).
Bu tasarımın güzelliği, "dizini her zaman yükleyip ayrıntıları yalnızca gerektiğinde getirerek" bağlam penceresini temiz tutabilmenizdir. Binlerce küçük kural olsa bile, dizin şişmediği sürece bağlam her seferinde kirlenmez.
Sıralama açısından, özel bir SQLite çözümü oluşturmaya çalışmadan önce resmi markdown tabanlı otomatik belleği sonuna kadar kullanın.
Bugün atabileceğiniz bir adım: Bir oturum sırasında /memory yazmak, o anda yüklü olan CLAUDE.md ve otomatik bellek dosyalarının listesini gösterir. İlk olarak, belleğinizin nerede ve ne kadar olduğuna bir göz atın.
7. Paralel İşlemde Üç Tuzak (Maliyet, DB, İzinler)
Artık mekanizmayı anladığınıza göre, işlem için üç dikkat noktası.
Birincisi token maliyetidir. Resmi dokümanlar, bir temsilci ekibindeki her ekip arkadaşının bağımsız bir bağlama sahip olması nedeniyle token kullanımının kişi sayısıyla orantılı olarak arttığını belirtir. Rutin işler için 5 kişi kullanmak maliyet kaybına neden olur. Bu nedenle resmi öneri 3–5 kişidir ve "üç odaklı üyenin genellikle beş dikkati dağınık üyeyi yendiği" belirtilir (Resmi Dokümanlar).
İkincisi, worktree'lerin izolasyon kapsamıdır. Bir worktree, yalnızca dosya ayrımı için bir Git mekanizmasıdır; veritabanları, ortam değişkenleri ve çalışan hizmetler hala paylaşılır. İki oturum aynı yerel DB'de geçişler çalıştırırsa, bozulur. Resmi dokümanlar, "her worktree'de geliştirme ortamını başlatmayı (bağımlılıkları yükleme, sanal ortamlar kurma) unutmayın" ve görevler DB'ye dokunuyorsa, şemaları, Docker konteynırlarını veya .env dosyalarını ayırmanız gerektiği konusunda uyarır (Resmi Dokümanlar).
Üçüncüsü izinlerdir. Ekip arkadaşları, oluşturulduklarında liderin izin ayarlarını devralırlar. Lideri --dangerously-skip-permissions ile çalıştırırsanız, tüm ekip arkadaşları da aynı onaylanmamış durumda olur. Bir kazanın etkisi paralel olarak yayıldığından, izinleri lider tarafında kısıtlamak daha güvenlidir.
8. Orta Düzey Kullanıcılar için SSS: Kişi Sayısı, Genişleme ve Kalite Kapıları
Son olarak, sık sorulan sorulara bazı ek cevaplar.
S. Kaç oturum gerçekçi?
Daha önce bahsedilen 3 katmanlı, 8 oturumlu yapı iyi bir kılavuzdur. Kilit nokta, 8 kişiyi tek bir temsilci ekibine tıkıştırmak değil, 3–5 kişilik bir ekibi çekirdek olarak kullanmak ve worktree oturumları veya alt temsilciler eklemektir. Bu, resmi önerilerle (ekip başına 3–5 kişi, ekip arkadaşı başına 5–6 görev) uyumludur. Nihai sınır, izleyebileceğiniz ve yönlendirebileceğiniz aralıktır. Sayıyı komuta edebileceğinizden fazla artırırsanız, verimlilik düşecektir.
S. Alt temsilciler ve temsilci ekipleri yetersiz kalırsa ne olur?
Çok sayıda bağımsız oturumu tek bir yerden izlemek istiyorsanız, resmi alt temsilciler sayfası arka plan temsilcileri adı verilen bir mekanizmadan bahseder. Bunu katmanlar halinde düşünün: bir oturum içinde yardım için alt temsilciler, konuşmaya dayalı paralel bir ekip için temsilci ekipleri ve birçok bağımsız oturumu yönetmek için arka plan temsilcileri.
S. Kaliteyi nasıl garanti edebilirim?
CLAUDE.md içindeki öneriler yalnızca "uygulaması kolay talimatlardır." Kesinlikle uygulamak istediğiniz kontroller için, bunları hook'lar ile zorlayın. Temsilci ekiplerinde TeammateIdle, TaskCreated ve TaskCompleted gibi hook'lar bulunur; çıkış kodu 2 döndürmek geri bildirim gönderir ve çalışmanın devam etmesini sağlar (Resmi Dokümanlar). Bu, "testler yeşil olana kadar tamamlama" gibi kuralları programlı olarak uygulayabileceğiniz anlamına gelir.
Özet: Monitörden Tasarımcıya/Yetki Devredene
Claude Code'un değeri, yalnızca kodu daha hızlı yazmaktan çok, bir kişinin birden çok özelleşmiş Claude'u kontrol edebilmesinde yatar. İşte kilit noktalar:
Üç mekanizmayı karıştırmayın: alt temsilciler sonuçları döndürür, temsilci ekipleri konuşmaya dayalı ekiplerdir ve worktree'ler dosyaları izole eder. 8 oturumu Komut, Uygulama ve Kalite katmanlarına bölün; uygulamayı worktree'ler ile izole edin ve kalite rollerini alt temsilci tanımları veya temsilci ekipleriyle belirleyin. Rol sınırlarını CLAUDE.md yerine alt temsilci tanımlarında belirleyin ve mutlak kuralları hook'lar ile zorlayın. Özel bir SQLite çözümü oluşturmadan önce resmi markdown tabanlı otomatik belleği düzenleyin. Ekip başına 3–5 kişiyi hedefleyin ve katmanlar ekleyerek 8 işçiye ulaşın.
Bugün başlamak için denenecek 3 adım:
- [ ] İzole bir oturum başlatma hissini yakalamak için
claude --worktree test-1yazın. - [ ]
.claude/agents/dizininde bir "incelemeci" rolü için bir alt temsilci tanımı yazın ve uygulamanızı inceletmesini sağlayın. - [ ]
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1ayarını yapın ve üç ekip arkadaşıyla paralel olarak bir PR incelemesi çalıştırmayı deneyin.
Tek bir oturumda sürekli düzeltme talimatları yazarak geçirdiğiniz zaman, rolleri tasarlamak ve yetki devretmek için harcanan zamana dönüşecek. Neyi bırakıp neyi denetleyeceğinize karar vermek, paralel işlemde kalan en insani iştir.
Referans Bağlantıları (Resmi Birincil Kaynaklar)
- Özel alt temsilciler oluşturun
- Claude Code oturumlarından oluşan ekipler oluşturun
- Worktree'ler ile paralel oturumlar çalıştırın
- Claude'un projenizi nasıl hatırladığı / CLAUDE.md ve otomatik bellek
X'te paylaşamadığım faydalı bilgileri bu Açık Sohbet'te paylaşmayı planlıyorum. İlgileniyorsanız, şimdi katılın.
