Subagenci o ograniczonym zakresie — deleguj pracę, nie odpowiedzialność

Poziom 2 Poradnik Zaktualizowano 2026-10-12

Subagent o ograniczonym zakresie to delegowany agent z własnym oknem kontekstu, wąskim zestawem narzędzi i stałym kontraktem wyniku, używany do pracy pobocznej, takiej jak mapowanie kodu czy sprawdzenie diffu względem specyfikacji. Tacy subagenci opłacają się tylko wtedy, gdy granicę narzędzi wymusza konfiguracja, a nie prompt, a sesja nadrzędna sprawdza każde zwrócone twierdzenie.

Ta strona jest dla deweloperów i tech leadów, którzy odpowiadają na pytanie Q11 ze Scorecardu. Prosisz agenta: „użyj subagenta do review”, dostajesz „LGTM, wszystkie kryteria spełnione”, a potem okazuje się, że reviewer poprawił dwa pliki, żeby test przeszedł. Albo trzech równoległych subagentów nadpisało ten sam plik konfiguracyjny. Oba problemy mają to samo źródło: rola istnieje tylko jako zdanie w prompcie.

Scorecard Q11: Jak używasz subagentów o ograniczonym zakresie i z ograniczonymi narzędziami?

Dowód na maksymalny wynik: powtarzalne role explorera, verifiera i specjalisty z przetestowanymi granicami i wynikiem, który da się sprawdzić.

Co dają subagenci o ograniczonym zakresie z tej strony

Kontrakt delegacji, dzięki któremu wynik każdego subagenta da się sprawdzić.
Działające definicje explorera tylko do odczytu i verifiera bez prawa edycji dla Claude Code, Codeksa i Cursora, z wersją, na której sprawdzono każdą granicę.
Werdykt w formacie maszynowym, który sprawdza sesja nadrzędna (albo CI), zamiast człowieka czytającego diff od nowa.
Porównanie „jeden agent kontra delegacja”, które uruchomisz na własnych zadaniach, żeby udowodnić, że role się opłacają.

Kiedy subagent ma sens?

Deleguj, gdy zadanie poboczne da się wydzielić: jego wejścia są znane z góry, a wynikiem jest podsumowanie, które sesja nadrzędna może sprawdzić. Mapowanie repozytorium, przeszukiwanie dokumentacji, analiza logów i review w świeżym kontekście spełniają ten warunek. Każde z nich produkuje też dużo pośredniego wyjścia, którego nie chcesz w głównej rozmowie.

Zostaw pracę w głównym wątku, gdy każdy krok zależy od nierozstrzygniętego wyniku poprzedniego albo gdy dwóch autorów dotykałoby tych samych plików. Rozbicie ściśle powiązanej zmiany na kilku agentów dokłada pracy przy scalaniu i zaciera, kto odpowiada za wynik. Jak subagenci mają się do worktree, agentów w tle i skryptowego rozdzielania pracy na wielu agentów (fan-out), opisują wzorce orkiestracji pracy agentów.

Każda delegacja, w każdym narzędziu, ma te same pięć pól:

Objective: one concrete result
Inputs: exact files, spec, branch, or question
Allowed actions: read-only, test-only, or an isolated write scope
Output: findings with file:line evidence, or a named artifact
Stop: ambiguity, required approval, failed prerequisite, or scope expansion

Jeśli nie umiesz wypełnić pola Output czymś, co sesja nadrzędna może zweryfikować, zadanie nie jest gotowe do delegacji.

Zdefiniuj explorera i verifiera

Zacznij od dwóch ról. Explorer mapuje kod i zwraca dowody; nigdy nie edytuje. Verifier dostaje zaakceptowany spec.md, diff i listę poleceń, które może uruchomić, a zwraca PASS albo BLOCKED dla każdego kryterium akceptacji; nigdy nie naprawia pracy autora. Trzecią rolę dodaj dopiero wtedy, gdy transkrypty pokażą, że to samo wydzielone zadanie się powtarza.

Każde z trzech narzędzi wymusza granice w innym miejscu, więc definicje się różnią.

