Własne subagents — chroń kontekst wyspecjalizowanymi delegatami

Q12 · Rozszerzalność Czy używasz subagentów (wyspecjalizowanych sub-agentów z ograniczeniami narzędzi)?

Maksymalna odpowiedź: “Pełny zestaw: code-reviewer, code-explorer, code-architect — i z góry wiem, co delegować.”

Dlaczego to ważne: Subagenty chronią budżet głównego kontekstu i zrównoleglają niezależny research. Bez nich kontekst zapycha się surowym outputem z narzędzi.

Dlaczego to ważne w 2026

Kontekst jest ograniczonym zasobem w sesji agentowej. Nawet przy oknie 1M tokenów na Sonnet 5 i Opus 4.8 długie transkrypty narzędzi mogą wypchnąć plan i istotny kod, zanim dojdziesz do deklarowanego limitu. Wskazówki Anthropica dotyczące context engineering i niezależne badania długiego kontekstu wspierają jakościowy wniosek, że więcej kontekstu nie zawsze znaczy lepiej; punkt degradacji zależy od modelu, zadania i harnessu.

Subagenty mogą pomóc, gdy niezależny research da się podsumować przed zwrotem do orchestratora. Zleć code explorerowi wyszukiwanie call sites, wymagaj zwięzłego strukturalnego podsumowania i porównaj wynik z wykonaniem tej samej pracy w głównym wątku. Równoległość skraca wall-clock tylko przy naprawdę niezależnej pracy; opóźnienia narzędzi, zduplikowane odczyty i review mogą zjeść zysk.

Rate card może premiować tańszy model subagenta: Haiku 4.5 kosztuje $1/$5 za MTok, Sonnet 5 tymczasowo $2/$10 do 31 sierpnia (potem $3/$15), a Opus 4.8 $5/$25. Te proporcje porównują ten sam miks tokenów, a nie całe zadania. Zmierz łączną liczbę tokenów, retry i zaakceptowany output, zanim ogłosisz oszczędność albo równoważną jakość.

Jak naprawdę wygląda maksymalny wynik

Pełne punkty za Q12 dostajesz tylko wtedy, gdy wszystkie cztery poniższe są prawdziwe:

• Masz zainstalowany pełny zestaw subagentów opartych na rolach. Minimum code-reviewer, code-explorer (lub używasz wbudowanego Explore z Claude Code) i code-architect, plus 2–4 task-specific (np. migration-planner, test-author, doc-writer, sql-reviewer). Żyją w .claude/agents/ (project scope) i ~/.claude/agents/ (user scope), każdy jako pojedynczy plik .md z YAML frontmatter.
• Narzędzia są whitelistowane per subagent. code-reviewer dostaje Read, Grep, Glob — bez Bash, bez Write, bez Edit. code-architect dostaje read-only plus WebSearch. Test-author dostaje Read, Write, Edit, Bash (scope’owany do komend testowych). Zasada least privilege jest wymuszona we frontmatter, nie w Twojej głowie.
• Modele są routowane per subagent. Explorery, reviewery i bulk-scan agenty chodzą na claude-haiku-4-5-20251001. Architekci i planiści chodzą na claude-opus-4-8. Test-authorzy i refactor-boty zwykle chodzą na claude-sonnet-5. Orchestrator zostaje na Sonnet i decyduje, do kogo delegować. Ten routing trzyma się nawet wtedy, gdy główną sesję przeniesiesz wyżej, na Claude Fable 5 (nowy tier powyżej Opus 4.8, wydany 9 czerwca 2026): przypięte subagenty zostają na Haiku/Sonnet/Opus. Właśnie to ograniczenie kosztów sprawia, że Fable 5 jako default jest opłacalny, gdy tempo i jakość ważą więcej niż budżet.
• Potrafisz nazwać z góry, co delegujesz. Zanim odpalisz zadanie, już zdecydowałeś, które kroki główny agent wykonuje sam, a które fan-outuje. “Zmapuj call sites” → explorer. “Zreviewuj ten diff względem naszych reguł stylu” → reviewer. “Zaprojektuj plan migracji” → architect. Jeśli wymyślasz wybór delegacji w trakcie zadania, nie masz strategii subagentów — masz ciekawą zabawkę.

