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 najrzadszym zasobem w każdej agentic coding session 2026. Nawet przy oknie 1M tokenów na Sonnet 4.6 i Opus 4.7, użyteczny budżet kontekstu pojedynczego agenta sypie się długo zanim dojdziesz do ściany — zanim przeczytasz 30 plików, odpalisz 10 test suite’ów i przegrepujesz tuzin call site’ów, połowa tokenów to surowy output narzędzi, który model musi re-czytać w każdej turze. Ewaluacje long-context publikowane przez 2025 i 2026 (post inżynierski Anthropica “Effective context engineering” oraz seria Chroma “context rot”) pokazują ten sam kształt: accuracy modelu na multi-hop reasoning zaczyna spadać przy 50k–80k tokenów i zauważalnie pogarsza się powyżej 200k, nawet gdy raw window rzekomo obsługuje milion. Przy 600k często pracujesz z lobotomizowanym modelem, który po prostu sprawia wrażenie głupszego.

Subagenty to fix, który skaluje. Subagent działa we własnym oknie kontekstu, z własnym system promptem i własnym allowlistem narzędzi; orchestrator nigdy nie widzi surowego outputu jego grep, Read ani bash — tylko strukturalne podsumowanie, które subagent decyduje się zwrócić. Zdeleguj jedną rundę “znajdź wszystkie miejsca wywołania Stripe.checkout.sessions.create” code-explorerowi na Haiku 4.5 i kontekst głównego agenta rośnie o ~1k tokenów (podsumowanie) zamiast ~40k (faktyczne odczyty). Odpal trzy takie explorery równolegle i przy okazji tniesz wall-clock time mniej więcej 3×, bo fan-out subagentów leci współbieżnie, podczas gdy orchestrator czeka. To cała gra: chroń budżet, który trzyma plan, mapę plików i aktywną edycję; wszystko inne outsource’uj.

Matematyka kosztu to wzmacnia. Subagenty na Haiku 4.5 ($1 in / $5 out za milion tokenów) kosztują mniej więcej jedną piątą tego co Sonnet 4.6 i jedną piętnastą tego co Opus 4.7. Odpalenie czterech równoległych explorerów Haiku, by zmapować feature, jest wciąż tańsze niż poproszenie Sonneta o przeczytanie tych samych plików w głównym wątku — a przy okazji trzymasz top-tier model świeżym do planowania i integracji. Pomiń subagenty i płacisz 3–5× więcej za zadanie oraz wcześniej w każdej sesji uderzasz w degradację kontekstu.

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-7. Test-authorzy i refactor-boty zwykle chodzą na claude-sonnet-4-6. Orchestrator zostaje na Sonnet i decyduje, do kogo delegować.
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. Plik agenta jest czytany przez Claude Code na starcie sesji; możesz też tworzyć i edytować je przez slash command /agents.

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-7. Większość pozostałych na claude-sonnet-4-6.
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ś.
Składnia Agent(<agent_type>) ogranicza, kto kogo może odpalać. 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. Ustawia skończone drzewo delegacji zamiast rekurencyjnej darmochy.
Cloud Agents mają zredukowaną powierzchnię. Tool task/subagent dostępny w lokalnych sesjach IDE nie jest wystawiony Cloud Agents na początku 2026, a na planach request-based niektóre flowy subagentów wymagają Max mode lub Composer 1.5. Jeśli odpalasz Cursora głównie w Cloud, strategia subagentów wciąż musi opierać się na lokalnych sesjach albo spadać do Claude Code.

Ograniczenia Codeksa

Codex CLI od OpenAI nie ma udokumentowanej architektury subagentów na maj 2026. Nie ma odpowiednika .codex/agents/, nie ma toolu delegacji subagentów na powierzchni narzędzi CLI, nie ma prymitywu “Task” ani “Explore”. Agenci Codeksa chodzą jako single-context agenty z tym tool surface, który skonfigurujesz. Jeśli Codex jest Twoim primary tool, nie masz ścieżki do max score na Q12 wewnątrz samego Codeksa — albo trzymasz Claude Code lub Cursor w pętli do pracy delegowanej, albo żyjesz z limitami single-context.

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

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.
Odpal /agents i utwórz plik. Slash command /agents w Claude Code wyscaffolduje plik markdown z frontmatter i pustym system promptem. Wybierz project scope (.claude/agents/), jeśli agent jest repo-specyficzny, user scope (~/.claude/agents/), jeśli chcesz go wszędzie.
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”).
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).
Pinuj model. Read-only / bulk-scan / klasyfikacja → claude-haiku-4-5-20251001. Partner Plan mode / architektura → claude-opus-4-7. Edytory i test-authorzy → claude-sonnet-4-6. Jeśli nie pinujesz, subagent dziedziczy model orchestratora i tracisz wygraną kosztową.
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.
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.
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/.
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. Domyślne zachowanie to dziedziczenie modelu po orchestratorze, czyli zwykle Sonnet. Code-reviewer na Sonnet kosztuje ~5× tyle co code-reviewer na Haiku przy ~zero zysku jakości. Pinuj model we frontmatter każdego agenta.
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.
Próba wciśnięcia subagentów do Codeksa. Codex nie ma prymitywu subagentów. Nie udawaj tego łańcuchami wywołań CLI; używaj Claude Code lub Cursora do pracy delegowanej, a Codeksa trzymaj do zadań single-context.
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-7 — 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.