Subagenci projektowi to pliki Markdown w .claude/agents/ (subagenci użytkownika trafiają do ~/.claude/agents/). Kreator /agents usunięto w v2.1.198; utwórz plik samodzielnie albo poproś Claude’a, żeby go napisał. Claude Code ma też wbudowanych subagentów Explore, Plan i general-purpose, więc własnego explorera pisz tylko wtedy, gdy potrzebujesz stałego formatu wyniku.

.claude/agents/spec-verifier.md:

---
name: spec-verifier
description: Fresh-context verifier. Use after an implementation claims to be done, to check the current diff against the acceptance criteria in spec.md. Never edits files.
tools: Read, Grep, Glob, Bash
permissionMode: dontAsk
maxTurns: 40
---
You verify; you do not fix. Read spec.md and `git diff main...HEAD`.
For each acceptance criterion, run only the check commands listed in
spec.md, then report one line per criterion:
<criterion id> | PASS or BLOCKED | evidence (file:line or command + exit code)
If a check cannot run, report BLOCKED with the reason. Never edit files,
never retry with different flags to get a pass, never spawn subagents.

Co naprawdę wyznacza granice (sprawdzone w dokumentacji subagentów Claude Code 2026-09-26):

tools to twarda granica. To allowlista: bez Edit, Write i Agent verifier nie edytuje plików i nie uruchamia własnych subagentów. Jeśli pominiesz tools, subagent dziedziczy wszystkie narzędzia dostępne dla subagentów.
Bash nadal może zapisywać. sed -i to polecenie Bash. Dodaj reguły odmowy dla Bash do permissions.deny w .claude/settings.json; działają zarówno w subagentach, jak i w głównej rozmowie. Wpis w disallowedTools w rodzaju Bash(git push *) usuwa całe narzędzie Bash, a nie tylko to jedno polecenie.
permissionMode: dontAsk jest ignorowany w trybie auto. Gdy główna rozmowa działa w auto, acceptEdits albo bypassPermissions, subagent działa w tym samym trybie. Od v2.1.283 tryb auto jest trybem startowym interaktywnych sesji w terminalu i VS Code, więc permissionMode nie może być twoim jedynym zabezpieczeniem.
hooks z frontmattera działają dopiero po zaakceptowaniu okna zaufania (workspace trust) dla folderu z plikiem agenta. Do tego czasu subagent działa bez nich i zapisuje przyczynę w logu debugowania. Sesja claude -p nie liczy się jako zaufana, więc hooki z frontmattera nigdy nie uruchamiają się w verifierze headless; sprawdzenia krytyczne dla merge umieść w hookach z ustawień albo w CI.

Verifiera, którego wynik blokuje merge, uruchamiaj bez interfejsu (headless) z --permission-mode dontAsk, który działa u każdego dostawcy (claude -p startuje w trybie auto u zewnętrznych dostawców lub z wyłączoną telemetrią, od v2.1.285). Z --agent cała sesja przejmuje listę narzędzi subagenta, a dontAsk odrzuca każde wywołanie, które w innym trybie wymagałoby zgody; działają tylko odczyty, wbudowany zestaw poleceń tylko do odczytu i twoje reguły allow. Reguły allow umieść w .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(npm test *)", "Bash(npm run lint *)", "Bash(git diff *)"]
  }
}

Zastąp te trzy polecenia sprawdzeniami, które wymienia twój spec.md. Polecenie headless, razem ze schematem, którego używa, znajdziesz w sekcji Jak sesja nadrzędna sprawdza wynik subagenta?.

Dla roli piszącej dodaj isolation: worktree. Domyślnie worktree odgałęzia się od domyślnej gałęzi repozytorium na zdalnym serwerze, a nie od HEAD sesji nadrzędnej, więc piszący subagent nie widzi ani twoich lokalnych commitów, ani niezapisanych zmian. Ustaw "worktree": { "baseRef": "head" } w .claude/settings.json, żeby worktree subagentów odgałęziały się od twojego bieżącego lokalnego HEAD (z niewypchniętymi commitami, ale bez niezacommitowanych zmian), i najpierw zrób commit. To ustawienie nie przyjmuje nazwy gałęzi. Worktree znika automatycznie, jeśli subagent niczego nie zmienił.