Cokolwiek mniej — “mam jednego custom agenta, którego nigdy nie używam”, “wszystko robię na wbudowanym general-purpose” albo “pozwalam modelowi decydować, kiedy iść w subagent” — to mid-tier na Q12.

Aktualny krajobraz (zweryfikowany przez web search)

Wbudowane w Claude Code (Explore, general-purpose)

Claude Code wysyła dwa subagent-like prymitywy z pudełka i warto znać oba, zanim zbudujesz własne.

• Explore. Wbudowany subagent wyspecjalizowany w rekonesansie codebase’u — file discovery, mapowanie call sites, pytania “gdzie w repo jest zaimplementowany feature X”. Explore jest wywoływany automatycznie, gdy orchestrator zdecyduje, że potrzebuje read-only sweepa, i zwraca strukturalne podsumowanie zamiast surowych treści plików. To agent, który samodzielnie ratuje kontekst przed anti-patternem “przeczytałem 40 plików, żeby znaleźć jedną funkcję”.
• General-purpose. Catch-all Task agent. Przydatny, gdy chcesz fan-outu zanim napiszesz custom agenta, ale nie ma specjalizacji roli ani ograniczeń narzędzi — czyli może wszystko i przez to zwykle robi za dużo. Traktuj go jak tymczasowe rusztowanie zanim napiszesz właściwego wyspecjalizowanego agenta.

Oba są ok jako defaulty, ale żaden nie zastępuje wykuratowanego zestawu. Cała pointa Q12 jest taka, że Ty zdecydowałeś, jakie są Twoje typowe delegacje, i to skodyfikowałeś.

Własne subagents w .claude/agents/ (spec markdown frontmatter, whitelist narzędzi)

Własne subagents to pliki markdown z YAML frontmatter. Dwie lokalizacje:

• .claude/agents/<name>.md — project-scoped, czekowany do repo, dostępny tylko w tym projekcie.
• ~/.claude/agents/<name>.md — user-scoped, dostępny we wszystkich projektach.

