Własne subagenty w Claude Code: wyspecjalizowani pomocnicy, których pracę da się sprawdzić

Własny subagent w Claude Code to plik Markdown w .claude/agents/ (projekt) lub ~/.claude/agents/ (konto osobiste). Frontmatter YAML ustala nazwę, opis delegowania, narzędzia, model i uprawnienia, a treść pliku staje się promptem systemowym. Każdy subagent działa we własnym oknie kontekstu i zwraca tylko podsumowanie, więc głośna praca poboczna nie zaśmieca głównej rozmowy.

Po czterdziestu minutach refaktoryzacji twoja sesja mieści trzy pełne przebiegi testów, dwa przeszukania całego repozytorium grepem i log migracji. Ograniczenie ustalone na początku („nie ruszaj publicznego API”) ginie pod tym wszystkim, a przegląd, którego teraz potrzebujesz, walczyłby o ten sam kontekst. Ta strona jest dla deweloperów, którzy chcą oddać taką pracę poboczną wyspecjalizowanym pomocnikom, oraz dla tech leadów, którzy commitują wspólny zestaw subagentów do repozytorium i potrzebują, żeby działał tak samo u ośmiu osób.

Co daje dobrze ustawiony zestaw subagentów

Trzy pliki subagentów do zacommitowania od razu: recenzent tylko do odczytu, który zwraca werdykt, tani runner testów raportujący wyłącznie błędy i wykonawca, który edytuje we własnym worktree gita.
Trzydziestolinijkowy test w CI, który łapie błędy frontmattera pomijane przez Claude Code bez żadnego komunikatu.
Zasadę wyboru modelu i poziomu effort dla każdego subagenta oraz sposób, żeby sprawdzić, co faktycznie się uruchomiło.
Procedurę weryfikacji, w której raport subagenta jest twierdzeniem do sprawdzenia, a nie dowodem.
Tabelę objaw → przyczyna → naprawa dla awarii, które zdarzają się w praktyce.

Kiedy subagent, a kiedy skill, fork albo sesja w tle?

Subagent startuje z czystym kontekstem i odsyła jedno podsumowanie. To dobry kształt dla samodzielnej pracy, która generuje dużo wyjścia, do którego już nie wrócisz. To zły kształt dla pracy wymagającej historii rozmowy albo ciągłej wymiany zdań.

Potrzebujesz…	Użyj	Dlaczego
Głośnego, samodzielnego zadania pobocznego: testy, analiza logów, przeszukanie kodu	Własnego subagenta	Własne okno kontekstu, własne limity narzędzi, wraca tylko podsumowanie
Powtarzalnej procedury, która ma działać z całą dotychczasową rozmową	Skilla	Skille działają w kontekście głównej rozmowy
Zadania pobocznego, które potrzebuje całej rozmowy bez ponownego tłumaczenia	Forka: `/subtask <zadanie>` (v2.1.212+)	Fork dziedziczy rozmowę i korzysta z prompt cache rodzica
Kilku niezależnych zadań, które nadzorujesz, każde we własnej sesji	Agent view (`claude agents`, `claude --bg`)	Osobne sesje, osobne worktree, jeden panel
Dziesiątek agentów sterowanych skryptem, który można uruchomić ponownie	Dynamicznych workflowów	Orkiestracja żyje w kodzie, a nie w jednej rozmowie
Szybkiego pytania o coś, co już jest w rozmowie	`/btw`	Widzi twój kontekst, nie ma narzędzi, odpowiedź nie trafia do historii

Claude Code ma też wbudowane subagenty: Explore i Plan (badanie kodu tylko do odczytu) oraz general-purpose (może edytować). Własny subagent ma sens, gdy wciąż uruchamiasz ten sam rodzaj pomocnika z tymi samymi instrukcjami i tymi samymi ograniczeniami.

Jak zbudowany jest plik subagenta?

Subagent to jeden plik Markdown. Wymagane są tylko name i description:

---
name: code-reviewer
description: Reviews the current branch's changes for correctness and security. Use proactively before a commit or pull request.
tools: Read, Grep, Glob, Bash
---

You review code. You never edit files. Report findings with file and line.

