# Claude Code Multi-Agent Teams: Paralel AI Agentlarla Gelistirme
Tek bir AI agent iyi, ama ya bes tanesi ayni anda calissa? Claude Code'un multi-agent sistemi, karmasik yazilim projelerini paralel sprint'ler halinde yonetmeni sagliyor. Bir agent kod yazarken digeri review yapiyor, ucuncusu test kosuyor — ve hepsi koordineli. Bu yazida team mimarisinden gercek proje orneklerine kadar multi-agent gelistirmenin tum detaylarini kesfedecegiz.
Not: Bu rehber Claude Code resmi dokumantasyonu, Anthropic guncellemeleri ve 50+ agent session deneyimine dayanmaktadir.
Icindekiler
- Multi-Agent Nedir ve Neden Onemli?
- Mimari: Team Lead, Teammate ve Task
- TeamCreate ve Agent Rolleri
- SendMessage ile Koordinasyon
- TaskCreate ile Paralel Sprint
- Agent Pattern'leri
- Code + Review Pattern
- Gercek Proje Ornegi: 19 Proje Ekleme
- Best Practices ve Anti-Pattern'ler
- Sonuc ve Oneriler
1. Multi-Agent Nedir ve Neden Onemli?
Geleneksel AI asistanlar sirayla calisir — bir iste bitmeden digerine gecemezsin. Multi-agent sistemde ise birden fazla AI agent paralel calisir:
Ozellik | Tek Agent | Multi-Agent |
|---|---|---|
Calisma | Sirayla | Paralel |
Hiz | 1x | 3-5x |
Kapsam | Tek dosya odakli | Coklu dosya/proje |
Review | Yok | Otomatik peer review |
Koordinasyon | Gereksiz | Team lead yonetir |
Maliyet | Dusuk | Orta-yuksek |
Ne Zaman Multi-Agent Kullanmalisin?
- 3+ dosya degisecekse
- Bagimsiz is parcalari varsa
- Farkli uzmanliklara ihtiyac varsa (kod + test + review)
- Zaman kritik ise (paralel = daha hizli)
Pro Tip: Multi-agent kullanmak her zaman dogru degil. 1-2 dosyalik bir degisiklik icin tek agent daha verimli. Karar agacini iyi ogren.
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, sonuclari birlestirir.
Teammate (Takim Arkadasi)
Team lead'in olusturdugu bagimli agent'lar. Her teammate kendi context'inde calisir ama team lead ile iletisim kurabilir.
Task (Gorev)
Daha hafif bir yaklasim. Teammate gibi ama daha bagimsiz — sonuc 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 degisiklikleri review eder3. TeamCreate ve Agent Rolleri
Bir team olusturmak icin Team Lead su yapiyi kullanir:
typescript
1// Team olusturma ornegi (kavramsal)2TeamCreate({3 teammates: [4 {5 name: "frontend-dev",6 role: "Frontend gelistirici. React/Next.js/Tailwind uzmanı.",7 tools: ["Edit", "Write", "Glob", "Grep", "Read", "Bash"],8 instructions: "Sadece src/components/ dizininde calis. Tailwind mobile-first yaz."9 },10 {11 name: "backend-dev",12 role: "Backend gelistirici. API ve veritabani uzmani.",13 tools: ["Edit", "Write", "Bash", "Read"],14 instructions: "Sadece src/lib/ ve src/api/ dizinlerinde calis."15 },16 {17 name: "reviewer",18 role: "Kod reviewer. Kalite ve guvenlik odakli.",19 tools: ["Read", "Grep", "Glob"],20 instructions: "Dosya DUZENLEME. Sadece oku ve rapor yaz."21 }22 ]23});Agent Rol Tanimlama Kurallari
- Net kapsam — Her agent hangi dizinlerde calisacagini bilmeli
- Sinirli yetkiler — Reviewer'a Edit verme, sadece Read
- Bagimsiz dosyalar — Iki agent ayni dosyayi duzenleyememeli (conflict)
- Spesifik talimatlar — Genel degil, 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 iletisim 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 degisti. /api/v1 yerine /api/v2 kullanin.",21 summary: "API degisikligi bildirimi"22});Iletisim Kurallari
Mesaj Tipi | Kullanim | 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 ayri mesaj. Sadece kritik durumlar icin.
5. TaskCreate ile Paralel Sprint
Task, teammate'ten daha hafif ve bagimsiz bir yaklasimdir:
typescript
1// Paralel task'lar olusturma2const 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 cevir, writeFileSync ile yaz"5});6 7const task2 = TaskCreate({8 description: "blog-posts-part6.ts dosyasindaki 7 blog'un Turkce karakterlerini duzelt",9 instructions: "Ayni islem: 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 islem: Unicode > UTF-8 donusumu"15});16 17// Uc task PARALEL calisir — 3x hizliTask vs Teammate Karsilastirmasi
Ozellik | Task | Teammate |
|---|---|---|
Bagimlilik | Bagimsiz, sonuc dondurur | Team lead ile iletisim |
Yasam suresi | Gorev bitince kapanir | Acik kalir |
Iletisim | Tek yonlu (sonuc) | Cift yonlu (mesaj) |
Kullanim | Bagimsiz isler | Koordinasyon gereken isler |
Maliyet | Daha dusuk | Daha yuksek |
6. Agent Pattern'leri
Pattern 1: Paralel Explore
2-3 agent farkli 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 farkli platformlara paralel uygulama:
typescript
1// iOS agent2TaskCreate({ description: "iOS projesindeki API URL'lerini v1'den v2'ye guncelle" });3 4// Android agent5TaskCreate({ description: "Android projesindeki API URL'lerini v1'den v2'ye guncelle" });6 7// Flutter agent8TaskCreate({ description: "Flutter projesindeki API URL'lerini v1'den v2'ye guncelle" });Pattern 3: Research Sprint
Farkli cozum yaklasimlari 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 — once olc, sonra optimize et.
7. Code + Review Pattern
En guclu multi-agent pattern'i: bir agent kodlar, digeri review eder:
typescript
1// Faz 1: Code agent calisir2TeamCreate({3 teammates: [4 {5 name: "coder",6 role: "Kod yazici. Ozellik implement eder.",7 tools: ["Edit", "Write", "Read", "Bash", "Glob", "Grep"]8 },9 {10 name: "reviewer",11 role: "Kod reviewer. Guvenlik, 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 olustur. 7 blog, her biri 10K+ karakter.",22 summary: "Blog yazma gorevi"23});24 25// 2. Coder bitince reviewer'a gonder26SendMessage({27 recipient: "reviewer",28 content: "blog-posts-part15.ts dosyasini review et. Kontrol listesi: TypeScript hatalari, Turkce karakter, 10K+ icerik, slug benzersizligi",29 summary: "Blog review gorevi"30});31 32// 3. Reviewer rapor verir, Team Lead son karari verirFlutter Clean Architecture yazimizda anlattigimiz katmanli yaklasim burada da gecerli — her agent kendi katmaninda calisir.
8. Gercek 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 birlestimeSonuclar
Metrik | Tek Agent | Multi-Agent (5) |
|---|---|---|
Sure | ~4 saat | ~50 dakika |
Kalite | Degisken | Tutarli (standards) |
Hata | Yorgunluk etkisi | Review ile dusuk |
Dosya | 1 dosya sirasyla | 5 dosya paralel |
Karsilasilan Sorunlar ve Cozumler
- Conflict riski — Her agent farkli bolumu sahiplendi
- Tutarlilik — PROJECT_STANDARDS.md ile 21 kriter zorunlu kilindi
- Turkce karakter — Post-process agent'lari Unicode temizligi yapti
- Maliyet — 5 paralel agent = 5x token kullanimi, ama 4x hiz kazanimi
Pro Tip: Multi-agent kullaniminda en buyuk 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 icin multi-agent gereksiz
- Spesifik talimatlar — "Kod yaz" degil, "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 | Cozum |
|---|---|---|
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 | Yanlis cikti | Spesifik, olculebilir gorev |
Review'siz merge | Hata gecer | Her zaman review agent |
Maliyet Optimizasyonu
typescript
1// Basit arama icin 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// Karmasik kodlama icin Opus kullan (guclu)8TaskCreate({9 description: "Yeni authentication middleware yaz, JWT + refresh token",10 model: "opus" // Guc: En iyi kodlama yetenegi11});Modular Architecture SPM yazimizda anlattigimiz modul yaklasimi gibi — her agent bir modul, birlikte calisirlar.
10. Sonuc ve Oneriler
Multi-agent gelistirme, dogru kullanildiginda hiz ve kaliteyi ayni anda arttirir. Yanlis kullanildiginda ise maliyet ve karmasiklik artar. Anahtar: dogru durumda dogru pattern'i secmek. Buyuk degisikliklerde once Plan Mode ile mimari planlama yapip, sonra agent'lara dagitmak en etkili yaklasimdir. Ayrica CI/CD pipeline'inla entegre ederek kalite kontrolunu otomatiklestirebilirsin.
Oneriler:
- 3+ dosya kurali — 3'ten az dosya degisecekse tek agent yeter
- Code + Review — En etkili pattern, her projede kullan
- Paralel Explore — Buyuk codebase arastirmasi icin ideal
- Dosya sahipligi — Conflict'i onlemenin tek yolu
- Haiku maliyet hack'i — Basit isler icin 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 ozel 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 ornekleri. Gercek projelerde test edilmis yapilandirmalar.