Project-scoped wygrywa przy kolizji. Claude Code czyta plik agenta na starcie sesji. Claude Code v2.1.198 usunął kreator /agents, dlatego poproś Claude o draft definicji albo edytuj .claude/agents/*.md bezpośrednio.

Spec frontmatter, ze wszystkim, co realnie się liczy:

---
name: code-reviewer
description: Reviews diffs against project style and architecture rules. Read-only.
tools: Read, Grep, Glob, WebSearch
model: claude-haiku-4-5-20251001
memory: user
---

# code-reviewer

You are a senior reviewer for this TypeScript/Next.js codebase. When invoked
on a diff or a set of changed files:

1. **Map the change.** Use Grep/Glob to find every call site touched by the
   diff. Read enough surrounding code to understand the contract, not the
   whole file.

2. **Score against the rules.** Apply, in order:
   - The project's CLAUDE.md style rules (single quotes, import ordering,
     interface for object shapes).
   - The relevant skill (if any) under .claude/skills/.
   - Standard quality: dead code, missing error paths, leaky abstractions,
     test coverage on changed branches.

3. **Return a structured summary.** Top: must-fix items with file:line.
   Middle: nits and style. Bottom: praise-worthy choices (so the orchestrator
   knows what to keep). Never paste the whole file back — return diff hunks
   or line ranges only.

Hard rules:
- You have no Write/Edit/Bash. Do not propose to run anything.
- If you find a structural problem requiring an architectural decision, stop
  and surface it. Do not redesign — that's the code-architect's job.

Pola, które liczą się najbardziej:

• tools — allowlist po przecinkach. Jeśli pole jest puste, subagent dziedziczy wszystkie narzędzia po orchestratorze — i to właśnie domyśl, przez który ludzie wpadają w kłopoty. Zawsze ustawiaj explicite. Typowe wzorce: Read, Grep, Glob dla agentów read-only; dodaj Write, Edit, MultiEdit dla edytorów; dodaj Bash(npm test:*) dla wąsko-scope’owanych runnerów komend.
• model — pin model per agent. Reviewery, explorery i bulk-scannery na claude-haiku-4-5-20251001. Architekci i planiści na claude-opus-4-8. Większość pozostałych na claude-sonnet-5. Pole akceptuje też krótkie aliasy haiku, opus, sonnet lub inherit — aliasy śledzą najnowszy snapshot każdego tieru i są bardziej forward-compatible; w pełni datowane ID przypina do konkretnego snapshotu. To pole utrzymuje też ekonomię setupu z Fable 5: defaultem głównej pętli może być claude-fable-5, podczas gdy pola model subagentów dalej wskazują na te tańsze tiery.
• description — pierwsze zdanie to to, co orchestrator czyta, decydując czy delegować. Otwórz czasownikiem i scope’em (“Reviews diffs against project style and architecture rules”), nie nazwą roli.
• memory — opt-in dla subagenta na persistent knowledge directory, który przeżywa konwersacje. Przydatne dla code-explorer (z czasem buduje mapę plików/featurów repo) i code-architect (akumuluje decyzje projektowe). Nie włączaj dla bezstanowych reviewerów.

Subagents w Cursor 3.0+

Cursor wypuścił first-class subagents w linii 2.4 i skonsolidował to przez 3.0 (2026). Model mentalny jest identyczny jak w Claude Code: parent agent deleguje do child agenta z własnym oknem kontekstu, system promptem i ograniczeniami narzędzi. Są dwie ważne Cursor-specyficzne uwagi:

• Dziedziczenie narzędzi jest opt-in, nie automatyczne. Custom rules i “efficiency prompts” zdefiniowane dla głównego agenta nie propagują się do subagentów, chyba że jawnie włączysz je w prompt subagenta. To pułapka, w którą ludzie wpadają — subagent ignoruje Twój style guide, bo nigdy mu go nie dałeś.
• Możesz ograniczyć, jakie typy subagentów dany parent może spawn’ować. Przydatne do zagnieżdżonej orchestracji: top-level architect może spawn’ować explorery, ale nie editory; editor może spawn’ować test-authora, ale nie kolejnego architekta. Daje to skończone drzewo delegacji zamiast rekurencyjnej darmochy.
• Subagenty chmurowe są first-class. Od Cursor 3.7 /in-cloud uruchamia izolowanego subagenta chmurowego, a /babysit zleca agentowi przygotowanie PR-a do merge, gdy parent pracuje dalej lokalnie lub w chmurze.

Wsparcie multi-agent w Codex

Codex obsługuje teraz natywną delegację multi-agent. CLI 0.142 dodał tryby polityki per task/turn: wyłączony, tylko na jawną prośbę albo proaktywny, a bieżący Codex uruchamia subagentów równolegle i pokazuje ich postęp na desktopie i mobile. Repozytoryjne AGENTS.md oraz skills mogą autoryzować delegację. Model konfiguracji nie jest kopią .claude/agents/, więc definicje ról trzymaj osobno dla każdego narzędzia i jawnie opisuj ich odpowiedniki.

Przykład: mały, ale realny zestaw

Działający zestaw na repo TypeScript/Next.js + Cloudflare:

.claude/agents/
  code-reviewer.md      # Haiku · Read/Grep/Glob · diffy vs reguły CLAUDE.md
  code-explorer.md      # Haiku · Read/Grep/Glob · call sites i mapy featurów
  code-architect.md     # Opus · Read/Grep/Glob/WebSearch · partner Plan mode
  migration-planner.md  # Opus · Read/Grep/Glob/WebSearch · multi-PR migracje
  test-author.md        # Sonnet · Read/Write/Edit/Bash(npm test:*) · pisze testy
  sql-reviewer.md       # Haiku · Read/Grep · review schemy i query D1
~/.claude/agents/
  pr-writer.md          # Haiku · Read/Bash(gh,git) · draftuje tytuły i body PR-ów
  doc-writer.md         # Sonnet · Read/Write/Edit · MDX docs w głosie projektu

Siedem wyspecjalizowanych agentów pokrywa ~90% delegacji, które wygeneruje realny dzień kodowania.

Krok po kroku: budowa subagenta

1. Wybierz pierwszą delegację, której masz dość robić samemu. Otwórz transkrypty Claude Code z ostatniego tygodnia i znajdź zadanie, które uruchamiałeś więcej niż trzy razy. “Zmapuj wszystkie call sites X”. “Napisz testy dla tej funkcji”. “Zreviewuj ten diff względem naszych reguł stylu”. To jest Twój pierwszy subagent.

2. Utwórz definicję agenta. Poproś Claude o draft Markdown z frontmatter albo edytuj plik bezpośrednio. Użyj project scope (.claude/agents/) dla definicji repozytoryjnej, a user scope (~/.claude/agents/) dla globalnej. Dawny kreator /agents usunięto w v2.1.198.

3. Napisz najpierw description, potem prompt. Description to to, co widzi orchestrator przy decyzji o delegacji; prompt to to, co widzi subagent przy uruchomieniu. Otwórz description czasownikiem i scope’em (“Reviews diffs”, “Maps call sites”, “Designs migration plans”) — nie rzeczownikiem (“A reviewer agent”).

4. Whitelistuj narzędzia jawnie. Nigdy nie zostawiaj tools: pustego. Dla code-reviewera: Read, Grep, Glob. Dla code-explorera: Read, Grep, Glob (to samo — i to ok). Dla code-architecta: Read, Grep, Glob, WebSearch. Dla edytora: dodaj Write, Edit, MultiEdit. Dla agenta odpalającego Bash: scope’uj go (Bash(npm test:*), nie goły Bash).

5. Pinuj model. Read-only / bulk-scan / klasyfikacja → claude-haiku-4-5-20251001. Partner Plan mode / architektura → claude-opus-4-8. Edytory i test-authorzy → claude-sonnet-5. Jeśli nie pinujesz, subagent dziedziczy model orchestratora i tracisz wygraną kosztową.

6. Powiedz agentowi, czego nie robić. Na dole każdego promptu powinna być sekcja “Hard rules”: kiedy się zatrzymać, co eskalować, czego nie przeprojektowywać. Code-reviewer, który zaczyna przeprojektowywać architekturę, jest gorszy niż brak subagenta.

7. Przetestuj na trzech realnych przypadkach. Wywołaj subagenta na trzech faktycznych zadaniach z backlogu. Patrz, co wraca. Jeśli podsumowanie jest za długie (>500 tokenów), subagent za mało kompresuje — dociśnij instrukcje “return a structured summary”. Jeśli podsumowanie jest za krótkie, przedobrzyłeś kompresję — rozluźnij. Iteruj nad promptem, nie nad orchestratorem.

8. Zacommituj plik. Project-scoped agenty idą do repo, żeby Twoje przyszłe ja i koledzy z zespołu dostali to samo zachowanie delegacji. User-scoped agenty idą do dotfilesowego repo obok ~/.claude/settings.json i ~/.claude/skills/.

9. Dodaj regułę delegacji do CLAUDE.md. Jedna linijka mówiąca orchestratorowi, kiedy używać tego agenta (“When asked to review a diff, delegate to the code-reviewer subagent and integrate its summary”). Bez tej podpowiedzi orchestrator może zapomnieć, że agent istnieje.

Częste pułapki

• Nad-delegacja. Subagenty to ostre narzędzie. Jeśli delegujesz “popraw tę literówkę” do subagenta, dorzucasz dwa network round-tripy i context handoff na edycję 5-tokenową. Zasada kciuka: deleguj, gdy zadanie inaczej zżarłoby >5k tokenów głównego kontekstu albo gdy jest żenująco równoległe.
• Brak override’u modelu. Subagent może dziedziczyć model orchestratora. Przypnij tańszy model do wąsko zakresowanej pracy, gdy własne ewaluacje potwierdzają jakość; porównuj całkowity koszt zadania zamiast utożsamiać proporcję rate card z oszczędnością.
• Leaky context — zwracanie surowego outputu. Cała pointa subagenta jest taka, że jego surowe ready, grepy i tool calle nie wchodzą do kontekstu orchestratora. Jeśli system prompt subagenta mówi “zwróć zawartość pliku”, zabiłeś cel. Zmuś subagenta do podsumowywania.
• Brak ograniczeń narzędzi. Subagent, który dziedziczy wszystkie narzędzia, to po prostu główny agent w innym oknie. Zawsze whitelistuj. Code-reviewer z dostępem do Write w końcu spróbuje “pomocnie” wyedytować plik, który reviewuje.
• Jeden mega-agent zamiast zestawu. Pojedynczy “do-everything” custom agent to nie strategia subagentów; to drugi główny agent. Wygrana bierze się z promptów wyspecjalizowanych po roli, narzędzi wyspecjalizowanych po roli i modeli wyspecjalizowanych po roli. Jeśli wszyscy Twoi agenci mają tę samą linijkę tools:, nie specjalizujesz.
• Zapominanie o regule dziedziczenia promptów w Cursorze. Subagenty w Cursorze nie dziedziczą reguł projektu, chyba że jawnie wciągniesz je do promptu subagenta. Fix to jedno include @.cursor/rules/style.md w prompcie subagenta albo w pliku agenta.
• Traktowanie Codeksa jak single-context. Bieżący Codex deleguje natywnie. Ustaw świadomie politykę multi-agent, ogranicz współbieżność i użyj AGENTS.md lub skills do określenia, kiedy delegacja jest dozwolona.
• Robienie z Explore (lub general-purpose) “strategii subagentów”. Wbudowane agenty to świetne defaulty, ale max score wymaga, byś Ty zdecydował, co delegować i jak. Wykuratowany zestaw w .claude/agents/ to artefakt, który to dowodzi.

Jak sprawdzić, że jesteś tam, gdzie trzeba

• Twój projekt ma co najmniej trzech subagentów opartych na rolach (code-reviewer, code-explorer, code-architect) w .claude/agents/ lub ~/.claude/agents/.
• Istnieje co najmniej dwóch dodatkowych task-specific subagentów (np. migration-planner, test-author, doc-writer, pr-writer).
• Każdy subagent ma jawny whitelist tools: we frontmatter — żaden nie polega na dziedziczonych narzędziach.
• Co najmniej jeden subagent jest przypięty do claude-haiku-4-5-20251001 i co najmniej jeden do claude-opus-4-8 — różnicę kosztu widzisz w dashboardzie spend.
• Twój CLAUDE.md ma co najmniej jedną linijkę per agent, mówiącą, kiedy do niego delegować.
• Potrafisz bez zaglądania nazwać te trzy lub cztery zadania, które domyślnie delegujesz — i agenta, do którego każde z nich idzie.
• Podsumowania subagentów wracające do orchestratora to średnio <500 tokenów, a nie surowa zawartość plików.
• W ostatnim miesiącu odpaliłeś to samo zadanie raz bez i raz z delegacją do subagenta, i zauważyłeś różnicę w zużyciu kontekstu.

Dalsza lektura

Q8 · Agent skills Skills, subagenty i slash commandy działają razem — napisz skill raz, wywołuj z dowolnego subagenta.

Q13 · Hooki agenta Stop / PreToolUse / PostToolUse — wymuś wywołanie subagenta przy każdym commicie, PR-ze, review.

Q25 · Struktura zmian Pętla równoległe Explore → Plan mode → kod → auto-PR, którą subagenty czynią opłacalną.

Zrób Developer Scorecard Wyceń się na wszystkich 25 pytaniach w ~10 minut.