Treść pliku zastępuje dla tego subagenta prompt systemowy Claude Code: subagent dostaje twój tekst plus podstawowe informacje o środowisku, takie jak katalog roboczy. Tożsamość wyznacza name; nazwa pliku i podkatalog w agents/ nie mają znaczenia.

Gdzie leżą pliki subagentów i który wygrywa

Gdy dwie definicje mają tę samą name, Claude Code bierze tę z lokalizacji o wyższym priorytecie:

Priorytet	Lokalizacja	Zasięg
1 (najwyższy)	Managed settings	Cała organizacja, ustawia administrator
2	Flaga `--agents '{…}'` z JSON-em	Tylko bieżąca sesja
3	`.claude/agents/`	Ten projekt; commituj go
4	`~/.claude/agents/`	Wszystkie twoje projekty
5 (najniższy)	Katalog `agents/` pluginu	Tam, gdzie plugin jest włączony

Claude Code obserwuje katalogi agents projektu i użytkownika, więc zmiana działa przy następnym delegowaniu bez restartu. Wyjątek: jeśli katalog nie istniał w chwili startu sesji, po utworzeniu pierwszego pliku zrestartuj ją raz.

Co widzi subagent na starcie?

Subagent, który nie jest forkiem, startuje z:

własnym promptem systemowym (treścią pliku) i informacjami o środowisku;
wiadomością z zadaniem, którą Claude pisze przy delegowaniu. To jedyny kanał dla wszystkiego, co dotyczy bieżącej pracy;
twoimi plikami CLAUDE.md, na każdym poziomie ładowanym przez główną rozmowę, łącznie z AGENTS.md wczytanym jako instrukcje projektu. Ustaw omitClaudeMd: true (v2.1.271+), żeby pominąć pliki CLAUDE.md użytkownika, projektu i lokalne (pliki polityki z managed settings nadal się ładują) w subagencie, który potrzebuje wyłącznie zadania;
migawką stanu gita i pełną treścią skilli wymienionych w polu skills.

Nie widzi historii rozmowy, plików, które Claude już przeczytał, auto memory głównej sesji ani twojego stylu wyjścia. Reguła, którą podałeś na czacie dziesięć minut temu, nie dotrze więc do subagenta, jeśli nie ma jej w CLAUDE.md, we własnym prompcie subagenta albo w wiadomości delegującej. Gdzie leży każdy poziom CLAUDE.md i co do niego wpisać, opisuje system pamięci.

Zbuduj trzy subagenty, które kończą się dowodem

Trzy pliki poniżej pokrywają typowy podział: jeden subagent ocenia, drugi uruchamia sprawdzenia, trzeci edytuje w izolacji. Każdy prompt kończy się stałym formatem raportu, bo właśnie stały format pozwala sprawdzić wynik bez czytania transkryptu.

Utwórz recenzenta. Może czytać i uruchamiać polecenia, ale nie może zapisywać ani edytować plików, więc nie „naprawi” testu, żeby jego własny werdykt stał się prawdą.

---
name: code-reviewer
description: Reviews the diff against main for correctness, security and missing tests. Use proactively before a commit or pull request.
tools: Read, Grep, Glob, Bash
disallowedTools: Write, Edit, NotebookEdit
model: inherit
---

You review the changes between the merge base with main and the working tree.
You never modify files.

1. Run `git diff --merge-base main --stat`, then read every changed file in full.
2. Check behaviour, not style: wrong logic, unhandled errors, injection,
   authorization gaps, and changed behaviour without a test that covers it.
3. For every finding, run or name the command or test that demonstrates it.

Reply in exactly this format and nothing else:
VERDICT: APPROVE | REQUEST_CHANGES
FINDINGS:
- [blocker|major|minor] path/to/file.ts:LINE: what is wrong. Evidence: <command or test>
CHECKED: <each command you ran, with its exit code>

Skip anything a linter or formatter would catch. If you found nothing,
say so and list what you checked.

Bash wciąż może zmieniać pliki poleceniami powłoki. Jeśli recenzent ma być ściśle tylko do odczytu, usuń Bash i przekaż diff w wiadomości delegującej albo dodaj reguły permissions.deny dla poleceń, których się obawiasz.

