Çoklu Agent Orkestrasyonu

Yeniden düzenleme göreviniz 6 modül genelinde 40 dosyaya dokunuyor. Tek bir Claude oturumu bunları sırayla işliyor — 90 dakika bekleme. Çoklu agent orkestrasyonuyla, 4 paralel işçi 25 dakikada bitirir.

Tek agent yaklaşımları yetersiz hissettirmeden çoklu agent’a başvurmayın. Koordinasyon yükü gerçektir — her agent kendi oturumunu tam bağlamla çalıştırır, bu yüzden herhangi bir hız artışı görmeden önce 3-5 kat token ödüyorsunuz.

Test metodolojisi: 3.000 satırlık bir Express uygulamasının yeniden düzenlenmesi. Tek agent (Opus, plan modu): 90 dakika. Üç agent’lı takım (dosya keşifçi + yeniden düzenleme lideri + test doğrulayıcı): 25 dakika. Aynı kalite, 3,6 kat daha hızlı.

Çoklu agent orkestrasyonu, birden fazla Claude Code örneğini bir takım olarak birlikte çalıştırmanıza olanak tanır; her biri kendi bağlam penceresine sahiptir, paylaşılan bir listeden görev alır ve birbirleriyle doğrudan mesajlaşır. Bir oturum takım lideri olarak hareket eder, çalışmayı koordine eder, takım arkadaşlarını oluşturur ve sonuçları sentezler. Bu, tüm kod tabanı genelinde karmaşık işleri paralelleştirmek için en yüksek kaldıraçlı kalıptır.

Subagent’lar ve Takımlar

Temel ayrım hiyerarşidir. Subagent’lar tek bir üst öğeye rapor verir. Agent takımları ise paylaşılan bir görev listesi ve doğrudan mesajlaşma aracılığıyla koordine olan eşitlerdir. Takımlar, her agent’ın çakışma olmadan dosya değiştirebilmesi için git worktree’leri (deponuzun ayrı dizin kopyaları) kullanır.

Odaklanmış bir işin çalışması, bir sonuç üretmesi ve geri dönmesi gerektiğinde subagent’ları kullanın. Birden fazla agent’ın müzakere etmesi, uçuş sırasında bağlam paylaşması ve ortak bir iş listesinden bağımsız olarak iş alması gerektiğinde agent takımlarını kullanın.

Takım Lideri Kalıbı

Takım lideri ana Claude Code oturumudur. Takımı oluşturur, role özel prompt’larla takım arkadaşlarını başlatır, paylaşılan görev listesini tanımlar ve sonunda sonuçları sentezler. Lider, takımın ömrü boyunca sabittir ve devredilemez.

Yaşam döngüsü net bir sıra izler:

1. Kurulum — Görevi ve takım yapısını doğal dilde tanımlarsınız
2. Oluşturma — Claude belirli rol prompt’larıyla takım arkadaşlarını oluşturur
3. Planlama — Lider bağımlılıklarla paylaşılan bir görev listesi oluşturur
4. Yürütme — Takım arkadaşları bağımsız olarak görevleri alır ve üzerinde çalışır
5. İletişim — Takım arkadaşları bulguları paylaşmak ve çakışmaları çözmek için birbirleriyle mesajlaşır
6. Sentez — Lider sonuçları toplar ve nihai çıktıyı üretir
7. Temizlik — İşiniz bittiğinde lidere temizlik yapmasını söylersiniz (her zaman lider aracılığıyla, asla takım arkadaşları değil)

Takım arkadaşları liderin konuşma geçmişini miras ALMAZ. CLAUDE.md, MCP sunucuları ve becerileri alırlar, ancak konuşma bağlamını almazlar. Tam rol açıklamasını, sahip olunan dosyaları, beklenen çıktı formatını ve kısıtlamaları doğrudan oluşturma prompt’una dahil edin.

Paylaşılan Görev Listesi

Paylaşılan görev listesi koordinasyonun omurgasıdır. Her görev, sabit bir yaşam döngüsünde ilerleyen bir duruma sahiptir:

pending  -->  in progress  -->  completed

Görevler diğer görevlere bağımlılık bildirebilir. Çözülmemiş bağımlılıkları olan bekleyen bir görev alınamaz. Bir takım arkadaşı mevcut işini bitirdiğinde, listeyi bir sonraki uygun bekleyen görev için tarar, onu alır ve başlar.

Görev alma, yarış koşullarını önlemek için dosya kilitleme kullanır. İki takım arkadaşı aynı anda aynı görevi almaya çalışırsa, yalnızca biri başarılı olur. Diğeri yeniden tarar ve farklı bir görev seçer.

Takım yapılandırması ~/.claude/teams/{team-name}/config.json konumunda ve görev verileri ~/.claude/tasks/{team-name}/ konumunda yaşar. Bunlar diskte kalıcıdır, böylece lider tam oturum boyunca durumu izleyebilir.

Posta Kutusu Sistemi

Posta kutusu sistemi agent’lar arası doğrudan mesajlaşmayı sağlar. Takım arkadaşları yalnızca lidere değil, birbirlerine de mesaj gönderebilir. Bu, her koordinasyon talebinin bir darboğazdan geçmesini engeller.

Tipik bir alışveriş şöyle görünür:

[frontend-dev -> backend-dev]
  "I need the /auth endpoint to return a user_id field in the response body."

[backend-dev -> frontend-dev]
  "Done. The response now includes { user_id, token, expires_at }."

