Otonom Yazılım Geliştirme ve Çoklu Subagent Orkestrasyon Rehberi

Büyük Dil Modelleri (LLM) ile yazılım geliştirme serüveni ilk dönemlerde tek bir devasa kullanıcı istemine ("Bana uçtan uca bir e-ticaret sitesi yaz") ve modelin tek seferde tüm mimariyi kusursuz üretmesi beklentisine dayanıyordu. Ancak projeler büyüdükçe bu yaklaşım kaçınılmaz olarak çöktü:

• Bağlam Şişmesi (Context Drift): Ajanın 50.000 token sonrasında ilk baştaki mimari kuralları unutması,
• Halüsinasyon Patlaması: Modelin bilmediği kütüphane fonksiyonlarını uydurması,
• Scope Creep (Kapsam Kayması): Bir buton rengini düzeltmesi istenen ajanın tüm veritabanı şemasını baştan yazmaya kalkışması.

Modern yazılım mühendisliğinde bu krizin çözümü; tek bir monolitik bot yerine, rol odaklı çalışan ve atomik mikro-görevleri paralel yürüten Çoklu Alt Ajan (Multi-Agent / Subagent) orkestrasyonudur.

Bu kapsamlı eğitim rehberinde, sıfırdan kurumsal düzeyde bir alt ajan ekosistemi kurmayı, rolleri ve yetenekleri dinamik olarak enjekte etmeyi, paralel havuzları yönetmeyi ve kanıta dayalı teslimat protokollerini adım adım öğreneceğiz.

1. Rehber Özeti & Neler Öğreneceğiz?

Bu rehberi tamamladığınızda şu yetkinlikleri kazanmış olacaksınız:

• Monolitikten Ayrışma: Tek model yanılsamasından çıkıp orkestratör-işçi (Orchestrator-Worker) hiyerarşisine geçiş.
• Rol ve Yetenek Mimarisi: roles/ ve skills/ dizinleriyle ajanların uzmanlık alanlarını izole etme.
• Mikro-Görev Tasarımı: Halüsinasyonu sıfırlayan atomik görev sözleşmeleri (Task Contracts).
• Maksimum Paralel Yürütme (Max Parallelism): Birbirine bağımlı olmayan görevleri eşzamanlı çalıştırma taktikleri.
• Reaktif Uyandırma (Reactive Wakeup): Token yakan döngüleri (polling) kaldırıp olay güdümlü bildirim sistemi kurma.
• Kanıta Dayalı Teslimat: Test sonucu veya terminal logu olmadan hiçbir kodun kabul edilmemesi kuralı.

2. Ön Koşullar & Gerekli Araçlar

3. Aşama Aşama Adımlar

Adım 1: Monolitik Prompt Tuzağı ve Çoklu Ajan Mimarisine Geçiş

Monolitik yaklaşımda tek bir ajan aynı anda hem veritabanı mimarı, hem frontend tasarımcısı, hem de DevOps uzmanı olmaya zorlanır. Bu durum bilişsel aşırı yüklenmeye (cognitive overload) yol açar.

Çözüm: Hiyerarşik Ajan Mimarisi.

+-------------------------------------------------------------+
|               Kullanıcı (Ürün Yöneticisi)                   |
+-------------------------------------------------------------+
                              |
                              v
+-------------------------------------------------------------+
|             Ana Ajan (Tech Lead / Orchestrator)             |
|   - Görevi analiz eder, mimari plan çıkarır.                |
|   - Asla doğrudan kod yazmaz; mikro-görevlere böler.        |
+-------------------------------------------------------------+
       |                      |                       |
       v                      v                       v
+---------------+     +---------------+       +---------------+
| Subagent #1   |     | Subagent #2   |       | Subagent #3   |
| Backend Mimar |     | Frontend UI   |       | QA & Test     |
| (Laravel 13)  |     | (Bootstrap 5) |       | (Pest/PHPUnit)|
+---------------+     +---------------+       +---------------+
       \                      |                       /
        +---------------------+----------------------+
                              |
                              v