Utwórz runner testów. Wyjście testów to klasyczne zalewanie kontekstu. Ten subagent działa na aliasie haiku, bo praca jest mechaniczna i masowa.

---
name: test-runner
description: Runs tests and reports only the failures. Use whenever a test command would print more than a screen of output.
tools: Bash, Read, Grep, Glob
model: haiku
maxTurns: 15
---

Run the test command given in the task. If none is given, use the project's
default test script from package.json, pyproject.toml or the Makefile.
Never edit a file.

Reply in exactly this format:
COMMAND: <the exact command>
EXIT: <exit code>
RESULT: <passed> passed, <failed> failed, <skipped> skipped
FAILURES:
- <test name> at path:LINE: <assertion message, first 3 lines>

Before you call a failure flaky, re-run that one test once and report both runs.

Utwórz izolowanego wykonawcę do pracy równoległej. isolation: worktree daje każdemu uruchomieniu własny tymczasowy worktree gita, więc równolegli wykonawcy nie nadpisują sobie nawzajem zmian.

---
name: migration-worker
description: Applies one mechanical change (a rename, an API migration) to the files named in the task. Use for parallel fan-out across modules.
tools: Read, Edit, Write, Grep, Glob, Bash
isolation: worktree
model: sonnet
effort: medium
---

Make only the change the task describes, only in the files it names.
Then run the type check and the tests that cover the changed files.
Commit on your worktree branch with a message that names the change.

Reply with: BRANCH, FILES CHANGED, and every command you ran with its exit code.
If a check fails and the fix is outside your files, stop and report it.

Worktree subagenta odgałęzia się od domyślnej gałęzi repozytorium, a nie od twojego bieżącego HEAD. Jeśli wykonawcy mają pracować na niewypchniętych commitach twojej gałęzi, ustaw w .claude/settings.json:

{
  "worktree": { "baseRef": "head" }
}

Dodaj lint dla plików. Claude Code pomija plik subagenta bez żadnego komunikatu w sesji, gdy frontmatter się nie parsuje, gdy --- nie stoi w pierwszej linii albo gdy brakuje name lub description. Po cichu ignoruje też nieznane pola, więc disallowed_tools zamiast disallowedTools niczego nie odbiera. Zapisz to jako scripts/lint_agents.py (wymaga pyyaml):

#!/usr/bin/env python3
"""Fail CI when a subagent file would be skipped or would silently ignore a field."""
import pathlib, sys, yaml

KNOWN = {"name", "description", "tools", "disallowedTools", "model", "permissionMode",
         "maxTurns", "skills", "mcpServers", "hooks", "memory", "background",
         "omitClaudeMd", "effort", "isolation", "color", "initialPrompt", "experimental"}
errors = []
for path in sorted(pathlib.Path(".claude/agents").rglob("*.md")):
    text = path.read_text(encoding="utf-8").replace("\r\n", "\n")
    if not text.startswith("---\n"):
        print(f"warning: {path}: no frontmatter, so Claude Code treats it as a doc")
        continue
    try:
        meta = yaml.safe_load(text.split("---\n", 2)[1]) or {}
    except yaml.YAMLError as exc:
        errors.append(f"{path}: YAML does not parse: {exc}")
        continue
    if not isinstance(meta, dict):
        errors.append(f"{path}: frontmatter must be a YAML mapping")
        continue
    name = str(meta.get("name", ""))
    if not name or not meta.get("description"):
        errors.append(f"{path}: needs both name and description")
    if name.startswith("-") or ":" in name:
        errors.append(f"{path}: name must not start with '-' or contain ':'")
    for key in sorted(set(meta) - KNOWN):
        errors.append(f"{path}: unknown field '{key}' (ignored at runtime)")
print("\n".join(errors) or "agents OK")
sys.exit(1 if errors else 0)

Uruchamiaj go w tym samym jobie CI co linter. Job nie potrzebuje żadnych sekretów, a tylko dostępu do odczytu:

name: agent-config
on: [pull_request]
permissions:
  contents: read
