# Claude Code Multi-Agent Teams: Paralel AI Agentlarla Geliştirme
Tek bir AI agent iyi, ama ya bes tanesi ayni anda calissa? Claude Code'un multi-agent sistemi, karmaşık yazılım projelerini paralel sprint'ler halinde yonetmeni sagliyor. Bir agent kod yazarken digeri review yapiyor, ucuncusu test kosuyor — ve hepsi koordineli. Bu yazida team mimarisinden gerçek proje orneklerine kadar multi-agent gelistirmenin tum detaylarini kesfedecegiz.
Not: Bu rehber Claude Code resmi dokumantasyonu, Anthropic güncellemeleri ve 50+ agent session deneyimine dayanmaktadir.
İçindekiler
- Multi-Agent Nedir ve Neden Önemli?
- Mimari: Team Lead, Teammate ve Task
- TeamCreate ve Agent Rolleri
- SendMessage ile Koordinasyon
- TaskCreate ile Paralel Sprint
- Agent Pattern'leri
- Code + Review Pattern
- Gerçek Proje Ornegi: 19 Proje Ekleme
- Best Practices ve Anti-Pattern'ler
- Sonuç ve Öneriler
1. Multi-Agent Nedir ve Neden Önemli?
Geleneksel AI asistanlar sirayla çalışır — bir iste bitmeden digerine gecemezsin. Multi-agent sistemde ise birden fazla AI agent paralel çalışır:
Özellik | Tek Agent | Multi-Agent |
|---|---|---|
Çalışma | Sirayla | Paralel |
Hız | 1x | 3-5x |
Kapsam | Tek dosya odakli | Çoklu dosya/proje |
Review | Yok | Otomatik peer review |
Koordinasyon | Gereksiz | Team lead yonetir |
Maliyet | Dusuk | Orta-yuksek |
Ne Zaman Multi-Agent Kullanmalisin?
- 3+ dosya degisecekse
- Bağımsiz is parçalari varsa
- Farklı uzmanliklara ihtiyaç varsa (kod + test + review)
- Zaman kritik ise (paralel = daha hızlı)
Pro Tip: Multi-agent kullanmak her zaman doğru değil. 1-2 dosyalik bir değişiklik için tek agent daha verimli. Karar agacini iyi öğren.
2. Mimari: Team Lead, Teammate ve Task
Claude Code multi-agent sistemi uc katmandan olusur:
Team Lead (Lider)
Ana konversasyondaki Claude Code instance'i. Planlama yapar, task'lari dagitir, sonuçları birleştirir.
Teammate (Takim Arkadasi)
Team lead'in olusturdugu bağımlı agent'lar. Her teammate kendi context'inde çalışır ama team lead ile iletişim kurabilir.
Task (Gorev)
Daha hafif bir yaklaşım. Teammate gibi ama daha bağımsiz — sonuç dondurur ve kapanir.
swift
1Team Lead (Ana Agent)2 ├-- Teammate A: "Frontend Developer"3 │ ├-- Task A1: "Header component"4 │ └-- Task A2: "Footer component"5 ├-- Teammate B: "Backend Developer"6 │ └-- Task B1: "API endpoint"7 └-- Teammate C: "Reviewer"8 └-- Tum değişiklikleri review eder3. TeamCreate ve Agent Rolleri
Bir team oluşturmak için Team Lead su yapiyi kullanir:
typescript
1// Team oluşturma ornegi (kavramsal)2TeamCreate({3 teammates: [4 {5 name: "frontend-dev",6 role: "Frontend geliştirici. React/Next.js/Tailwind uzmanı.",7 tools: ["Edit", "Write", "Glob", "Grep", "Read", "Bash"],8 instructions: "Sadece src/components/ dizininde çalış. Tailwind mobile-first yaz."9 },10 {11 name: "backend-dev",12 role: "Backend geliştirici. API ve veritabani uzmani.",13 tools: ["Edit", "Write", "Bash", "Read"],14 instructions: "Sadece src/lib/ ve src/api/ dizinlerinde çalış."15 },16 {17 name: "reviewer",18 role: "Kod reviewer. Kalite ve güvenlik odakli.",19 tools: ["Read", "Grep", "Glob"],20 instructions: "Dosya DUZENLEME. Sadece oku ve rapor yaz."21 }22 ]23});Agent Rol Tanımlama Kurallari
- Net kapsam — Her agent hangi dizinlerde calisacagini bilmeli
- Sınırli yetkiler — Reviewer'a Edit verme, sadece Read
- Bağımsiz dosyalar — Iki agent ayni dosyayi duzenleyememeli (conflict)
- Spesifik talimatlar — Genel değil, somut yonergeler ver
Pro Tip: Agent'lara "uzman" rolunu verin — "sen bir CSS uzmanisin" yerine "sen Tailwind CSS mobile-first uzmanisin, tum class'larda base > sm > md > lg sirasini koru" gibi spesifik talimatlar verin.
4. SendMessage ile Koordinasyon
Agent'lar birbirleriyle SendMessage ile iletişim kurar:
typescript
1// Team Lead'den teammate'e mesaj2SendMessage({3 type: "message",4 recipient: "frontend-dev",5 content: "Header componentini tamamla. Tasarim: sticky, blur backdrop, hamburger mobile menu.",6 summary: "Header gorevi atandi"7});8 9// Teammate'ten Team Lead'e mesaj10SendMessage({11 type: "message",12 recipient: "team-lead",13 content: "Header tamamlandi. 3 dosya degistirildi: header.tsx, mobile-menu.tsx, nav-links.tsx",14 summary: "Header tamamlandi"15});16 17// Broadcast — TUM team'e mesaj (dikkatli kullan)18SendMessage({19 type: "broadcast",20 content: "KRITIK: API endpoint değişti. /api/v1 yerine /api/v2 kullanin.",21 summary: "API degisikligi bildirimi"22});İletişim Kurallari
Mesaj Tipi | Kullanım | Maliyet |
|---|---|---|
message | Tek bir agent'a | Dusuk |
broadcast | Tum team'e | N x mesaj maliyeti |
shutdown_request | Agent'i kapat | Dusuk |
Broadcast dikkatli kullan! N agent = N ayrı mesaj. Sadece kritik durumlar için.
5. TaskCreate ile Paralel Sprint
Task, teammate'ten daha hafif ve bağımsiz bir yaklasimdir:
typescript
1// Paralel task'lar oluşturma2const task1 = TaskCreate({3 description: "blog-posts-part5.ts dosyasindaki 7 blog'un Turkce karakterlerini duzelt",4 instructions: "readFileSync ile oku, Unicode escape'leri UTF-8'e çevir, writeFileSync ile yaz"5});6 7const task2 = TaskCreate({8 description: "blog-posts-part6.ts dosyasindaki 7 blog'un Turkce karakterlerini duzelt",9 instructions: "Ayni işlem: Unicode > UTF-8 donusumu"10});11 12const task3 = TaskCreate({13 description: "blog-posts-part7.ts dosyasindaki 7 blog'un Turkce karakterlerini duzelt",14 instructions: "Ayni işlem: Unicode > UTF-8 donusumu"15});16 17// Uc task PARALEL çalışır — 3x hızlıTask vs Teammate Karşılaştırmasi
Özellik | Task | Teammate |
|---|---|---|
Bağımlılık | Bağımsiz, sonuç dondurur | Team lead ile iletişim |
Yasam süresi | Gorev bitince kapanir | Açık kalir |
İletişim | Tek yonlu (sonuç) | Cift yonlu (mesaj) |
Kullanım | Bağımsiz işler | Koordinasyon gereken işler |
Maliyet | Daha dusuk | Daha yuksek |
6. Agent Pattern'leri
Pattern 1: Paralel Explore
2-3 agent farklı dosya gruplarini tarayan arastirma pattern'i:
typescript
1// Agent 1: Frontend dosyalarini tara2TaskCreate({3 description: "src/components/ altindaki tum dosyalari tara, accessibility sorunlarini bul"4});5 6// Agent 2: Backend dosyalarini tara7TaskCreate({8 description: "src/lib/ altindaki tum dosyalari tara, type safety sorunlarini bul"9});10 11// Agent 3: Test kapsamini tara12TaskCreate({13 description: "Tum dosyalari tara, test coverage eksik alanlari raporla"14});Pattern 2: Cross-Platform
Ayni degisikligi farklı platformlara paralel uygulama:
typescript
1// iOS agent2TaskCreate({ description: "iOS projesindeki API URL'lerini v1'den v2'ye güncelle" });3 4// Android agent5TaskCreate({ description: "Android projesindeki API URL'lerini v1'den v2'ye güncelle" });6 7// Flutter agent8TaskCreate({ description: "Flutter projesindeki API URL'lerini v1'den v2'ye güncelle" });Pattern 3: Research Sprint
Farklı çözüm yaklaşımlari arastirma:
typescript
1// Agent 1: Context7 ile dokumantasyon arastirmasi2TaskCreate({3 description: "Context7 kullanarak Next.js 15 static export limitasyonlarini arastir"4});5 6// Agent 2: Mevcut codebase analizi7TaskCreate({8 description: "Mevcut codebase'de middleware/server action kullanimlarini tara ve raporla"9});Bu pattern SwiftUI Performance yazimizda anlattigimiz profiling yaklasimina benzer — önce ölç, sonra optimize et.
7. Code + Review Pattern
En güçlü multi-agent pattern'i: bir agent kodlar, digeri review eder:
typescript
1// Faz 1: Code agent çalışır2TeamCreate({3 teammates: [4 {5 name: "coder",6 role: "Kod yazici. Özellik implement eder.",7 tools: ["Edit", "Write", "Read", "Bash", "Glob", "Grep"]8 },9 {10 name: "reviewer",11 role: "Kod reviewer. Güvenlik, performans ve kalite kontrol.",12 tools: ["Read", "Grep", "Glob"] // Sadece okuma yetkileri13 }14 ]15});16 17// Team Lead koordinasyonu:18// 1. Coder'a gorevi ata19SendMessage({20 recipient: "coder",21 content: "Yeni blog-posts-part15.ts dosyasi oluştur. 7 blog, her biri 10K+ karakter.",22 summary: "Blog yazma gorevi"23});24 25// 2. Coder bitince reviewer'a gönder26SendMessage({27 recipient: "reviewer",28 content: "blog-posts-part15.ts dosyasini review et. Kontrol listesi: TypeScript hatalari, Turkce karakter, 10K+ içerik, slug benzersizligi",29 summary: "Blog review gorevi"30});31 32// 3. Reviewer rapor verir, Team Lead son karari verirFlutter Clean Architecture yazimizda anlattigimiz katmanli yaklaşım burada da gecerli — her agent kendi katmaninda çalışır.
8. Gerçek Proje Ornegi: 19 Proje Ekleme
Bu portfolyo sitesine 19 yeni proje eklerken multi-agent pattern'ini kullandik:
Sprint Plani
swift
1Team Lead: Koordinasyon2 ├-- Agent 1-5: Her biri 3-4 proje case study yazar (paralel)3 ├-- Agent 6-8: Turkce karakter fix (paralel post-process)4 └-- Agent 9: Final review ve birlestimeSonuçlar
Metrik | Tek Agent | Multi-Agent (5) |
|---|---|---|
Sure | ~4 saat | ~50 dakika |
Kalite | Değişken | Tutarlı (standards) |
Hata | Yorgunluk etkisi | Review ile dusuk |
Dosya | 1 dosya sirasyla | 5 dosya paralel |
Karsilasilan Sorunlar ve Çözümler
- Conflict riski — Her agent farklı bolumu sahiplendi
- Tutarlılik — PROJECT_STANDARDS.md ile 21 kriter zorunlu kilindi
- Turkce karakter — Post-process agent'lari Unicode temizligi yapti
- Maliyet — 5 paralel agent = 5x token kullanımi, ama 4x hız kazanimi
Pro Tip: Multi-agent kullaniminda en büyük risk dosya conflict'idir. Her agent'in calisacagi dosyalari net olarak belirle. Ayni dosyayi iki agent duzenleyememeli.
9. Best Practices ve Anti-Pattern'ler
Best Practices
- Karar agaci kullan — 3+ dosya mi? Paralel mi? Koordinasyon gerekli mi?
- Dosya sahipligi — Her agent kendi dosya setini sahiplenmeli
- Maliyet-fayda analizi — 1-2 dosya için multi-agent gereksiz
- Spesifik talimatlar — "Kod yaz" değil, "src/lib/utils.ts'e parseDate fonksiyonu ekle"
- Review zorunlu — Her sprint'te en az bir review agent'i olsun
Anti-Pattern'ler
Anti-Pattern | Sorun | Çözüm |
|---|---|---|
Herkes her yerde | Dosya conflictleri | Net dosya sahipligi |
Broadcast spam | Maliyet patlasi | Sadece kritik broadcast |
Agent fazlaligi | Koordinasyon yuku | Max 5-7 agent |
Belirsiz talimat | Yanlış çıktı | Spesifik, olculebilir gorev |
Review'siz merge | Hata gecer | Her zaman review agent |
Maliyet Optimizasyonu
typescript
1// Basit arama için Haiku model kullan (ucuz)2TaskCreate({3 description: "grep ile tum .ts dosyalarinda 'any' kullanimini bul",4 model: "haiku" // Maliyet: Opus'un ~1/10'u5});6 7// Karmaşık kodlama için Opus kullan (güçlü)8TaskCreate({9 description: "Yeni authentication middleware yaz, JWT + refresh token",10 model: "opus" // Güç: En iyi kodlama yetenegi11});Modular Architecture SPM yazimizda anlattigimiz modul yaklaşımi gibi — her agent bir modul, birlikte calisirlar.
10. Sonuç ve Öneriler
Multi-agent geliştirme, doğru kullanildiginda hız ve kaliteyi ayni anda arttirir. Yanlış kullanildiginda ise maliyet ve karmaşıklık artar. Anahtar: doğru durumda doğru pattern'i seçmek. Büyük degisikliklerde önce Plan Mode ile mimari planlama yapip, sonra agent'lara dagitmak en etkili yaklasimdir. Ayrıca CI/CD pipeline'inla entegre ederek kalite kontrolunu otomatiklestirebilirsin.
Öneriler:
- 3+ dosya kurali — 3'ten az dosya degisecekse tek agent yeter
- Code + Review — En etkili pattern, her projede kullan
- Paralel Explore — Büyük codebase arastirmasi için ideal
- Dosya sahipligi — Conflict'i onlemenin tek yolu
- Haiku maliyet hack'i — Basit işler için ucuz model kullan
ALTIN İPUCU
Bu yazının en değerli bilgisi
Bu ipucu, yazının en önemli çıkarımını içeriyor.
Easter Egg
Gizli bir bilgi buldun!
Bu bölümde gizli bir bilgi var. Keşfetmek ister misin?
Okuyucu Ödülü
🎉 **Sonuna Kadar Okuyan Kahraman!** Tebrikler! Iste sana özel bir kaynak: [Everything Claude Code](https://github.com/affaan-m/everything-claude-code) — Community tarafindan derlenmis 1500+ snippet ile Claude Code multi-agent pattern'leri, hook'lar, skill'ler ve CLAUDE.md örnekleri. Gerçek projelerde test edilmis yapilandirmalar.