Posta kutusu kalıbı, agent takımlarını subagent’lardan ayıran şeydir. Liderin her şeyi aktardığı merkez-ve-kol modelinin yerine, takım arkadaşları eşler arası bir ağ oluşturur. Bu, frontend ve backend agent’larının liderin mesajları aktarmasını beklemeden API sözleşmelerini müzakere etmesi gereken katmanlar arası özellik geliştirme gibi iş akışları için kritiktir.

Dosya Kilitleme

İki takım arkadaşının aynı dosyayı düzenlemesi birleştirme çakışmalarına ve boşa giden işe neden olur. Agent takımları sistemi, yarış koşullarını önlemek için görev alma sırasında dosya kilitleme kullanır, ancak daha önemli savunma görev tasarımıdır.

Her takım arkadaşının farklı dosyalara sahip olması için görevleri dizin sınırları etrafında yapılandırın:

• Frontend takım arkadaşı: src/components/, src/styles/
• Backend takım arkadaşı: src/api/, src/middleware/
• Test takım arkadaşı: tests/, test-fixtures/

İdeal takım boyutu 3-5 takım arkadaşı ve takım arkadaşı başına 5-6 görev’dir. Daha fazla takım arkadaşı doğrusal token maliyet ölçeklendirmesi ve daha fazla koordinasyon yükü anlamına gelir. Daha az takım arkadaşı daha az paralellik anlamına gelir.

Takım Arkadaşı Modları

Takım arkadaşlarının terminalinizde nasıl görüntülendiği --teammate-mode bayrağına bağlıdır.

In-process modu en taşınabilir seçenektir. Bölünmüş panel modu daha iyi görünürlük sağlar ancak VS Code terminalinde, Windows Terminal’de veya Ghostty’de çalışmaz. in-process modunda terminal çökerse, takım arkadaşları kaybolur. Bölünmüş panel modu (tmux) daha dayanıklıdır çünkü her panel bağımsız bir tmux sürecidir.

Manuel Paralellik için Git Worktree’ler

Deneysel agent takımları özelliği olmadan daha basit paralel çalışma için, yerel git worktree desteğini kullanın:

Her worktree, kendi çalışma dizinine sahip ayrı bir checkout’tur. Farklı worktree’lerdeki Claude oturumları, ayrı dizin ağaçlarında çalıştıkları için dosya yazmalarında çakışamazlar. Temel kısıtlamalar: her worktree benzersiz bir dal adı kullanmalıdır, worktree’ler aynı .git dizinini paylaşır (bu yüzden rebase gibi git işlemleri hala çakışabilir) ve CLAUDECODE ortam değişkeni Claude’un Claude içinde iç içe geçirilmesini önler.

Yaygın worktree hataları:

• fatal: not a git repository — git worktree add’ı alt dizinden değil, depo kökünden çalıştırın
• worktree already exists — Yeni worktree oluşturmadan önce eski worktree’leri git worktree prune ile temizleyin

Hook’larla Kalite Kapıları

İki hook olayı özellikle agent takımı orkestrasyonu için tasarlanmıştır:

• TeammateIdle — Bir takım arkadaşı mevcut görevini bitirdiğinde ve alacak görevi kalmadığında tetiklenir. Hook’unuz boşta kalmaya izin vermek için 0 ile veya geri bildirim gönderip takım arkadaşını çalıştırmaya devam ettirmek için 2 ile çıkabilir (ör. “Henüz testleri çalıştırmadın”).
• TaskCompleted — Bir takım arkadaşı bir görevi tamamlandı olarak işaretlediğinde tetiklenir. Hook’unuz kabul etmek için 0 ile veya reddetmek ve takım arkadaşını geri çalışmaya göndermek için 2 ile çıkabilir (ör. “Testler başarısız oluyor, önce düzelt”).

Örnek: Testler geçene kadar dosya yazmayı engelle

{
  "hooks": {
    "PreToolUse": [
      {
        "filter": { "toolNames": ["Write", "Edit"] },
        "hooks": [
          {
            "type": "command",
            "command": "npm test",
            "on_error": {
              "action": "block",
              "message": "Tests failing. Fix them before writing files."
            }
          }
        ]
      }
    ]
  }
}

Bu kalıp, Write/Edit çağrılarına izin vermeden önce her agent’ın çıktısını doğrular. npm test sıfır olmayan bir kodla çıkarsa, hook aracı engeller ve geri bildirim gönderir. Testler geçene kadar hiçbir takım arkadaşı dosyaları değiştiremez.

Worktree İzolasyonu

--worktree bayrağı izole geliştirme için gerçek bir git worktree oluşturur:

• worktree-<name> dalında .claude/worktrees/<name>/ konumunda bir worktree oluşturur
• Dahili olarak git worktree add kullanır — standart git araçları çalışır (git worktree list, git worktree remove)
• Bir worktree’de oluşturulan dosyalar ana dalda görünmez — tam git düzeyinde izolasyon
• Worktree’ler Claude oturumu sona erdikten sonra kalıcıdır — otomatik olarak temizlenMEZ
• Birden fazla worktree, her biri kendi dalında, bir arada var olabilir

# Özellik çalışması için izole bir worktree oluştur
claude --worktree feature-auth

# Tüm worktree'leri listele (Claude tarafından oluşturulanlar dahil)
git worktree list

# İşiniz bittiğinde temizleyin
git worktree remove .claude/worktrees/feature-auth

Tmux Entegrasyonu

--tmux bayrağı (yalnızca etkileşimli mod), worktree için bir tmux oturumu oluşturarak yan yana terminal panellerini etkinleştirir. Geleneksel tmux davranışı ile iTerm2 yerel panelleri için --tmux=classic kullanın. --print (-p) modunda kullanılamaz.

# Paralel etkileşimli çalışma için worktree + tmux
claude --worktree feature-api --tmux