jobs:
  lint-agents:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - run: pip install pyyaml && python3 scripts/lint_agents.py

Przy pull_request GitHub uruchamia ten workflow i scripts/lint_agents.py z samego pull requesta, więc pull request może zmienić kontrolę w tym samym diffie co plik agenta. Obejmij .github/ i scripts/lint_agents.py wpisem w CODEOWNERS razem z .claude/agents/ i wymagaj przeglądu code ownera w ochronie gałęzi.

Dokumentacja producenta proponuje do tego claude plugin validate .claude/agents. Na v2.1.283 polecenie wypisało „Validation passed” dla katalogu z plikiem o zepsutym YAML-u, plikiem z literówką w nazwie pola i plikiem bez name, także z --strict (test z 2026-09-26), więc na razie nie polegaj na nim przy plikach agentów projektu.

Wypróbuj. Zacommituj trzy pliki i skrypt, a potem wklej pierwszy prompt z sekcji z gotowymi promptami poniżej. W transkrypcie delegowanie widać jako wiersz w rodzaju code-reviewer(Review the diff). Uruchom /tasks w trakcie pracy subagenta, żeby zobaczyć jego wiersz i model, na którym działa.

Jak sprawić, żeby Claude wybrał właściwego subagenta?

Claude wybiera subagenta na podstawie jego description, więc pisz opis jak regułę routingu: co subagent robi i jaka sytuacja ma go uruchomić. Sformułowanie „Use proactively after code changes” zachęca do automatycznego delegowania. Opisy trzymaj krótkie: gdy łączna długość opisów twoich subagentów przekroczy 15 000 tokenów, Claude Code ostrzega przy starcie, a każdy z tych tokenów siedzi w głównym kontekście.

Gdy routing ma znaczenie, przestań na nim polegać. Masz trzy poziomy kontroli:

Jak	Co gwarantuje
Nazwa w prompcie: „Use the test-runner subagent…”	Nic: Claude zwykle deleguje, ale decyduje sam
@-wzmianka: wpisz `@` i wybierz go albo napisz `@agent-test-runner`	Ten subagent uruchomi się dla tego zadania; wiadomość z zadaniem nadal pisze Claude
Cała sesja: `claude --agent code-reviewer` albo `"agent": "code-reviewer"` w `.claude/settings.json`	Główny wątek sam przejmuje prompt, narzędzia i model subagenta

--agent łączy się z sesjami w tle: claude --agent code-reviewer --bg "review the open changes on this branch" uruchamia recenzenta jako osobną sesję, którą potem zarządzasz w agent view. W polu wysyłania agent view prompt, którego pierwsze słowo pasuje do nazwy subagenta, uruchamia tego subagenta, więc prompt zaczynający się od „test-runner” nie jest zwykłym tekstem.

Żeby Claude w ogóle nie używał danego subagenta, zablokuj go w ustawieniach dokładną nazwą:

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(migration-worker)"]
  }
}

Kontroluj, do czego subagent ma dostęp

Pole tools to lista dozwolonych, a disallowedTools to lista zakazanych; gdy ustawisz oba, najpierw działa lista zakazanych. O tym, czy ograniczenie trzyma, decydują cztery reguły:

Specyfikator usuwa całe narzędzie. disallowedTools: Bash(git push *) odbiera cały Bash, a nie tylko git push. Żeby zostawić Bash i zablokować jedno polecenie, dodaj Bash(git push *) do permissions.deny w ustawieniach; ta reguła obejmuje główną rozmowę i każdego subagenta.
permissionMode często jest ignorowane. Gdy główna rozmowa działa w trybie auto, acceptEdits albo bypassPermissions, subagent działa w tym samym trybie niezależnie od zapisu w pliku. Od v2.1.283 (kanał latest) tryb auto jest trybem startowym sesji interaktywnych, chyba że plik ustawień wskazuje inny tryb domyślny, więc w praktyce realnymi limitami są lista tools i reguły deny. Subagent, który deklaruje bypassPermissions, nigdy nie dostaje więcej niż główna rozmowa.
Subagenty w tle mają mniej narzędzi. W sesji interaktywnej tryb forków jest domyślnie włączony i Claude Code uruchamia subagenty tworzone przez Claude w tle. Subagent w tle zachowuje wszystkie narzędzia MCP, ale tylko stały zestaw narzędzi wbudowanych (m.in. Read, Grep, Glob, Bash, Edit, Write, WebFetch i Skill). Ten sam plik może więc działać na pierwszym planie, a w tle nie mieć jakiegoś narzędzia. Jego prośby o uprawnienia pojawiają się w głównej sesji, a odpowiedź „na resztę sesji” obowiązuje wtedy w całej sesji.
Subagenty z pluginów tracą trzy pola. Subagent pochodzący z pluginu ignoruje hooks, mcpServers i permissionMode. Jeśli ich potrzebujesz, skopiuj plik do .claude/agents/.