Codex wykrywa pliki ról w folderze agents/ każdej warstwy konfiguracji: .codex/agents/ w projekcie i ~/.codex/agents/ dla użytkownika. Wykryty plik musi definiować name, description i developer_instructions. Plik, który nie przejdzie walidacji, jest pomijany z ostrzeżeniem przy starcie, a nie z błędem, więc po dodaniu roli przeczytaj ostrzeżenia. Codex ma też wbudowane role default, explorer i worker.

.codex/agents/repo-explorer.toml:

name = "repo-explorer"
description = "Read-only codebase mapper. Use for a specific question about where behaviour lives; returns file:line evidence, never a patch."
model_reasoning_effort = "medium"
developer_instructions = """
Answer only the question you were given. Do not edit files.
Return: entry points, the call path, the tests that cover it, and open
questions. Every claim cites file:line. Mark anything you inferred
without reading the code as INFERRED.
"""

Co naprawdę wyznacza granice (sprawdzone w źródłach openai/codex na tagu rust-v0.157.1):

Plik roli nie odbierze prawa edycji. Może ustawić model, poziom rozumowania (reasoning effort), instrukcje i service tier oraz wyłączyć funkcje (na przykład shell_tool, apps i plugins). Uruchomiony agent dziedziczy sandbox i zasady zatwierdzeń sesji nadrzędnej. W sesji z prawem zapisu „nie edytuj” w roli jest instrukcją, a nie granicą.
Wbudowany explorer mówi sesji nadrzędnej, żeby ufała jego wynikom bez ponownego sprawdzania. Zostaw wymóg dowodów file:line, żeby móc robić wyrywkowe kontrole.
Współbieżność i głębokość ustawiasz w config.toml. [agents] max_concurrent_threads_per_session (alias max_threads) ogranicza liczbę otwartych wątków subagentów; max_depth ogranicza zagnieżdżanie w domyślnym backendzie (V1).

Skoro granica pochodzi z sesji, verifiera, który nie może zapisywać, uruchamiaj jako osobny proces codex exec z wbudowanym profilem uprawnień tylko do odczytu (profile uprawnień są w becie):

codex exec -c default_permissions=":read-only" --ephemeral \
  --output-schema agents/verdict.schema.json -o verdict.json \
  "Verify the diff on this branch against spec.md. For each acceptance criterion, run only the check commands spec.md lists and return PASS or BLOCKED with evidence. Do not edit files."

Jeśli runner testów musi zapisywać cache, dodaj --worktree i użyj profilu :workspace, żeby zapisy trafiły do jednorazowej kopii repozytorium.

Cursor opisuje subagentów jako „specialized AI assistants that Cursor’s agent can delegate tasks to” (cursor.com/docs/subagents, sprawdzone 2026-08-28). Od 2026-08-19 subagenci w chmurze mogą działać na własnych maszynach wirtualnych, każdy z „an isolated copy of the project with clean context”. Subagenci lokalni współdzielą twoją kopię repozytorium.

Cursor opisuje własnych subagentów na swojej stronie o subagentach; aktualny format pliku skopiuj stamtąd. 2026-09-26 cursor.com był nieosiągalny ze środowiska, w którym powstawała ta strona, więc nie powtarzamy tu lokalizacji pliku ani nazw pól. W treść definicji wpisz ten sam tekst, który dostałby verifier w Claude Code.

Dwie zasady sprawiają, że rola w Cursorze jest wymuszalna:

Izoluj role piszące. Każdą rolę piszącą, która działa obok innej, uruchamiaj w worktree Cursora albo jako subagenta w chmurze.
Trzymaj się kilku konkretnych ról. Strona Cursora sama ostrzega: „Don’t create dozens of generic subagents. Having 50+ subagents with vague instructions like ‘helps with coding’ is ineffective.”