+-------------------------------------------------------------+
|               Kanıta Dayalı Teslimat & Doğrulama            |
|       (Terminal Logu, PHPStan 0 Hata, Test Raporu)          |
+-------------------------------------------------------------+

Adım 2: Tech Lead & Uzman Ajan Roller Sisteminin (roles/) Kurulması

Her ajan rolü, sınırları net bir Markdown belgesiyle tanımlanmalıdır.

Projenizin hafıza kökünde roles/ dizini açın ve rolleri tanımlayın:

Örnek: roles/04-laravel13-expert.md

---

title: Laravel 13 Expert
type: role
expertise: [backend, php, laravel13, api-design]

---

# Laravel 13 Expert

Sen bir Laravel 13 Uzmanısın. MVC desenine ve modern PHP 8.3+ standartlarına tavizsiz uyarsın.
- Asla Controller içine iş mantığı yığmazsın.
- Her zaman declare(strict_types=1) kullanırsın.
- N+1 sorgularını engellemek için Eager Loading kullanırsın.
- Görev bitiminde mutlaka php -l ve phpstan analiz kanıtı sunarsın.

Adım 3: Atomik Mikro-Görevlerin (Micro-Tasks) Tasarımı ve Kapsam İzolasyonu

Bir alt ajanın başarılı olması için ona verilen görev şu 4 kriteri karşılamalıdır:

1. Tek Sorumluluk: Sadece bir sınıfı, bir view bileşenini veya bir migration'ı hedefler.
2. Kesin Girdi/Çıktı: Hangi dosyaları okuyacağı ve nereye yazacağı açıktır.
3. Katı Sınırlar: Görev dışındaki hiçbir dosyaya dokunması yasaktır.
4. Kabul Kriteri: Kodun geçerli sayılması için gereken somut şartlar.

Görev Sözleşmesi Örneği:

{
  "task_id": "TASK-104",
  "role": "roles/04-laravel13-expert.md",
  "goal": "LearnEntry modeline getStepsAttribute accessor metodunu ekle",
  "target_files": [
    "app/Models/LearnEntry.php"
  ],
  "constraints": [
    "Diğer dosyalara dokunma",
    "declare(strict_types=1) koru"
  ],
  "verification": "php -l app/Models/LearnEntry.php çıktısı 'No syntax errors detected' olmalıdır."
}

Adım 4: Rol ve Yetenek Enjeksiyon Protokolü (Role & Skill Injection)

Bir subagent başlatılırken (invoke_subagent), ajanın sistem promptuna rol dosyası ve ihtiyaç duyacağı beceri (skill) dosyaları enjekte edilmelidir. Subagent'ın ilk yapması gereken eylem bu dosyaları view_file ile okumaktır.

[Prompt Enjeksiyonu]
"ROL ENJEKSİYONU: Sen bir Laravel 13 Uzmanısın.
GÖREV ÖNCESİ ZORUNLU OKUMA: İşe başlamadan önce İLK ADIM olarak view_file ile 
'roles/04-laravel13-expert.md' ve 'rules/user-preferences.md' dosyalarını oku.
Standartları özümsedikten sonra hedefe geç."

Bu protokol sayesinde alt ajan genel AI reflekslerinden sıyrılarak projenin yerel standartlarını ve kodlama kurallarını (örneğin badge kontrastları, spacing limitleri) hatasız benimser.

Adım 5: Eşzamanlı Paralel Havuzlar (Parallel Pools) ile Verim Maksimizasyonu

Birbirine bağımlılığı olmayan görevler sırayla değil, aynı anda tek bir çağrıda paralel koşturulmalıdır:

{
  "Subagents": [
    {
      "TypeName": "self",
      "Role": "Backend Model Mimarı",
      "Prompt": "LearnEntry.php modelindeki accessor metodlarını güncelle..."
    },
    {
      "TypeName": "self",
      "Role": "UI/UX Blade Uzmanı",
      "Prompt": "resources/views/learn/show.blade.php şablonuna stepper bileşenini ekle..."
    },
    {
      "TypeName": "self",
      "Role": "QA Test Uzmanı",
      "Prompt": "tests/Feature/LearnEntryTest.php birim testlerini hazırla..."
    }
  ]
}

Paralel yürütme ile 15 dakikalık bir refactoring süreci 2 dakikaya indirilir.

Adım 6: Reaktif Uyandırma (Reactive Wakeup) ile Token Tasarrufu ve Sıfır Polling

Alt ajanların durumunu kontrol etmek için arka planda sürekli sleep veya periyodik cron zamanlayıcıları kurmak token israfına yol açar.

Modern agentic mimaride Reaktif Uyandırma (Reactive Wakeup) uygulanır:

1. Tech Lead alt ajanı başlatır ve sırasını (turn) sonlandırır.
2. Alt ajan arka planda izole çalışır.
3. Alt ajan işini bitirdiğinde send_message ile ana ajana sonuç raporunu iletir.
4. Sistem bu mesajı aldığında Tech Lead'i otomatik olarak uyandırır.

Bu prensip sayesinde sıfır token israfı ve anlık tepki hızı elde edilir.

Adım 7: Kanıta Dayalı Teslimat ve Kalite Güvence (QA) Kapıları

Bir alt ajanın işi bitirdiğini iddia etmesi yeterli değildir; doğrulanabilir somut kanıt sunması zorunludur:

[Zorunlu Teslimat Paketi]
1. Değiştirilen dosya linki: [LearnEntry.php](file:///Users/.../LearnEntry.php)
2. Sözdizimi Kontrolü:
   $ php -l app/Models/LearnEntry.php
   Output: No syntax errors detected in app/Models/LearnEntry.php
3. Birim Test Çıktısı:
   $ php artisan test --filter=LearnEntryTest
   Passes: 4, Failures: 0

Eğer kanıt sunulmazsa Tech Lead görevi reddeder ve eksik kanıtların tamamlanmasını ister.

4. Yaygın Hatalar ve Çözümleri (Troubleshooting)

1. Kapsam Kayması (Scope Creep)

• Sorun: Ajan verilen tek bir dosya yerine ilgisiz onlarca dosyayı yeniden yazmaya kalkar.
• Çözüm: Prompt içine TargetFiles listesini mutlak olarak belirtin ve "Hedef liste dışındaki hiçbir dosyayı değiştiremezsin" kuralını enjekte edin.

2. Sürekli Polling ve Token Yanması (Token Burn)

• Sorun: Ana ajanın her 10 saniyede bir sleep ile durumu sorgulaması.
• Çözüm: Schedule ve timer araçlarını devre dışı bırakıp send_message tabanlı Reaktif Uyandırma kullanın.

3. Rol Uyumsuzluğu (Role Mismatch)

• Sorun: Backend uzmanı bir ajanın CSS veya Tailwind sınıfları uydurması.
• Çözüm: Görevleri uzmanlık alanlarına göre katı biçimde parçalayın (Separation of Concerns).

5. Test, Doğrulama & Canlı Çalıştırma

Geliştirdiğiniz subagent sisteminin performansını test etmek için aşağıdaki kontrol listesini uygulayın:

• İzole Rol Dosyaları: roles/ altında her uzmanlık için ayrı .md mevcut mu?
• Kullanıcı Standartları: memories/user-preferences.md dosyası ajan promptlarına aktarılıyor mu?
• Paralellik: Bağımsız en az 2 görev tek invoke_subagent ile eşzamanlı çalıştırılabiliyor mu?
• Kanıt Doğrulama: Görev çıktısında terminal logu veya test sonucu mevcut mu?

Bu disiplini oturttuğunuzda, yazılım geliştirme süreciniz tek kişilik bir çabadan 7/24 çalışan organize bir yazılım şirketine dönüşecektir!