Dwa pola dodają możliwości bez obciążania głównej sesji kontekstem. mcpServers z definicją serwera wpisaną w pliku łączy ten serwer tylko na czas pracy subagenta, więc opisy jego narzędzi nigdy nie trafiają do głównej rozmowy. hooks we frontmatterze działają tylko wtedy, gdy ten subagent jest aktywny, na przykład hook PreToolUse blokujący zapisy SQL w subagencie czytającym bazę. Oba ładują się z pliku w projektowym .claude/agents/ dopiero po zaakceptowaniu okna zaufania dla tego folderu; uruchomienie claude -p nie liczy się jako zaufane.

Wybierz model i effort dla każdego subagenta

Claude Code ustala model subagenta w tej kolejności: model przekazany przez Claude dla tego jednego wywołania, potem pole model w pliku, potem zmienna środowiskowa CLAUDE_CODE_SUBAGENT_MODEL, na końcu model głównej rozmowy. Pole przyjmuje inherit, alias (opus, sonnet, haiku, fable) albo pełny identyfikator modelu.

Stosuj tę samą zasadę co w całym serwisie: zacznij od domyślnego modelu, najpierw stroj effort, a model zmieniaj dopiero wtedy, gdy przemawiają za tym twoje własne wyniki.

Pracę wymagającą osądu (przegląd, krytyka projektu, debugowanie) zostaw na inherit. Na kanale latest oznacza to domyślnie Claude Opus 5.5; na stable (v2.1.274) domyślny model zależy od planu.
Pracę mechaniczną i masową (testy, analiza logów, zmiany nazw w wielu plikach) przenieś na sonnet albo haiku, a zanim zmienisz model, ustaw effort dla subagenta.
fable zostaw na najdłuższe zadania i wybieraj go świadomie.

Ceny i okna kontekstu modeli znajdziesz w porównaniu modeli.

Dwie niespodzianki warte zapamiętania. Po pierwsze, alias z tej samej rodziny co model głównej rozmowy wskazuje na model główny: gdy sesja działa na Opus 5.5, model: opus uruchamia Opus 5.5, a nie to, na co alias wskazuje gdzie indziej. Po drugie, CLAUDE_CODE_SUBAGENT_MODEL to tylko wartość domyślna; żeby wymusić jeden model na wszystkich subagentach, ustaw też CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (v2.1.257+). Wynik sprawdź w /tasks, które pokazuje model w wierszu każdego działającego subagenta.

Koszt wynika z samej konstrukcji: każdy subagent wysyła własne zapytania, liczone do tych samych limitów użycia co główna rozmowa, a każde zwrócone podsumowanie ląduje w głównym kontekście. Stały, krótki format odpowiedzi (jak w trzech plikach powyżej) ogranicza ten drugi koszt. Budżety dla całego zespołu opisuje strona o kontroli kosztów w Claude Code.

Jak zweryfikować to, co raportuje subagent?

Raport subagenta to twierdzenie napisane przez model, którego pracy nie oglądałeś. Traktuj go tak jak „testy przechodzą” napisane przez kolegę na czacie: przydatne, ale sprawdzone, zanim się liczy.