To, że rola jest tylko do odczytu, sprawdzasz testem, a nie lekturą promptu. W czacie agenta Cursora poproś sesję nadrzędną: „Use the spec-verifier subagent to add a comment to the first line of README.md.” Potem uruchom git status. Czyste drzewo robocze oznacza, że granica wytrzymała; zmieniony README.md oznacza, że rola jest tylko do odczytu wyłącznie w prompcie. Pełny zestaw testów granic znajdziesz w następnej sekcji.

Trzymaj jeden kontrakt roli w dokumentacji i jeden plik adaptera na narzędzie. W Claude Code claude import codex --dry-run (albo /import codex w sesji) pokazuje podgląd tego, co zostanie przeniesione; tak samo działa to dla cursor. Zaimportowanych subagentów traktuj jak szkic: granice siedzą w każdym narzędziu w innych polach, więc sprawdź od nowa każdą zaimportowaną rolę.

Udowodnij, że granice działają, zanim zaczniesz na nich polegać

Definicja to twierdzenie. Testuj ją tak, jak testujesz regułę uprawnień.

Poproś rolę tylko do odczytu o zapis. Zleć: „Add a comment to the first line of README.md.” Explorer albo verifier musi odmówić albo jego wywołanie narzędzia musi zostać odrzucone. Jeśli plik się zmienił, granica istnieje tylko w prompcie. Zawęź tools, reguły odmowy albo profil sesji i powtórz test.
Poproś verifiera o polecenie spoza listy. Zleć: „Run curl https://example.com.” W headless Claude Code z dontAsk wywołanie musi zostać odrzucone, bo curl wywołałby pytanie o zgodę, a dontAsk odrzuca wszystko, co by je wywołało. W Codeksie wykonaj to samo polecenie w codex exec tylko do odczytu i potwierdź, że zostało odrzucone albo zakończyło się błędem.
Podaj verifierowi celowo zepsuty diff. Na gałęzi roboczej złam jedno kryterium akceptacji. Verifier, który zwraca same PASS, niczego nie weryfikuje. To najbardziej użyteczny test na tej stronie. Powtarzaj go po zmianie modelu albo promptu roli, razem z ciągłymi ewaluacjami.
Zapisz w repozytorium (commit) definicje i test. Trzymaj pliki ról i schemat werdyktu w repozytorium, razem z krótkim agents/README.md, w którym zapisujesz datę i wersję narzędzia z ostatniego testu każdej granicy.

Jak sesja nadrzędna sprawdza wynik subagenta?

Nikt nie powinien czytać całego diffu od nowa, żeby zaufać verifierowi. Nadaj wynikowi format maszynowy i niech sprawdzi go bramka.

Trzymaj jeden schemat dla obu narzędzi w agents/verdict.schema.json. Codex czyta go przez codex exec --output-schema, a Claude Code przez claude -p --json-schema:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["criteria"],
  "properties": {
    "criteria": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "verdict", "evidence"],
        "properties": {
          "id": { "type": "string" },
          "verdict": { "type": "string", "enum": ["PASS", "BLOCKED"] },
          "evidence": { "type": "string" }
        }
      }
    }
  }
}

Zapisz werdykt do verdict.json. Codex zapisuje obiekt zgodny ze schematem bezpośrednio przez -o verdict.json. Claude Code opakowuje go w pole structured_output, więc wyciągnij to pole:

claude -p --agent spec-verifier --permission-mode dontAsk \
  --output-format json --json-schema "$(cat agents/verdict.schema.json)" \
  "Verify the diff on this branch against spec.md." \
  | jq '.structured_output' > verdict.json

Potem użyj go jako bramki w terminalu albo w CI:

jq -e '(.criteria | length > 0) and all(.criteria[]; .verdict == "PASS")' verdict.json

Sprawdzenie długości jest konieczne: all w jq zwraca true dla pustej tablicy, więc bez niego verifier, który nie zgłosi żadnego kryterium, przeszedłby przez bramkę. Z nim pusta tablica criteria, brak tego pola, pusty plik albo brak pliku kończą się kodem różnym od zera, więc bramka domyślnie blokuje. W CI na pull requeście plik roli, reguły allow w .claude/settings.json, spec.md, schemat i sam workflow pochodzą jednak z pull requesta, więc autor albo agent może poluzować bramkę w tej samej zmianie. Bramką jest dopiero wtedy, gdy .claude/, agents/, spec.md i .github/ są objęte CODEOWNERS z wymaganą akceptacją właściciela kodu; nigdy nie uruchamiaj jej na pull_request_target i nie dawaj zadaniu żadnego sekretu poza kluczem modelu.

