Sub-agenty w Claude Code — wzorzec orkiestracji który działa

Sub-agent w Claude Code to instancja agenta odpalona z głównej sesji jako Tool call (Agent(...)). Ma własny kontekst, własne narzędzia, zwraca jeden wynik. Po kilku miesiącach widzę cztery wzorce w których zwraca się ich używanie. Pokażę je.

Anatomia sub-agenta

Wywołanie:

Agent({
  description: "Find auth middleware",
  subagent_type: "Explore",
  prompt: "Locate file containing JWT validation logic. Return path + key line numbers."
})

Sub-agent dostaje świeży kontekst (system prompt + pojedynczy prompt który podałem). Pracuje, zwraca jeden message. Główna sesja widzi tylko ten message, całe deliberowanie jest niewidoczne.

To jest kluczowa intuicja: sub-agent chroni Twój główny kontekst. Robi pracę, zwraca syntezę, nie zaśmieca głównej sesji.

Wzorzec #1: research równoległy

Najczęstszy use case. 3 niezależne pytania o codebase:

Agent({ description: "Find auth flow", subagent_type: "Explore", prompt: "..." })
Agent({ description: "Map RBAC roles", subagent_type: "Explore", prompt: "..." })
Agent({ description: "Audit token storage", subagent_type: "Explore", prompt: "..." })

Wszystkie trzy w jednym message → odpalają się równolegle. 3-minutowy wall time zamiast 9. Każdy zwraca raport pod 500 słów.

Wzorzec #2: izolowanie wąskiego zadania

Mam test który padł, agent ma zdebugować i naprawić. W głównej sesji jestem mid-refactor, nie chcę żeby debug zatłukł mi kontekst.

Agent({
  description: "Debug failing auth test",
  subagent_type: "general-purpose",
  prompt: `Test 'auth validates JWT signature' fails in CI. Logi: [paste].
           Znajdź root cause, napraw, popchnij commit. Zwróć summary < 200 słów.`
})

Sub-agent może spędzić 15 minut na debugowaniu, używać 50 tool calls, robić eksperymenty. Główna sesja widzi tylko "fixed by changing X in Y, commit ABC123".

Wzorzec #3: review przed merge

Ostre rozdzielenie ról: główna sesja pisze kod, sub-agent z dedykowanym subagent_type robi review.

Agent({
  description: "Review my changes for silent failures",
  subagent_type: "pr-review-toolkit:silent-failure-hunter",
  prompt: `Review unstaged changes in current dir. Focus on catch blocks
           that swallow errors. Report each with path:line.`
})

Sub-agent ma własny system prompt (specialist), inne reguły. Daje feedback który mainstream agent dałby gorszy.

Wzorzec #4: bounded creative task

Mam wygenerować 10 wariantów ofertowego maila. Każdy musi się różnić, ale wszystkie spójne brand-voice.

Bez sub-agenta: główna sesja generuje 10 wariantów, kontekst pęcznieje, jakość spada.

Z sub-agentem:

// 10 niezależnych wywołań
for (i in 1..10) {
  Agent({
    description: `Generate cold-outreach variant ${i}`,
    prompt: `Write variant ${i}/10 of cold-outreach email for [client].
             Brand voice: ... Hook: vary with ${variation_seed}`
  })
}

Każdy sub-agent ma świeży kontekst, ten sam brand prompt. Generuje swoją wersję. Główna sesja zbiera 10 wyników i wybiera najlepsze.

Czego NIE robi sub-agent

1. Nie pamięta poprzednich wywołań. Każde uruchomienie to fresh start. Jak chcesz coś trzymać między wywołaniami, git, plik, baza.

2. Nie modyfikuje głównego stanu poza explicit operations. Edycje plików, tak. Memory, nie (każdy ma własną). Tasks, tak.

3. Nie zna intencji za prompt. Jeśli powiesz "fix this bug", sub-agent nie zapyta "ale dlaczego?", zacznie naprawiać. To czemu prompty muszą być self-contained.

Reguły pisania prompta dla sub-agenta

Najważniejsza rzecz: brief jak inteligentnego kolegę który właśnie wszedł do pokoju.

✅ "Audit migration 0042_user_schema.sql for safety. Context: adding NOT NULL column to 50M-row table with default backfill. I want second opinion on backfill safety under concurrent writes. Report: safe yes/no, what breaks if not."

❌ "Sprawdź migration".

Pierwsze daje agentowi cel, kontekst, oczekiwany format. Drugie zwraca generic feedback.

Kosztowanie

Sub-agent = osobna sesja Claude API. Płacisz osobno za jego context + outputs. 3 sub-agenty równolegle = 3x token cost.

Reguły:

• Jeden sub-agent = ok dla każdego nietrywialnego wąskiego zadania
• 3 paralelne = ok dla research/exploration

• 5 paralelnych = znak że projekt promptu jest źle podzielony

W moim billingu sub-agenty to ~30% miesięcznego kosztu Claude Code. Worth it za ochronę głównego kontekstu.

Kiedy NIE używać

1. Gdy zadanie wymaga continuous feedback od Ciebie. Sub-agent zwróci jeden message, nie ma dialogu. Iteracja UI = nope.

2. Gdy zadanie jest trywialne. "Zmień kolor przycisku z czerwonego na zielony", main session w 5 sekund, sub-agent w 20.

3. Gdy chcesz uczyć się patrząc. Sub-agent ukrywa swoje deliberowanie. Jak debugujesz coś po raz pierwszy i chcesz zobaczyć tok myślenia, main session.

Sub-agenty to nie sci-fi orchestration. To prosty wzorzec "outsource'uj jedno zadanie żeby chronić główny kontekst". Stosowane bez ceregieli na każdy explore i każdy bounded debug, wymierna oszczędność. Próbuj, używaj naturalnie, mierz.