Wymagaj dowodów w formacie. Każde znalezisko musi mieć ścieżka:linia oraz polecenie albo test, który je pokazuje. Znalezisko bez dowodu to pytanie, a nie blocker.
Decydujące sprawdzenie uruchom sam. Gdy runner testów zgłasza „0 failed”, niech główna sesja raz uruchomi to samo polecenie i porówna kody wyjścia. To jedno polecenie, a nie ponowne czytanie całości.
Oddziel autora od sędziego. Sesja, która napisała kod, nie powinna go oceniać. Recenzent powyżej nie ma Write ani Edit, więc nie zmieni testu, żeby jego werdykt stał się prawdą. O testach, których agent implementujący nie może osłabić, przeczytasz na stronie o ochronie wyroczni.
Trzymaj bramkę poza agentem. CI uruchamia sprawdzanie typów, lint i testy na pull requeście. APPROVE subagenta pomaga w decyzji o merge’u, ale nigdy nie zastępuje CI. Merge zatwierdza deweloper, który otwiera pull request, a tech lead jest właścicielem .claude/agents/ przez CODEOWNERS.
Czytaj znacznik skanowania. Od v2.1.210 Claude Code skanuje każdy raport subagenta i dopisuje na początku wiersz ze znacznikiem, gdy tekst naśladuje wewnętrzne tagi Claude Code albo wspomina ustawienia uprawnień, takie jak bypassPermissions. Recenzja, która namawia do poluzowania uprawnień, jest informacją o przeczytanych danych wejściowych, a nie radą.
Zachowaj ślad audytowy. Transkrypty subagentów są zapisywane jako ~/.claude/projects/<project>/<session-id>/subagents/agent-<agent-id>.jsonl i usuwane po cleanupPeriodDays (domyślnie 30 dni). Hook SubagentStop w settings.json może skopiować końcowy raport w trwałe miejsce.

Metodę stojącą za tym podejściem (jawne wejścia, ograniczony zestaw narzędzi, stały format wyniku i warunek zatrzymania) opisuje strona subagenty z zakresem: deleguj ograniczoną pracę, nie odpowiedzialność.

Gotowe prompty dla własnych subagentów

Create three project subagents in .claude/agents/ for this repository:
code-reviewer (read-only: tools Read, Grep, Glob, Bash; disallowedTools Write, Edit,
NotebookEdit; model inherit), test-runner (tools Bash, Read, Grep, Glob; model haiku;
maxTurns 15) and migration-worker (isolation: worktree; model sonnet; effort medium).
Use this repository's real test, type-check and lint commands in their prompts.
End every prompt with a fixed reply format: a verdict or result line, findings with
path:line and the command that proves each one, and the commands run with exit codes.
Keep each description under 40 words and make it say when to delegate. Show me the
three files before you write them.

@agent-code-reviewer Review my changes against main before I open a pull request.
Focus on src/billing/ and anything that calls it. Treat unparameterized SQL, a
secret in code or config, and changed behaviour without a covering test as blockers.
When it reports back, re-run every command listed under Evidence for blocker and
major findings yourself, and tell me which findings you reproduced and which you did not.

Use the test-runner subagent to run the full test suite, then the type check.
Send me only its report. If anything failed, do not fix it yet: group the failures
by root cause, and for each group name the smallest file set a fix would touch.

Split the migration from moment to date-fns across src/ into independent batches of
at most 10 files, grouped by directory. Run one migration-worker subagent per batch,
in parallel. When all have reported, list each worker's branch, merge the branches
into a new branch named chore/date-fns, run the full test suite once on the result,
and report any batch whose own checks or the combined run failed.

Udostępnij subagenty zespołowi

Jedno repozytorium: zacommituj .claude/agents/ i dodaj dla niego wpis w CODEOWNERS, żeby zmiana reguł wspólnego recenzenta przechodziła taki sam przegląd jak zmiana w CI.
Pomocnicy osobiści: trzymaj ich w ~/.claude/agents/. Plik projektowy o tej samej name nadpisuje osobisty.
Wiele repozytoriów: spakuj subagenty w plugin i instaluj go z zespołowego marketplace’u; zobacz pluginy Claude Code. Subagenty z pluginów pojawiają się na liście @-wzmianek pod nazwą z zakresem, np. my-plugin:code-reviewer. claude plugin eval mierzy, jak niezawodnie Claude deleguje do subagentów pluginu na zestawie promptów.
Cała organizacja: administratorzy umieszczają pliki w .claude/agents/ w katalogu managed settings; nadpisują one definicje projektowe i użytkownika o tej samej nazwie.
Przejście z innego narzędzia: /import codex, /import cursor albo /import gemini przenosi subagenty tego narzędzia razem z jego plikami instrukcji, poleceniami i serwerami MCP.