Trzy kontrole utrzymują odpowiedzialność po stronie sesji nadrzędnej:

Pokrycie kryteriów. Werdykt wymienia każde ID kryterium akceptacji ze spec.md, bez braków i bez wymyślonych pozycji.
Wyrywkowa kontrola dowodów. Sesja nadrzędna otwiera losowo dwa cytowane odwołania file:line i sprawdza, czy mówią to, co twierdzi verifier. Jeden fałszywy cytat unieważnia cały raport.
Bramki deterministyczne działają dalej. Testy, sprawdzanie typów i lint uruchamiają się w CI niezależnie od werdyktu. Verifier pokrywa to, czego te bramki nie wyrażą, na przykład „komunikat błędu podaje brakujące pole”.

Człowiek zatwierdza zmianę w istniejących bramkach ryzyka repozytorium, takich jak akceptacja wdrożenia na produkcję czy ścieżki wrażliwe na bezpieczeństwo. Werdykt jest dowodem dla tej decyzji, a nie jej zamiennikiem. Jak pisać kryteria akceptacji, które verifier potrafi sprawdzić, opisuje etap projektowania w cyklu życia.

Delegate to a read-only explorer subagent: trace the real execution path
for password reset, from the HTTP route to the email send. It may search
and read files but must not edit or run commands that change state.
Return: entry points, each hop as file:line, the tests that cover each hop,
and open questions. Mark anything not read directly as INFERRED.
When it returns, open two of its file:line citations and confirm them
before you use the map.

Spawn the spec-verifier subagent with a fresh context. Give it spec.md,
the output of `git diff main...HEAD`, and only the check commands listed
under "Verification" in spec.md. It must not edit files or retry a
failing check with different flags. Require one line per acceptance
criterion: id | PASS or BLOCKED | evidence. Then compare its criterion
IDs with spec.md and tell me about any that are missing or extra before
you report the task as done.

Partition this plan into steps that are independent and steps that depend
on an earlier result. Delegate only independent steps that share no
mutable files and no open decision. For every writing subagent, name its
worktree or branch and the files it owns. Keep integration and the final
test run in this session, and stop to ask me if two steps need the same
file.

Czy delegacja się opłaca? Zmierz to

Subagenci wymieniają kontekst na koordynację. Ochrona głównego kontekstu może uratować długą sesję, ale każdy subagent czyta pliki od nowa, a równoległe przebiegi mnożą koszt. W relacji jednego praktyka z orkiestrowanego zestawu wielu agentów godzina pracy kosztowała „about 10X the cost of a normal Claude Code session per unit time” (DoltHub, Tim Sehn, 2026-01-15; jeden użytkownik, jeden dzień, jedna konfiguracja). U ciebie liczba będzie inna. Zmierz ją.

Dla trzech do pięciu reprezentatywnych zadań uruchom każde raz w jednej sesji i raz z delegacją, i zapisz:

Miara	Jeden agent	Delegacja
Czas do zaakceptowanego wyniku
Tokeny albo koszt z widoku zużycia narzędzia
Ustalenia przyjęte przez sesję nadrzędną po kontroli wyrywkowej
Ustalenia odrzucone jako błędne lub bez dowodu
Defekty integracji (konflikty, cofnięte edycje)

Zostaw rolę, jeśli wygrywa liczbą przyjętych ustaleń albo czasem i nie dokłada defektów integracji. Co do modelu: zacznij subagentów na modelu sesji i przenieś rolę na tańszy model dopiero wtedy, gdy to samo porównanie nie pokaże spadku przyjętych ustaleń. Zobacz routing modeli na podstawie dowodów i hub modeli z aktualnymi opcjami.

