Orkiestracja Wielu Agentów

Główna idea

Jeden agent robiący wszystko sekwencyjnie jest wolny i podatny na błędy. Wiele agentów pracujących równolegle jest szybkich i wzajemnie się sprawdza.

Kluczowy insight: większość zadań ma niezależne podzadania, które mogą działać jednocześnie. Implementacja funkcji ma research, scaffolding, testy i dokumentację — wszystko to może wystartować w tym samym momencie.

Framework dekompozycji

Krok 1: Zmapuj pracę

Wylistuj wszystkie podzadania. Dla każdego zapytaj:

• Czy to może wystartować bez czekania na inne podzadanie?
• Czy to potrzebuje wyniku z innego podzadania?
• Czy dwóch agentów może nad tym pracować bez konfliktów?

Krok 2: Zbuduj graf zależności

[Zbadaj dokumentację API] ──→ [Zaimplementuj warstwę serwisów]
                                        ↓
[Napisz test fixtures] ──→ [Napisz testy integracyjne]
                                        ↓
[Scaffold komponentów UI] ──→ [Połącz UI z serwisem] ──→ [Testy E2E]

Niezależne korzenie mogą wystartować równolegle. Zależne węzły czekają na swoje inputy.

Krok 3: Zbriefuj każdego agenta

Każdy agent dostaje:

1. Co zrobić — konkretny, ograniczony zakresem deliverable
2. Czego NIE robić — granice (nie dotykaj plików X, nie podejmuj decyzji o Y)
3. Kontekst — tyle, żeby wykonać zadanie, nie cała historia projektu
4. Format wyjścia — jaki artefakt wyprodukować i gdzie go umieścić
5. Kryteria sukcesu — jak poznać, że skończył

Role agentów

Agent Research

• Czyta dokumentację, szuka wzorców, ocenia biblioteki
• Wynik: ustrukturyzowany dokument ustaleń
• Nigdy nie pisze produkcyjnego kodu

Agent Builder

• Implementuje funkcje w ograniczonym zakresie
• Dostaje jasną specyfikację, produkuje działający kod
• Commituje na branch, nie merguje

Agent Testowy

• Pisze testy ze specyfikacji (nie z implementacji)
• Orientacja TDD: najpierw testy, builder implementuje żeby przejść
• Niezależny od buildera, żeby uniknąć bias potwierdzenia

Agent Review

• Recenzuje kod buildera, ustalenia z researchu
• Audyt bezpieczeństwa, wydajności, poprawności
• Bez implementacji — tylko ustalenia

Agent Dokumentacji

• Aktualizuje dokumentację na podstawie tego, co zbudowano
• Produkuje dokumentację API, przewodniki migracji, changelogi

Wzorce orkiestracji

Wzorzec 1: Fan-out / Fan-in

Uruchom N agentów równolegle, zbierz wyniki, zsyntezuj.

Orkiestrator → [Agent 1, Agent 2, Agent 3] → Zbierz → Syntezuj → Wynik

Najlepszy dla: research, code review, zmiany w wielu plikach.

Wzorzec 2: Pipeline

Każdy agent przetwarza i przekazuje następnemu.

Research → Spec → Build → Test → Review → Deploy

Najlepszy dla: sekwencyjnych workflow'ów, gdzie każdy krok potrzebuje wyniku poprzedniego.

Wzorzec 3: Krytyka z podziałem ról

Ten sam input, różne perspektywy. Porównaj i uzgodnij.

Input → [Reviewer bezpieczeństwa, Reviewer wydajności, Reviewer UX] → Uzgodnij konflikty

Najlepszy dla: złożonych decyzji wymagających wielu punktów widzenia.

Wzorzec 4: Builder + Obserwator

Jeden agent buduje, drugi obserwuje w czasie rzeczywistym (patrz: prompt Dwuwątkowy Development).

Szablon briefingu

## Brief agenta: {rola}

**Misja:** {jedno zdanie — co dostarczasz}

**Zakres:**
- ZRÓB: {konkretne zadania}
- NIE RÓB: {granice}

**Input:** {co dostajesz na start}
**Output:** {dokładny deliverable, format, lokalizacja}

**Kontekst:**
{tyle tła, ile potrzeba — maks 3-5 zdań}

**Gotowe gdy:**
- [ ] {kryterium 1}
- [ ] {kryterium 2}

Rozwiązywanie konfliktów

Gdy agenci produkują sprzeczne wyniki:

1. Konflikty faktów — zweryfikuj ze źródłem, wybierz poprawny
2. Konflikty opinii — porównaj rozumowanie, wybierz lepiej uargumentowany
3. Konflikty zakresu — agenci się nakładali; scal niesprzeczne części, zdecyduj o nakładających się
4. Konflikty stylu — wybierz spójny z istniejącym codebase

Antywzorce

• Uruchamianie agentów bez jasnych granic zakresu (zduplikują pracę)
• Dawanie każdemu agentowi pełnego kontekstu projektu (marnuje tokeny, powoduje zamieszanie)
• Brak definicji formatu wyjścia (spędzisz więcej czasu na parsowaniu wyników niż agenci zaoszczędzili)
• Nadmierna dekompozycja prostych zadań (narzut orkiestracji przekracza samą pracę)
• Ignorowanie zależności (agent B potrzebuje wyniku agenta A, ale oba wystartowały jednocześnie)