Codex i Cursor mają własne funkcje subagentów. Odpowiednik dla Codeksa opisuje strona orkiestracja wielu agentów Codeksa, a przewodnik po subagentach z zakresem porównuje wszystkie trzy narzędzia.

Gdy własne subagenty zawodzą

Objaw	Prawdopodobna przyczyna	Naprawa
Subagent nigdy nie jest wybierany	Opis jest mglisty, pokrywa się z innym albo ginie w dużym budżecie opisów	Przepisz go jako regułę routingu; gdy subagent musi się uruchomić, użyj @-wzmianki
Subagenta nie ma w sesji	Frontmatter się nie parsuje, `---` nie stoi w pierwszej linii, brakuje `name` lub `description` albo `name` zawiera `:`	Uruchom `claude --debug` i przeczytaj log; dodaj skrypt lintujący do CI
Pole nic nie zmienia	Klucz ma literówkę albo złą wielkość liter (`disallowed_tools`, `permission_mode`)	Używaj nazw w camelCase; skrypt lintujący zgłasza nieznane klucze
„Agent would be spawned with zero tools”	Każdy wpis w `tools` ma literówkę albo wskazuje narzędzie niedostępne dla subagentów	Popraw nazwy; porównaj z narzędziami, które faktycznie ma główna sesja
Na pierwszym planie działa, w tle brakuje narzędzia	Subagenty w tle zachowują tylko stały zestaw narzędzi wbudowanych	Używaj narzędzi z tego zestawu albo ustaw `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` dla tego uruchomienia
`permissionMode: plan` nie zatrzymał edycji	Główna sesja była w trybie auto, `acceptEdits` albo `bypassPermissions`, które nadpisują to pole	Usuń `Write` i `Edit` z `tools`; dodaj reguły deny w ustawieniach
Wykonawca w worktree nie widzi twoich ostatnich commitów	Worktree subagentów odgałęziają się od domyślnej gałęzi	Ustaw `worktree.baseRef` na `"head"` albo najpierw wypchnij gałąź bazową
Hooki z frontmattera lub serwery MCP z pliku nie działają	Folder z plikiem agenta nie jest zaufany; sesje `-p` się nie liczą	Otwórz sesję interaktywną w tym folderze i zaakceptuj okno zaufania
Nowy subagent jest „not found”	Katalog `agents` powstał po starcie sesji	Zrestartuj Claude Code raz
Subagent działa na innym modelu niż w pliku	Rozwiązywanie aliasu z tej samej rodziny, `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` albo podstawienie z listy `availableModels`	Sprawdź model w `/tasks`; jeśli potrzebujesz dokładnie tego modelu, podaj pełny identyfikator
„Concurrent subagent limit reached”	W sesji działa już 20 subagentów (wartość domyślna)	Poczekaj, aż część skończy, podziel pracę na partie albo podnieś `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`
Główny kontekst i tak się zapełnia	Każdy subagent zwraca długi raport w dowolnej formie	Dodaj stały, krótki format odpowiedzi na końcu promptu każdego subagenta

Dokąd dalej z własnymi subagentami

Agent view Uruchom subagenta jako osobną sesję w tle i zarządzaj wieloma sesjami z jednego panelu.

Własne polecenia i skille Spakuj procedurę działającą w głównej rozmowie i wczytaj ją do subagenta polem skills.

Hooki i automatyzacja Używaj hooków SubagentStart, SubagentStop i PreToolUse, żeby deterministycznie logować i ograniczać subagenty.

Dynamiczne workflowy Orkiestruj dziesiątki agentów ze skryptu, który można uruchomić ponownie, zamiast z jednej rozmowy.