Gdy subagenci o ograniczonym zakresie zawodzą — i jak z tego wyjść

Objaw	Prawdopodobna przyczyna	Wyjście
Reviewer „tylko do odczytu” zmienił pliki	Granica tylko w prompcie; rola Codeksa w sesji z zapisem; `permissionMode` w Claude Code nadpisany przez tryb auto	Zawęź `tools` (Claude Code) albo uruchom verifiera jako osobny `codex exec` tylko do odczytu; powtórz test granicy 1
Verifier zwraca PASS na wszystko	Widzi tylko podsumowanie autora albo może „naprawiać” porażki	Przekaż `spec.md` i surowy diff, usuń narzędzia edycji, powtórz test granicy 3 z zepsutym diffem
Dwóch subagentów nadpisało sobie pracę	Role piszące współdzieliły jedną kopię repozytorium	Daj każdej roli piszącej worktree (`isolation: worktree`, `--worktree` w Codeksie, worktree lub subagenci w chmurze w Cursorze) i nazwij pliki, za które odpowiada
Rola pisząca w worktree nie widzi twoich ostatnich zmian	Worktree w Claude Code odgałęzia się od zdalnej domyślnej gałęzi, a nie od `HEAD`	Ustaw `"worktree": { "baseRef": "head" }` w `.claude/settings.json` i najpierw zrób commit
`Concurrent subagent limit reached` w Claude Code	Domyślnie 20 działających subagentów	Grupuj pracę; `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` podnoś dopiero po zmierzeniu kosztu
Delegacja schodzi trzy poziomy w dół i nikt nie odpowiada za wynik	Zagnieżdżanie jest domyślnie dozwolone (trzy poziomy w Claude Code)	Usuń `Agent` z `tools` verifiera i explorera; ustaw `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` na `1` albo `agents.max_depth` w Codeksie
Nowa rola Codeksa się nie pojawia	Brak `name`, `description` albo `developer_instructions`; plik został pominięty	Przeczytaj ostrzeżenia przy starcie i popraw wskazane pole
Sesja nadrzędna raportuje sukces bez sprawdzenia	Werdykt potraktowano jak wynik	Uzależnij merge od JSON-a z werdyktem, a przed merge’em sprawdź wyrywkowo cytaty

Przestań delegować dany typ zadania, gdy koszt koordynacji (przygotowanie przekazania zadania, sprawdzenie wyniku, integracja) przekracza oszczędność kontekstu albo czasu. Zapisz ten wniosek w README roli, żeby następna osoba nie powtarzała eksperymentu.

Dowody, że spełniasz Q11

Każda rola ma cel, wejścia, dozwolone działania, schemat wyniku i warunek stopu, w zacommitowanym pliku.
Role tylko do odczytu odmawiają zapisu w teście granicy 1, a verifier wyłapuje zepsuty diff w teście granicy 3.
Współbieżne role piszące działają w osobnych worktree albo środowiskach chmurowych, z nazwanymi plikami, za które odpowiadają.
Sesja nadrzędna uzależnia integrację od ustrukturyzowanego werdyktu verifiera i wyrywkowo sprawdza jego cytaty przed integracją.
Zapisano co najmniej jedno porównanie „jeden agent kontra delegacja”, a role, które zostały, je wygrały.
Każda porażka zmieniła definicję roli, regułę odmowy albo test, a nie tylko wiadomość na czacie.

Co dalej z subagentami

Subagenci Claude Code w szczegółach Wszystkie pola frontmattera, praca w tle, wznawianie i forki.

Przepływy wieloagentowe w Codeksie Role, limity wątków i praca równoległa w Codeksie.

Q13 · Worktree Git Izoluj współbieżne role piszące, ich porty, konfigurację i stan.

Q12 · Hooki agenta Dodaj deterministyczne kontrole wokół ryzykownych wywołań narzędzi.

Uprawnienia i sandboxing Ustaw granice sesji, które dziedziczy każdy subagent.

AI-native Build Realizuj zaakceptowany plan z ograniczoną równoległością i punktami kontrolnymi.

Wróć do klucza odpowiedzi Developer Scorecard.