Architektura agentów: tworzenie środowisk programistycznych opartych na AI

TL;DR: Claude Code nie jest oknem czatu z dostępem do plików. To programowalne środowisko uruchomieniowe z 31 udokumentowanymi zdarzeniami cyklu życia, z których każde można podpiąć do skryptów powłoki, których model nie może pominąć. Łącząc hooks w dispatchers, dispatchers w skills, skills w agents, a agents w workflows, otrzymuje się autonomiczny harness programistyczny, który egzekwuje ograniczenia, deleguje pracę, utrwala pamięć między sesjami i orkiestruje wieloagentowe deliberacje. Dynamic workflows Claude Code (v2.1.154+) uczyniły deterministyczną wieloagentową orkiestrację natywnym mechanizmem — od dziesiątek do setek agentów działających w tle przez /workflows — a platforma uruchamia teraz subagents domyślnie w tle (20 równoczesnych, zagnieżdżanie do głębokości 3), pozwala sesjom przesyłać sobie wiadomości jako równorzędnym uczestnikom (v2.1.224) oraz wykonuje sesje chmurowe na self-hosted runners. Za poprawność nadal odpowiadają hooks i evidence gates.⁵²⁵³⁸⁷ Ten przewodnik omawia każdą warstwę tego stosu: od pojedynczego hooka po 10-agentowy system konsensusu. Bez wymaganych frameworków. Wyłącznie bash i JSON.

Andrej Karpathy ukuł termin opisujący to, co narasta wokół agenta LLM: claws. To hooks, skrypty i orkiestracja, które pozwalają agentowi chwytać świat poza jego oknem kontekstowym.¹ Większość programistów traktuje agentów AI do programowania jak interaktywnych asystentów. Wpisują prompt, obserwują edycję pliku i przechodzą dalej. Takie podejście ogranicza produktywność do tego, co można osobiście nadzorować.

Model mentalny infrastruktury jest inny: agent AI do programowania to programowalne środowisko uruchomieniowe z jądrem LLM. Każde działanie modelu przechodzi przez kontrolowane przez Pana/Panią hooks. Definiuje Pan/Pani zasady, a nie prompty. Model działa w ramach infrastruktury tak samo, jak serwer WWW działa w ramach reguł nginx. Nie siedzi Pan/Pani przy nginx i nie wpisuje żądań. Konfiguruje go Pan/Pani, wdraża i monitoruje.

To rozróżnienie ma znaczenie, ponieważ infrastruktura się kumuluje. Hook blokujący dane uwierzytelniające w poleceniach bash chroni każdą sesję, każdego agenta i każde autonomiczne uruchomienie. Skill kodujący kryteria oceny jest stosowany konsekwentnie niezależnie od tego, czy wywołuje go Pan/Pani, czy agent. Agent sprawdzający kod pod kątem bezpieczeństwa wykonuje te same kontrole bez względu na to, czy jest Pan/Pani obecny/a, czy nie.²

Najważniejsze wnioski

• Hooks gwarantują wykonanie; prompty nie. Hooks należy stosować do lintingu, formatowania, kontroli bezpieczeństwa oraz wszystkiego, co musi uruchamiać się za każdym razem niezależnie od zachowania modelu. Kod wyjścia 2 blokuje działania. Kod wyjścia 1 jedynie ostrzega.³
• Skills kodują wiedzę dziedzinową aktywującą się automatycznie. Pole description decyduje o wszystkim. Claude wykorzystuje rozumowanie LLM (a nie dopasowywanie słów kluczowych), aby zdecydować, kiedy zastosować skill.⁴
• Subagents zapobiegają rozrastaniu się kontekstu. Odizolowane okna kontekstowe na potrzeby eksploracji i analizy utrzymują główną sesję w zwięzłej formie. Niezależne subagents należy uruchamiać równolegle, a agent teams stosować wtedy, gdy pracownicy potrzebują trwałej koordynacji.⁵
• Memory znajduje się w systemie plików. Pliki zachowują się między oknami kontekstowymi. CLAUDE.md, MEMORY.md, katalogi reguł i dokumenty przekazania tworzą ustrukturyzowany zewnętrzny system pamięci.⁶
• Wieloagentowa deliberacja wykrywa martwe punkty. Pojedynczy agenci nie potrafią podważać własnych założeń. Dwaj niezależni agenci o różnych priorytetach oceny wychwytują błędy strukturalne, których quality gates nie są w stanie rozwiązać.⁷
• Wzorzec harness jest systemem. CLAUDE.md, hooks, skills, agents i memory nie są niezależnymi funkcjami. Łączą się w deterministyczną warstwę między Panem/Panią a modelem, która skaluje się wraz z automatyzacją.

Jak korzystać z tego przewodnika

Każda sekcja rozwija poprzednią. Znajdujące się na końcu ramy decyzyjne zawierają tabelę wyszukiwania, która pomaga wybrać właściwy mechanizm dla każdego typu problemu.

Pięciominutowa ścieżka złota

Przed głębokim zanurzeniem oto najkrótsza droga od zera do działającego harness. Jeden hook, jeden skill, jeden subagent, jeden rezultat.

Krok 1: Utworzenie hooka bezpieczeństwa (2 minuty)

Proszę utworzyć .claude/hooks/block-secrets.sh:

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

Podłączenie w .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

Rezultat: Każde polecenie bash uruchamiane przez Claude jest teraz sprawdzane pod kątem wycieku poświadczeń. Model nie może pominąć tej kontroli.

Krok 2: Utworzenie skilla do przeglądu kodu (1 minuta)

Proszę utworzyć .claude/skills/reviewer/SKILL.md z frontmatter (name: reviewer, description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code., allowed-tools: Read, Grep, Glob) oraz listą kontrolną: SQL injection, XSS, zakodowane na sztywno sekrety, brak obsługi błędów, funkcje powyżej 50 linii.

Rezultat: Claude automatycznie aktywuje tę wiedzę ekspercką za każdym razem, gdy pojawi się wzmianka o przeglądzie, kontroli lub audycie.

Krok 3: Uruchomienie subagenta (30 sekund)

W dowolnej sesji Claude Code można poprosić Claude o przejrzenie ostatnich 3 commitów pod kątem problemów bezpieczeństwa przy użyciu oddzielnego agenta. Claude uruchamia agenta Explore, który odczytuje diff, stosuje skill przeglądu i zwraca podsumowanie. Główny kontekst pozostaje czysty.

Co zostało uzyskane

Trójwarstwowy harness: deterministyczna bramka bezpieczeństwa (hook), wiedza dziedzinowa aktywująca się automatycznie (skill) oraz izolowana analiza chroniąca kontekst (subagent). Każda z kolejnych sekcji rozwija jedną z tych trzech warstw.

Dlaczego architektura agentów ma znaczenie

Simon Willison ujmuje obecny moment w jednej obserwacji: pisanie kodu jest teraz tanie.⁸ Zgadza się. Jednak konsekwencją tego jest to, że weryfikacja stała się kosztowną częścią. Tani kod bez infrastruktury weryfikacyjnej produkuje błędy na masową skalę. Inwestycja, która się zwraca, to nie lepszy prompt. To system wokół modelu, który wychwytuje to, co model przeoczy.

Trzy siły sprawiają, że architektura agentów staje się konieczna:

Okna kontekstu są skończone i stratne. Każdy odczyt pliku, wyjście narzędzia i tura rozmowy pochłaniają tokeny. Microsoft Research i Salesforce przetestowały 15 LLM na ponad 200 000 symulowanych rozmów i odkryły średni spadek wydajności o 39% z interakcji jednoturowej do wieloturowej.⁹ Degradacja rozpoczyna się już po dwóch turach i podąża przewidywalną krzywą: precyzyjne edycje wieloplikowe w pierwszych 30 minutach degradują się do wizji tunelowej jednego pliku w 90. minucie. Dłuższe okna kontekstu tego nie naprawiają. Warunek „Concat” z tego samego badania (cała rozmowa jako pojedynczy prompt) osiągnął 95,1% wydajności jednoturowej przy identycznej treści. Degradacja wynika z granic tur, a nie z limitów tokenów.

Zachowanie modelu jest probabilistyczne, a nie deterministyczne. Polecenie Claude „zawsze uruchom Prettier po edycji plików” działa w około 80% przypadków.³ Model może zapomnieć, postawić na szybkość lub uznać zmianę za „zbyt małą”. Dla zgodności z przepisami, bezpieczeństwa i standardów zespołowych 80% jest niewystarczające. Hooki gwarantują wykonanie: każdy Edit lub Write wyzwala formatter, za każdym razem, bez wyjątków. Deterministyczne wygrywa z probabilistycznym.

Pojedyncze perspektywy pomijają problemy wielowymiarowe. Pojedynczy agent przeglądający endpoint API sprawdził uwierzytelnianie, zweryfikował sanityzację danych wejściowych i potwierdził nagłówki CORS. Stan idealny. Drugi agent, zlecony oddzielnie jako tester penetracyjny, wykrył, że endpoint akceptował nieograniczone parametry zapytań, które mogły wywołać denial-of-service poprzez amplifikację zapytań do bazy danych.⁷ Pierwszy agent nigdy tego nie sprawdził, ponieważ nic w jego ramach oceny nie traktowało złożoności zapytań jako powierzchni bezpieczeństwa. Ta luka ma charakter strukturalny. Żadne dopracowanie promptu jej nie naprawi.

Architektura agentów odpowiada na wszystkie trzy wyzwania: hooki wymuszają deterministyczne ograniczenia, subagenty zarządzają izolacją kontekstu, a orkiestracja wieloagentowa zapewnia niezależne perspektywy. Razem tworzą harness.

Wzorzec harness

Harness nie jest frameworkiem. To wzorzec: kompozycyjny zestaw plików, skryptów i konwencji, które otaczają agenta AI do programowania deterministyczną infrastrukturą. Komponenty:

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

Warstwa instrukcji: pliki CLAUDE.md i katalogi reguł definiują, co agent wie o projekcie. Są ładowane automatycznie na początku sesji i po każdej kompaktacji. To długoterminowa pamięć architektoniczna agenta.

Warstwa rozszerzeń: skills zapewniają specjalistyczną wiedzę dziedzinową, która aktywuje się automatycznie na podstawie kontekstu. Hooks zapewniają deterministyczne bramki uruchamiane przy każdym pasującym wywołaniu narzędzia. Pliki pamięci utrwalają stan między sesjami. Niestandardowi agenci zapewniają wyspecjalizowane konfiguracje subagents.

Warstwa orkiestracji: wzorce wieloagentowe koordynują niezależnych agentów na potrzeby badań, przeglądów i deliberacji. Budżety uruchomień zapobiegają niekontrolowanej rekurencji. Walidacja konsensusu zapewnia jakość.

Kluczowy wniosek: większość użytkowników pracuje wyłącznie w warstwie podstawowej, obserwując rozrost kontekstu i wzrost kosztów. Zaawansowani użytkownicy konfigurują warstwy instrukcji i rozszerzeń, a następnie używają warstwy podstawowej wyłącznie do orkiestracji i podejmowania ostatecznych decyzji.²

Zarządzane i samodzielnie hostowane harnesses (kwiecień 2026)

Przez cały początek 2026 roku jedyną realną opcją była ścieżka „zbuduj własny harness”. W kwietniu 2026 roku to się zmieniło. Anthropic udostępniło w publicznej becie Claude Managed Agents (8 kwietnia): pętla harness + wykonywanie narzędzi + kontener sandbox + utrwalanie stanu jako REST API, rozliczane według standardowych tokenów oraz 0,08 USD za godzinę sesji. Aktualizacja Agents SDK firmy OpenAI (16 kwietnia) sformalizowała ten sam podział — harness i zasoby obliczeniowe jako odrębne warstwy, z natywnymi dostawcami sandbox (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) oraz snapshot/rehydrate umożliwiającymi przetrwanie utraty kontenera.²³²⁴

Głębsza powierzchnia SDK po stronie OpenAI pojawiła się w openai-agents Python v0.14.0 (wydanej 15 kwietnia 2026 roku; ogłoszonej 16 kwietnia): podklasa SandboxAgent klasy Agent z default_manifest, instrukcjami sandbox i możliwościami; Manifest opisujący kontrakt świeżej przestrzeni roboczej (pliki, katalogi, pliki lokalne, repozytoria Git, env, użytkownicy, montowania); SandboxRunConfig do konfiguracji dla każdego uruchomienia klienta sandbox, wstrzykiwania aktywnej sesji, nadpisywania manifestu, snapshotów i limitów współbieżności materializacji. Wbudowane możliwości obejmują dostęp do powłoki, edycję systemu plików, inspekcję obrazów, skills, pamięć sandbox i kompaktację. Pamięć sandbox utrwala wyodrębnione wnioski między uruchomieniami i udostępnia je stopniowo; przestrzenie robocze obsługują pliki lokalne, wpisy repozytoriów Git i zdalne montowania (S3, R2, GCS, Azure Blob, S3 Files); snapshoty są przenośne między dostawcami. Backendy: UnixLocalSandboxClient, DockerSandboxClient oraz hostowani klienci dla Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop i Vercel za pośrednictwem opcjonalnych extras.²⁴

Dla projektów Python, które chcą osadzić runtime Claude Code jako bibliotekę — między „wywołaj z powłoki claude” a „REST API do Managed Agents” — claude-agent-sdk-python jest trzecią opcją. Seria wydań z 28–29 kwietnia (v0.1.69 → v0.1.71) podniosła wersję dołączonego CLI do v2.1.123, zwiększyła minimalną wymaganą wersję zależności mcp do >=1.19.0 (starsze wersje po cichu odrzucały zwroty CallToolResult z narzędzi MCP działających w procesie, pozostawiając modelowi obiekt blob z błędem walidacji) oraz zapewniła zgodność schematu SandboxNetworkConfig z TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Według stanu na 2026-08-12 pakiet ma wersję v0.2.137 w PyPI, a TypeScript SDK — v0.3.229 (obie zweryfikowano względem aktywnych rejestrów); linia 0.2.x zawiera przyrostowe zmiany względem opisanej tutaj powierzchni 0.1.x — poniższe opcje include_hook_events, skills i konfiguracji sandbox pozostają aktualne — a ostatnie wydania koncentrują się na niezawodności czyszczenia podprocesów i strumieni NDJSON.⁹⁰⁸⁶

Jeśli harness obejmuje warstwę głosową lub realtime, openai-agents-python v0.17.0 (8 maja 2026) zaktualizował RealtimeAgent, aby domyślnie używał gpt-realtime-2.⁴¹ Istniejące sesje realtime automatycznie przejmują nową wartość domyślną; należy jawnie przypiąć poprzedni model, jeśli na potrzeby oceny trzeba zachować dotychczasowe działanie.

W lipcu 2026 roku zarządzana kolumna zyskała również historię wieloagentową po stronie OpenAI: openai-agents-python v0.18.2 (11 lipca) i openai-agents-js v0.13.2 (10 lipca) dodają w becie hostowaną obsługę wielu agentów — zarządzaną przez OpenAI orkiestrację wielu agentów jako hostowaną usługę, będącą bezpośrednim odpowiednikiem publicznej bety Managed Multiagent Orchestration firmy Anthropic, omówionej w sekcji Orkiestracja wielu agentów.[^^101] Obaj dostawcy oferują teraz na poziomie wielu agentów ten sam kompromis, który poniższa tabela opisuje dla pojedynczych agentów: dostawca prowadzi pętlę delegowania, a użytkownik rezygnuje z powierzchni hooks.

Rozwidlenie architektoniczne jest teraz realne:

Kiedy wybrać które rozwiązanie: samodzielne hostowanie nadal jest właściwe dla zespołów, które mają już zaplecze infrastrukturalne, chcą kontrolować własne skills/hooks lub dogłębnie optymalizują konkretny przepływ pracy. Rozwiązanie zarządzane jest odpowiednie dla zespołów bez dedykowanych inżynierów platformowych, gdy czas do uzyskania wartości jest ważniejszy niż możliwość dostosowania, albo gdy uruchomienia agentów muszą niezawodnie przetrwać zamknięcie laptopa bez budowania własnej warstwy utrwalania. Oba podejścia są zgodne — można uruchomić samodzielnie hostowany harness, który deleguje określone długotrwałe zadania do Managed Agents za pośrednictwem REST API.

Jak harness wygląda na dysku

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

Każdy plik w tej strukturze pełni określoną funkcję. Drzewo ~/.claude/ to osobista infrastruktura stosowana we wszystkich projektach. Drzewo .claude/ w każdym repozytorium jest specyficzne dla projektu i współdzielone przez git. Razem tworzą kompletny harness.

System skills

Skills to rozszerzenia wywoływane przez model. Claude automatycznie je wykrywa i stosuje zależnie od kontekstu, bez konieczności ich jawnego wywoływania.⁴ Gdy tylko zauważy Pan/Pani, że ponownie wyjaśnia ten sam kontekst w kolejnych sesjach, warto utworzyć skill.

Kiedy utworzyć skill

Skills służą do wiedzy, którą Claude ma zawsze do dyspozycji. Slash commands służą do działań wywoływanych jawnie. W razie wyboru między nimi warto zadać pytanie: „Czy Claude powinien zastosować to automatycznie, czy to ja powinienem/powinnam zdecydować, kiedy to uruchomić?”

Tworzenie skill

Skills mogą znajdować się w czterech lokalizacjach, od najszerszego do najwęższego zakresu:⁴

Każdy skill wymaga pliku SKILL.md z frontmatter YAML:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Dokumentacja frontmatter

Pole description jest najważniejsze

Na początku sesji Claude Code wyodrębnia name i description każdego skill, a następnie wstrzykuje je do kontekstu Claude. Gdy wysyłana jest wiadomość, Claude używa rozumowania modelu językowego, aby zdecydować, czy którykolwiek skill jest istotny. Niezależna analiza źródła Claude Code potwierdza ten mechanizm: opisy skill są wstrzykiwane do sekcji available_skills promptu systemowego, a model korzysta ze standardowego rozumienia języka, aby wybierać odpowiednie skills.¹⁰

Zły opis:

description: Helps with code

Skuteczny opis:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

Skuteczny opis zawiera: co robi (przegląda kod pod kątem konkretnych typów problemów), kiedy go używać (podczas analizy zmian, PR-ów, jakości) oraz frazy wyzwalające (review, audit, check), które użytkownicy naturalnie wpisują.

Należy pamiętać, że automatyczna aktywacja jest regulowana, a nie bezwzględna: od wersji v2.1.215 Claude nie wywołuje już samodzielnie dołączonych skills /verify i /code-review — uruchamiają się wyłącznie na jawne wywołanie, co jest świadomym wycofaniem aktywacji opartej na opisie dla kosztownych skills do przeglądu, których nieproszone uruchomienia kosztowały więcej, niż przynosiły korzyści.⁷⁴

Budżet kontekstu

Wszystkie opisy skills współdzielą budżet kontekstu skalowany dynamicznie do 1% okna kontekstu, z limitem awaryjnym wynoszącym 8 000 znaków.⁴ Przy dużej liczbie skills warto zachować zwięzłość każdego opisu i umieścić najważniejszy przypadek użycia na początku. Budżet można zastąpić zmienną środowiskową SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ lecz lepszym rozwiązaniem są krótsze, bardziej precyzyjne opisy. Podczas sesji należy uruchomić /context, aby sprawdzić, czy jakieś skills są wykluczone.

Pliki pomocnicze i organizacja

Skills mogą odwoływać się do dodatkowych plików w tym samym katalogu:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Należy odwoływać się do nich z SKILL.md za pomocą linków względnych. Claude odczytuje te pliki na żądanie, gdy skill się aktywuje. Warto utrzymywać SKILL.md poniżej 500 wierszy, a szczegółowe materiały referencyjne przenosić do plików pomocniczych.¹²

Udostępnianie skills przez Git

Project skills (.claude/skills/ w głównym katalogu repozytorium) są udostępniane przez kontrolę wersji:⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Gdy członkowie zespołu wykonają pull, automatycznie otrzymają skill. Bez instalacji i bez konfiguracji. Jest to najskuteczniejszy sposób standaryzacji wiedzy specjalistycznej w zespole.

Skills jako biblioteka promptów

Poza skills o pojedynczym przeznaczeniu struktura katalogów działa jak uporządkowana biblioteka promptów:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Każdy skill koduje inny aspekt Pana/Pani wiedzy specjalistycznej. Razem tworzą bazę wiedzy, z której Claude automatycznie korzysta zależnie od kontekstu. Młodszy programista otrzymuje wskazówki na poziomie seniora, nie musząc o nie prosić.

Skills współdziałają z hooks

Skills mogą definiować własne hooks w frontmatter, aktywowane tylko podczas działania danego skill. Tworzy to zachowanie specyficzne dla domeny, które nie zaśmieca innych sesji:²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

Skills filozoficzne aktywują się automatycznie przez hooks SessionStart, wstrzykując ograniczenia jakości do każdej sesji bez jawnego wywołania. Sam skill jest wiedzą. Hook jest egzekwowaniem. Razem tworzą warstwę zasad.

Typowe błędy związane ze skills

Zbyt szerokie opisy. Skill git-rebase-helper, który aktywuje się przy każdym prompcie związanym z git (rebase, merge, cherry-pick, a nawet git status), zaśmieca kontekst w 80% sesji. Rozwiązaniem jest zawężenie opisu albo dodanie disable-model-invocation: true i wymaganie jawnego wywołania /skill-name.⁴

Zbyt wiele skills rywalizujących o budżet. Więcej skills oznacza więcej opisów rywalizujących o 1% budżetu kontekstu. Jeśli skills się nie aktywują, należy sprawdzić /context pod kątem wykluczonych pozycji. Lepiej priorytetyzować mniej, dobrze opisanych skills niż wiele niejasnych.

Krytyczne informacje ukryte w plikach pomocniczych. Claude odczytuje SKILL.md od razu, lecz sięga do plików pomocniczych tylko w razie potrzeby. Jeśli krytyczne informacje znajdują się w pliku pomocniczym, Claude może ich nie znaleźć. Kluczowe informacje należy umieszczać bezpośrednio w SKILL.md.⁴

Powierzchnia skill SDK (8 maja 2026)

Samodzielnie hostowane harnesses korzystające z claude-agent-sdk-python v0.1.77+ powinny używać opcji skills w ClaudeAgentOptions do deklarowania dostępnych skills, a nie starszej wartości "Skill" w allowed_tools.³⁷ Skrót "Skill" jest przestarzały, a dedykowana opcja zapewnia Claude Code bardziej ustrukturyzowane informacje o dostępnych skills. Dołączony CLI w v0.1.77 ma wersję v2.1.133.

Konwergencja plugin i skills w .claude/skills/ (29 maja 2026)

Skills zawsze były ładowane z katalogu .claude/skills/ projektu. Claude Code v2.1.157 rozszerza ten katalog o plugins: plugin umieszczony w .claude/skills/ ładuje się teraz automatycznie bez rejestracji w marketplace, a claude plugin init <name> tworzy w tym miejscu nowy szkielet z manifestem i SKILL.md już połączonymi.⁵⁸ Zamyka to lukę między dwoma formami narzędzi projektowych, które wcześniej znajdowały się w różnych miejscach — prostym skill zapisanym bezpośrednio w repozytorium a plugin, który łączy skill, hooks i serwer MCP, lecz wcześniej wymagał marketplace do instalacji. Praktyczny efekt dla projektowania harness: narzędzia o zakresie projektu nie potrzebują już pośrednictwa rejestru, aby zostać dostarczone — należy je napisać, zatwierdzić w repozytorium, a członkowie zespołu otrzymają tę samą powierzchnię po git pull. Plugins nadal obsługują przypadek instalacji pakietowej (hooks + skills + serwery MCP + agents w jednym ZIP); zmiana polega na tym, że projekt nie musi już uruchamiać marketplace tylko po to, aby załadować plugin z własnego drzewa. Ta konwergencja ma teraz podstawę między dostawcami: Agent Plugins 1.0.0 (opublikowane 6 sierpnia 2026) standaryzuje ten sam format pakietu — manifest plugin.json, katalogi skills/ z folderami SKILL.md, opcjonalny mcp.json — jako „przenośny format pakietów dla agentów AI”, przyjęty przy premierze przez VS Code, Cursor, GitHub Copilot, ChatGPT & Codex oraz Kiro. Jest to wyraźnie warstwa pakietowania wokół Agent Skills i MCP, a nie ich zastępstwo; należy zauważyć, że Anthropic, autor specyfikacji Agent Skills, nie jest jeszcze częścią koalicji — dlatego przenośność z Claude na zewnątrz należy traktować jako zgodność na poziomie formatu, a nie oficjalną dwukierunkową umowę.⁸⁹

Ukrywanie dołączonej powierzchni jako zarządzanie (8 czerwca 2026)

Skills to możliwości, a możliwości to powierzchnia ataku. Claude Code v2.1.169 dodaje ustawienie disableBundledSkills (oraz odpowiadającą mu zmienną środowiskową CLAUDE_CODE_DISABLE_BUNDLED_SKILLS), które całkowicie ukrywa przed modelem dołączone skills, workflows i wbudowane slash commands.⁶⁰ W przypadku wzmocnionego lub regulowanego harness jest to celowe ograniczenie powierzchni ataku: operator, który przeprowadził audyt i zatwierdził określony zestaw project i personal skills, może wyłączyć wszystko, co Anthropic dostarcza w pakiecie, aby model rozumował wyłącznie w obrębie powierzchni zweryfikowanej przez operatora. Należy traktować to tak samo jak allowlist narzędzi — ustawieniem domyślnym są szerokie możliwości, a wyłączenie ustawienia domyślnego jest decyzją z zakresu zarządzania, nie przełącznikiem wygody.

Zagnieżdżone .claude/skills i rozstrzyganie według najbliższego katalogu (16 czerwca 2026)

Claude Code v2.1.178 uczynił narzędzia projektowe świadomymi lokalizacji. Skills w zagnieżdżonych katalogach .claude/skills są teraz ładowane podczas pracy nad plikami znajdującymi się pod tym katalogiem, a nie tylko z głównego katalogu repozytorium; przy kolizji nazw zagnieżdżony skill jest wyświetlany jako <dir>:<name>, dzięki czemu oba pozostają dostępne.⁶³ Ta sama wersja sprawiła, że pozostała powierzchnia projektu jest rozstrzygana najbliżej katalogu roboczego: gdy nazwa agent, workflow lub stylu wyjściowego koliduje między zagnieżdżonymi katalogami .claude/, wygrywa pozycja najbliższa katalogowi roboczemu, a zapis workflow o zakresie projektu trafia do najbliższego istniejącego .claude/workflows/, zamiast zawsze do katalogu głównego.⁶³ W monorepo lub repozytorium repozytoriów stanowi to różnicę między jedną płaską, globalną powierzchnią a narzędziami dla poszczególnych pakietów, które aktywują się w kontekście — services/api/.claude/skills/ może zawierać skills specyficzne dla API, pojawiające się wyłącznie podczas pracy w tym drzewie, bez kolizji ze skill o tej samej nazwie w services/web/.

Architektura hooków

Hooki to polecenia powłoki wyzwalane przez zdarzenia cyklu życia Claude Code.³ Działają poza LLM jako zwykłe skrypty, a nie prompty interpretowane przez model. Model chce uruchomić rm -rf /? 10-wierszowy skrypt bash sprawdza polecenie względem listy blokad i odrzuca je, zanim powłoka w ogóle je zobaczy. Hook uruchamia się niezależnie od tego, czy model tego chce.

Dostępne zdarzenia

Według stanu na aktualizację tego przewodnika Claude Code udostępnia 31 udokumentowanych zdarzeń cyklu życia w ośmiu kategoriach. Lista zdarzeń rośnie wraz z wydaniami, dlatego za źródło prawdy należy uznać dokumentację referencyjną i przed podłączeniem hooków produkcyjnych sprawdzić ściągę, aby poznać aktualną pełną tabelę:¹³

DirectoryAdded (v2.1.219) zamyka lukę dotyczącą workspace w trakcie sesji. Lista zdarzeń pozostawała stabilna od czasu pojawienia się MessageDisplay w v2.1.152; DirectoryAdded jest pierwszym nowym zdarzeniem cyklu życia od tamtej pory i uruchamia się po tym, jak /add-dir — albo żądanie kontrolne register_repo_root od SDK — zarejestruje nowy katalog roboczy w trakcie sesji.⁸⁴ Luka, którą to zamyka, jest realna: dotąd harness mógł wyczerpująco zweryfikować workspace podczas SessionStart, a następnie obserwować dołączenie drugiego repozytorium bez uruchomienia jakiegokolwiek hooka. Wszystko, co jest sprawdzane dotyczące workspace przy starcie — kontrole zaufania, skany sekretów, reguły ograniczania ścieżek wyprowadzane z drzewa, ładowanie zasad dla poszczególnych repozytoriów — należy uruchomić ponownie tutaj, ponieważ zbiór katalogów sesji nie jest już stały od momentu uruchomienia. Zdarzenie ma charakter informacyjny, a nie blokujący, dlatego należy traktować je jako wyzwalacz do ponownego wyprowadzenia stanu i zapisania pochodzenia, a nie jako bramkę; jeśli katalog nigdy nie powinien dać się dodać, należy odmówić tego w ustawieniach, zamiast próbować zawetować je z poziomu hooka. Część dotycząca SDK pojawiła się w tym samym wydaniu (TypeScript v0.3.219 dodaje DirectoryAdded do zdarzeń cyklu życia protokołu kontrolnego), więc harnessy hostowane przez SDK widzą je na równi z tymi opartymi na CLI.⁸⁵

Semantyka kodów wyjścia

Kody wyjścia określają, czy hooki blokują działania:³

Konfiguracja hooków

Hooki znajdują się w plikach ustawień. Poziom projektu (.claude/settings.json) służy do współdzielonych hooków. Poziom użytkownika (~/.claude/settings.json) — do hooków osobistych:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Pole matcher filtruje wartość zależną od zdarzenia. W przypadku zdarzeń narzędzi dopasowuje wartości tool_name, takie jak Bash, Edit, Write, Read, Glob, Grep, nazwy narzędzi MCP, takie jak mcp__server__tool, lub * dla wszystkich narzędzi. Proste nazwy i listy rozdzielane znakiem | są dopasowaniami dokładnymi; wartości zawierające inne znaki są wyrażeniami regularnymi JavaScript. Niektóre zdarzenia nie obsługują matcherów i zawsze uruchamiają się po skonfigurowaniu.¹³ Od Claude Code v2.1.195 matchery zawierające identyfikatory z łącznikami (code-reviewer, mcp__brave-search) są dopasowywane dokładnie, zamiast przypadkowo dopasowywać podciągi — hook skierowany do jednego agenta lub serwera nie uruchamia się już dla każdej nazwy, która jedynie zawiera ten ciąg; aby objąć wszystkie narzędzia z serwera MCP z łącznikiem, należy zapisać jawny wzorzec mcp__brave-search__.*.⁶⁶ Wersja v2.1.214 zastosowała tę samą zasadę wobec wzorców ścieżek: warunek if: hooka używający jednosegmentowego wzorca dir/** dopasowuje teraz wyłącznie <cwd>/dir, a nie każdy katalog o nazwie dir w dowolnym miejscu drzewa — gdy rzeczywiście chodzi o dowolną głębokość, należy użyć **/dir/**.⁷⁴ Podobnie jak w przypadku zmiany z v2.1.195, poprawka zamienia przypadkowy szeroki zakres na deklarowaną intencję; należy skontrolować wszelkie warunki hooków, które po cichu polegały na dawnym zachowaniu obejmującym dowolną głębokość.

Protokół wejścia/wyjścia hooków

Hooki otrzymują JSON na stdin wraz z pełnym kontekstem:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

W celu zaawansowanego sterowania hooki PreToolUse mogą zwracać JSON, aby modyfikować dane wejściowe narzędzia, wstrzykiwać kontekst lub podejmować decyzje dotyczące uprawnień. Należy użyć wrappera hookSpecificOutput — starszy format decision/reason na najwyższym poziomie jest przestarzały dla PreToolUse:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Trzy rodzaje gwarancji

Przed napisaniem dowolnego hooka warto zapytać: jakiego rodzaju gwarancji potrzebuję?¹⁴

Gwarancje formatowania zapewniają spójność po fakcie. Hooki PostToolUse dla Write/Edit uruchamiają formatter po każdej zmianie pliku. Dane wyjściowe modelu nie mają znaczenia, ponieważ formatter normalizuje wszystko.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Gwarancje bezpieczeństwa zapobiegają niebezpiecznym działaniom przed ich wykonaniem. Hooki PreToolUse dla Bash sprawdzają polecenia i blokują destrukcyjne wzorce kodem wyjścia 2:

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

Gwarancje jakości sprawdzają stan w punktach decyzyjnych. Hooki PreToolUse dla poleceń git commit uruchamiają linter lub zestaw testów i blokują commit, jeśli kontrole jakości zakończą się niepowodzeniem:

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

Typy hooków wykraczające poza polecenia powłoki

Claude Code obsługuje pięć typów hooków:¹³ Hooki poleceń (type: "command") uruchamiają skrypty powłoki. Są szybkie, deterministyczne i nie generują kosztów tokenów.

Hooki narzędzi MCP (type: "mcp_tool") wywołują narzędzie na już połączonym serwerze MCP. Należy ich używać, gdy logika walidacji znajduje się już za granicą MCP i nie wymaga osobnego skryptu powłoki.

Hooki promptów (type: "prompt") wysyłają prompt jednosesyjny do szybkiego modelu Claude. Model zwraca { "ok": true }, aby zezwolić, albo { "ok": false, "reason": "..." }, aby zablokować. Należy ich używać do niuansowanej oceny, której nie da się wyrazić za pomocą regex.

Hooki agentów (type: "agent") uruchamiają subagent z dostępem do narzędzi (Read, Grep, Glob) w celu wieloturowej weryfikacji. Są eksperymentalne; w bramkach produkcyjnych należy preferować hooki poleceń, a hooki agentów rezerwować dla kontroli, które rzeczywiście wymagają sprawdzenia faktycznych plików lub wyników testów:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Od wersji Claude Code v2.1.140 dane wejściowe hooka agenta obejmują subagent_type, co pozwala współdzielonemu hookowi odróżnić uruchomienie security-reviewer od explorera lub ogólnego workera bez zgadywania na podstawie tekstu promptu.⁴⁹

Hooki HTTP (type: "http") wysyłają dane wejściowe JSON zdarzenia jako żądanie POST do adresu URL i otrzymują z powrotem JSON. Należy ich używać do webhooków, zewnętrznych usług powiadomień lub walidacji opartej na API (v2.1.63+). Nie są obsługiwane dla zdarzeń SessionStart:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Asynchroniczne hooki

Hooki mogą działać w tle bez blokowania wykonania. Aby wykonywać niekrytyczne operacje, takie jak powiadomienia i logowanie, należy dodać async: true:¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

Trybu asynchronicznego należy używać do powiadomień, telemetrii i kopii zapasowych. Nigdy nie należy używać go do formatowania, walidacji ani niczego, co musi zostać ukończone przed następną akcją.

Dispatchery zamiast niezależnych hooków

Uruchamianie siedmiu hooków wywoływanych przez to samo zdarzenie, z których każdy niezależnie odczytuje stdin, tworzy warunki wyścigu. Dwa hooki zapisujące jednocześnie do tego samego pliku stanu JSON spowodują obcięcie JSON. Każdy hook działający dalej, który analizuje ten plik, przestanie działać.²

Rozwiązanie: jeden dispatcher na zdarzenie, który uruchamia hooki sekwencyjnie na podstawie danych stdin zapisanych w pamięci podręcznej:

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Debugowanie hooków

Pięć technik debugowania hooków, które zawodzą bez widocznego komunikatu:¹⁴

1. Testowanie skryptów niezależnie. Należy przekazać przykładowy JSON potokiem: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Używanie stderr do danych debugowania. Kod wyjścia 2 wraz ze stderr jest przekazywany z powrotem do Claude jako komunikat błędu. Nieblo­kujący stderr (wyjście 1, 3 itd.) pojawia się wyłącznie w trybie szczegółowym (Ctrl+O).
3. Kontrolowanie błędów jq. Nieprawidłowe ścieżki JSON zwracają po cichu null. Należy testować wyrażenia jq na rzeczywistych danych wejściowych narzędzia.
4. Weryfikacja kodów wyjścia. Hook PreToolUse używający exit 1 nie zapewnia żadnego wymuszania, choć może sprawiać wrażenie, że działa.
5. Utrzymywanie szybkiego działania hooków. Hooki działają synchronicznie. Wszystkie hooki powinny kończyć się w mniej niż 2 sekundy, a najlepiej w mniej niż 500 ms.

Strumieniowanie zdarzeń hooków po stronie SDK

Samodzielnie hostowane harnesses zbudowane na claude-agent-sdk-python (v0.1.74+, 6 maja 2026) mogą subskrybować zdarzenia hooków bezpośrednio ze strumienia komunikatów, zamiast korzystać z wywołań zwrotnych skryptów powłoki.³⁶ Należy ustawić include_hook_events=True w ClaudeAgentOptions; obiekty HookEventMessage (PreToolUse, PostToolUse, Stop i inne) są zwracane przez ten sam iterator co komunikaty asystenta i wyniki narzędzi. Odzwierciedla to opcję includeHookEvents TypeScript SDK; dołączony CLI został w tej samej wersji podniesiony do v2.1.129.

Wzorzec strumienia zdarzeń sprawdza się, gdy harness działa już w Python i sygnały hooków mają znajdować się w tym samym przepływie sterowania co dane wyjściowe modelu. Kontrakt hooków skryptów powłoki (kody wyjścia, stdin JSON, dispatchery) nadal jest właściwym rozwiązaniem dla harnesses łączących wiele narzędzi, współdzielących hooki między Claude Code a Codex lub wymagających semantyki kodów wyjścia do blokowania.

Seria TypeScript SDK z lipca 2026 roku (v0.3.205–v0.3.208) uczyniła sam protokół strumieniowany bardziej kontraktowym.⁷⁰ Przerwania zwracają teraz typowane potwierdzenia: przerwanie potwierdza, które wiadomości w kolejce nadal oczekują, za pomocą UUID still_queued, a sesje ogłaszają możliwość interrupt_receipt_v1 w system/init, dzięki czemu koordynator może odróżnić „przerwanie dotarło” od „przerwanie wyścigowo minęło wiadomość już będącą w toku”. Ramki command_lifecycle raportują stan queued/started/completed/cancelled/discarded dla każdej wiadomości — jest to pierwsza własna odpowiedź na pytanie „co stało się z wysłaną przeze mnie wiadomością” bez wnioskowania na podstawie transkrypcji. Pojawiły się też mniejsze elementy: typ AgentToolCompletedOutput dla ładunków ukończenia subagentów, a wywołania zwrotne canUseTool mogą teraz zwracać {behavior: 'allow'} bez pola updatedInput.

Jedna linia w tej serii wyznacza poziom bezpieczeństwa, a nie stanowi funkcji: v0.3.208 naprawiła sytuację, w której przerwanie wywołującego przychodzące podczas oczekiwania na hook było przekształcane w sukces hooka — co oznaczało, że narzędzie bramkowane przez hook PreToolUse mogło wykonać się po przerwaniu przez wywołującego.⁷⁰ Jeśli harness używa hooków po stronie SDK jako bramki uprawnień i polega na przerwaniu, aby anulować pracę w toku, v0.3.208 należy traktować jako minimalną wersję; poniżej niej „przerwano” nie oznaczało niezawodnie „zablokowano”. Python v0.2.127 (24 lipca 2026) to drugie obejście tego rodzaju w ciągu miesiąca — query() zamykało stdin przy pierwszej ramce result, podczas gdy subagenci w tle nadal działali, więc ich wywołania narzędzi SDK-MCP kończyły się błędem "Stream closed" i całkowicie omijały hooki PreToolUse.⁸⁵ Należy nazwać ten wzorzec i go monitorować: wymuszanie hooków po stronie SDK zawodzi w trybie fail-open na granicach cyklu życia — abort, teardown, stream close — gdy transport kończy się przed odebraniem werdyktu hooka; zawodzi też bezgłośnie, ponieważ pominięty hook wygląda dokładnie jak hook, który zatwierdził działanie. Należy przypiąć obie minimalne wersje SDK i zachować warstwę hooków powłoki jako możliwe do udowodnienia wymuszanie.

Poziom wysiłku i pochodzenie sesji (7–8 maja 2026)

Dwa dodatki w Claude Code v2.1.132 i v2.1.133 zapewniają hookom i podprocesom lepszy sygnał dotyczący ich kontekstu wykonania:³⁸³⁹

• effort.level w danych wejściowych hooka. Hooki otrzymują teraz pole JSON effort.level w tych samych danych wejściowych, które zawierają tool_input i session_id. Ta sama wartość jest eksportowana jako zmienna środowiskowa $CLAUDE_EFFORT, dzięki czemu polecenia Bash mogą ją odczytać bez analizowania JSON. Można użyć tego do skalowania kosztu hooka zależnie od poziomu wysiłku: pominąć kosztowną walidację na low, a uruchomić pełną bramkę bezpieczeństwa na xhigh lub max.
• Zmienna środowiskowa CLAUDE_CODE_SESSION_ID w podprocesach Bash. Podprocesy narzędzia Bash widzą teraz tę samą wartość session_id, którą widzą hooki, udostępnioną jako CLAUDE_CODE_SESSION_ID. Zamyka to lukę w pochodzeniu dla narzędzi rejestrujących stan według sesji, które wcześniej nie mogły powiązać zdarzeń podprocesów ze zdarzeniami hooków.

Oba sygnały są dostępne bez zmian w kodzie; istniejące hooki ignorujące nowe pola nadal działają.

autoMode.hard_deny oraz poprawki hooków/pluginów w v2.1.136 (8 maja 2026)

Claude Code v2.1.136 dodała nowy poziom twardego odrzucania do trybu automatycznego oraz naprawiła grupę problemów z pluginami i MCP, które wpływały na długotrwale działające harnesses:⁴⁰ - settings.autoMode.hard_deny. Reguły klasyfikatora trybu automatycznego, które blokują bezwarunkowo, niezależnie od intencji użytkownika lub wyjątków zezwalających. Znajduje się to ponad istniejącymi mechanizmami dopasowywania zezwalaj/blokuj jako bezwarunkowa dźwignia zarządzania. Należy używać tego dla reguł, których nigdy nie wolno nadpisać (wymuszone wysłanie zmian do main, pliki zawierające sekrety, dostęp do produkcyjnej bazy danych), nawet gdy operator zatwierdził szerszą kategorię w swoich osobistych ustawieniach. - autoMode.classifyAllShell (v2.1.193). Domyślnie klasyfikator trybu automatycznego analizuje wyłącznie polecenia powłoki pasujące do wzorców dowolnego wykonywania kodu. To ustawienie kieruje każde polecenie Bash/PowerShell przez klasyfikator — zapewniając maksymalny poziom pokrycia dla zarządzanego harness — a ta sama wersja udostępnia powody odmowy w transkrypcji, powiadomieniu toast i /permissions, co zamienia ciche blokady w decyzje podlegające audytowi. Codex zaostrzył analogiczny obszar w wersji v0.142.2: polecenia PowerShell zawierające wykonywalne regiony AST, których jego klasyfikator bezpieczeństwa nie potrafi przeanalizować, wymagają teraz zatwierdzenia zamiast przechodzić bezgłośnie.⁶⁶ - Hook ask ustanawia dolny próg klasyfikatora (v2.1.211). Kwestia pierwszeństwa między hook a trybem automatycznym została już rozstrzygnięta: hook PreToolUse, który zwraca decyzję uprawnień ask, wymusza ostateczny wynik w postaci pytania — tryb automatyczny nie może podnieść go ponownie do zezwolenia dla niesandboxowanych poleceń Bash.⁶⁹ Dla zarządzanego harness jest to brakująca warstwa gwarancji: ask hooka jest deterministycznym zatrzymaniem z udziałem człowieka, które pozostaje skuteczne nawet przy w pełni automatycznych zasadach uprawnień. W przypadku operacji, dla których potrzebna jest decyzja człowieka zamiast odmowy, należy używać ask (nie tylko blokad exit-2). - Model klasyfikatora jest przypięty na sesję (v2.1.210). Klasyfikator trybu automatycznego domyślnie używa Sonnet 5 i jest przypięty na czas sesji, dlatego zmiana modelu w trakcie sesji nie zmienia już modelu wykonującego klasyfikacje uprawnień.⁶⁹ Spójność klasyfikacji jest właściwością zarządzania; eliminuje to ciche źródło dryfu. - Serwery MCP nie znikają już po /clear. Serwery skonfigurowane w .mcp.json, pluginach i konektorach claude.ai były bezgłośnie usuwane z aktywnego zestawu po /clear w rozszerzeniu VS Code, pluginie JetBrains i Agent SDK. Poprawka pojawiła się w v2.1.136. Jeśli serwer „MCP server X went missing mid-session”, była to przyczyna. - Utrata tokena odświeżania OAuth MCP podczas równoczesnego odświeżania. Użytkownicy korzystający z kilku zdalnych serwerów MCP nie powinni już potrzebować codziennego ponownego uwierzytelniania. Równoczesne zapisy podczas odświeżania nadpisywały się nawzajem. - Tryb planu blokuje teraz zapisy plików prawidłowo. Pasująca reguła zezwalająca Edit(...) omijała ochronę zapisu w trybie planu. Tryb planu jest teraz egzekwowany niezależnie od reguł zezwalających. - Hooki pluginów Stop i UserPromptSubmit nie zawodzą już w trakcie sesji. Czyszczenie cache usuwało pliki wersji pluginów, które były nadal używane przez uruchomioną sesję, przerywając działanie konkretnie tych dwóch zdarzeń hooków. Poprawka utrzymuje używane wersje jako przypięte. - Wpis skills w plugin.json. Ustawienie skills ukrywało domyślny katalog skills/ pluginu. Teraz wpis jest prawidłowo łączony, a wskazanie ścieżki do pliku powoduje jawny błąd zamiast cichego niepowodzenia. - Zmienne środowiskowe hooka SessionStart CLAUDE_ENV_FILE stawały się nieaktualne. Zmienne eksportowane przez hooki SessionStart za pośrednictwem CLAUDE_ENV_FILE stawały się nieaktualne po /resume lub /clear. Poprawiono to w v2.1.136. Sesje ponownie wczytują teraz plik środowiskowy przy tych zdarzeniach.

Dla harness zarządzania operacyjnie najciekawsze pozycje to autoMode.hard_deny (nowa dźwignia) oraz poprawka znikania MCP (cicha awaria, która przerywała długie sesje). Wszystko pozostałe to poprawki jakości użytkowania.

Ustrukturyzowane argumenty hooków i kontynuowanie po blokadzie (11 maja 2026)

Claude Code v2.1.139 dodał dwa szczegóły dotyczące hooków istotne dla produkcyjnych harness: formę wykonania args: string[] dla hooków poleceń oraz continueOnBlock dla hooków PostToolUse.⁴²⁴⁴ Należy preferować args, gdy hook potrzebuje wartości dynamicznych lub symboli zastępczych ścieżek. Polecenie jest uruchamiane bezpośrednio, bez powłoki, co eliminuje całą klasę błędów związanych z cytowaniem i wstrzykiwaniem.

Należy używać continueOnBlock, gdy hook PostToolUse powinien przekazać powód odrzucenia z powrotem do Claude i kontynuować turę zamiast kończyć przepływ. Trzeba traktować to jako funkcję poprawiającą doświadczenie operatora, a nie obejście zabezpieczeń. Bramka blokująca nadal powinna blokować niebezpieczny rezultat.

Ta sama wersja przekazuje CLAUDE_PROJECT_DIR do serwerów stdio MCP i pozwala konfiguracjom pluginów odwoływać się do ${CLAUDE_PROJECT_DIR} w poleceniach.⁴² Narzędzia MCP powinny rozwiązywać ścieżki względne wobec projektu na podstawie tej wartości, a nie katalogu roboczego procesu, który przypadkowo uruchomił serwer. Wydania z początku lipca 2026 (v2.1.203–v2.1.206) rozszerzyły tę samą zasadę na poziom protokołu: roots/list MCP obejmuje teraz dodatkowe katalogi robocze sesji, z powiadomieniami roots/list_changed przy ich zmianie — dzięki temu serwer respektujący katalogi główne MCP śledzi rzeczywisty kształt wielokatalogowego workspace zamiast zakładać pojedynczy katalog projektu.⁶⁸

Claude Code v2.1.140 to przede wszystkim wydanie zwiększające niezawodność dla operatorów harness: naprawia hooki ConfigChange, które nie uruchamiały się przy zmianach ustawień, zamyka przypadki brzegowe, w których disableAllHooks i allowManagedHooksOnly nie łączyły się poprawnie między poziomami ustawień, oraz zapobiega ujawnianiu przez okna dialogowe uprawnień niezamierzonych zmiennych środowiskowych zwracanych przez wyniki hooków.⁴⁹ Dzięki temu istniejące wzorce zarządzania opisane w tej sekcji są bardziej niezawodne; nie wymaga to nowej architektury hooków.

Claude Code v2.1.141 dodaje pole terminalSequence w danych wyjściowych hooka dla powiadomień desktopowych, tytułów okien i dzwonków bez terminala sterującego.⁵⁰ Należy traktować to jako sygnalizację dla operatora, a nie egzekwowanie zasad. Bramki bezpieczeństwa i jakości nadal powinny komunikować niepowodzenia przez standardowy kontrakt blokowania: ustrukturyzowane dane wyjściowe hooka oraz zachowanie exit, które zapobiega niebezpiecznemu działaniu. Ta sama wersja dodaje claude agents --cwd <path> do ograniczania Agent View do jednego katalogu, CLAUDE_CODE_PLUGIN_PREFER_HTTPS dla instalacji pluginów w środowiskach bez kluczy GitHub SSH oraz ANTHROPIC_WORKSPACE_ID dla reguł federacji tożsamości obciążeń obejmujących więcej niż jeden workspace.⁵⁰ Są to szczegóły architektoniczne dla zespołowych harness: węższe widoki operacyjne, mniej założeń dotyczących instalacji pluginów i jawne zakresowanie tokenów przedsiębiorstwa.

Claude Code v2.1.142 jest istotniejszy dla orkiestracji sesji działających w tle niż dla semantyki hooków.⁵¹ claude agents może teraz wysyłać sesje działające w tle z jawnymi flagami katalogu, ustawień, MCP, pluginu, uprawnień, modelu i nakładu pracy, zamiast polegać na stanie wrappera. W tej wersji tryb Fast domyślnie korzystał z Opus 4.7, z CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 jako przypięciem dla harness o zmierzonej zależności od zachowania Opus 4.6 — od v2.1.219 Opus 4.7 nie jest już w ogóle dostępny w trybie fast, a /fast dotyczy Opus 5 i Opus 4.8.⁸⁴ Wykrywanie głównego pliku pluginu SKILL.md oraz widoczność LSP udostępnianego przez plugin zmniejszają niejednoznaczność pakowania. Poprawki dotyczące MCP_TOOL_TIMEOUT, istniejących wcześniej worktree sesji działających w tle, usypiania/wybudzania daemona i czyszczenia po aktualizacji, a także czyszczenia cache pluginów, zamykają luki w niezawodności, które w przeciwnym razie wyglądają jak błędy orkiestracji.

Sterowanie hookiem Stop, uprawnienia między sesjami i multi-agent v2 (czerwiec 2026)

Cztery zmiany z początku czerwca mają znaczenie dla projektowania harness i multi-agent.⁵⁹

Hooki Stop/SubagentStop zyskały kanał sterowania. Od Claude Code v2.1.163 hook Stop lub SubagentStop może zwrócić hookSpecificOutput.additionalContext, aby przekazać Claude informacje zwrotne i utrzymać turę, bez oznaczania odpowiedzi jako błąd hooka. Wcześniej jedyną realną dźwignią hooka Stop była blokada exit-2, która jest odczytywana jako błąd i liczy się do limitu kolejnych blokad. Dla harness z bramką jakości jest to czystszy mechanizm: hook Stop, który wykryje „uznałeś zadanie za zakończone, ale testy są czerwone”, może teraz wstrzyknąć „oto co nadal nie działa, kontynuuj” zamiast twardo blokować. Blokady należy używać w przypadku rzeczywistych warunków zatrzymania, a additionalContext dla komunikatu „to jeszcze nie koniec — oto dlaczego”.

Komunikacja między sesjami nie przenosi już pożyczonych uprawnień. v2.1.166 wzmocnił przypadek wielosesyjny: wiadomości przekazywane przez SendMessage z innej sesji Claude nie przenoszą już uprawnień pierwotnego użytkownika, dlatego sesja odbierająca odrzuca przekazywane żądania uprawnień, a tryb automatyczny je blokuje. Jeśli orkiestracja zakłada wymianę wiadomości między agentami, przychodzącą wiadomość należy traktować jako niezaufane dane, a nie jako uwierzytelnioną instrukcję. Jest to ta sama zasada, którą sekcja bezpieczeństwa stosuje do danych wyjściowych narzędzi, rozszerzona na komunikację między agentami. Od v2.1.199 Claude Code wykrywa także i ostrzega, gdy SendMessage zostanie błędnie skierowane, ponieważ dwóch agentów ma tę samą nazwę — jest to uzupełnienie niezawodnościowe tej granicy uprawnień, ponieważ wiadomość docierająca do niewłaściwego agenta o tej samej nazwie stanowi odrębną klasę błędu orkiestracji. Sesje są teraz równorzędnymi podmiotami pierwszej klasy (v2.1.224+). Komunikacja między sesjami przeszła od wzmacniania relay do pełnoprawnej powierzchni: SendMessage/ListAgents umożliwiają sesjom wzajemne wykrywanie i przesyłanie wiadomości między maszynami (macOS/Linux), a po stronie odbiorcy dostępne są mechanizmy crossSessionInbound pozwalające akceptować, wstrzymywać lub odmawiać — natomiast self-hosted runners pozwalają sesjom webowym i mobilnym Claude Code wykonywać zadania na sprzęcie pod Państwa kontrolą. W architekturze harness oznacza to, że „sesja” staje się adresowalnym węzłem: wykrywanie, polityka przychodząca i opisana wyżej granica uprawnień są teraz prymitywami platformy, a nie skryptami skrzynki pocztowej (pełny kontrakt dokumentuje przewodnik Claude Code).⁸⁷ Towarzyszy temu jedna zmiana podejścia: tryb auto stanie się domyślnym trybem uprawnień w planach Pro, Max i Team 14 sierpnia 2026 r. — harness, który liczy na prompty trybu Manual jako mechanizm human-in-the-loop, powinien jawnie przypiąć defaultMode, zamiast to zakładać.⁸⁷

Odporność modelu stała się ustawieniem pierwszej klasy. Ustawienie fallbackModel tworzy teraz łańcuch maksymalnie trzech modeli zapasowych, wypróbowywanych kolejno, gdy model podstawowy jest przeciążony lub niedostępny, a tura automatycznie ponawia próbę raz na modelu zapasowym w przypadku nieoczekiwanych, niepodlegających ponowieniu błędów API. W przypadku długotrwale działającego autonomicznego harness zamienia to przejściową awarię modelu podstawowego w łagodne obniżenie jakości usługi, zamiast porzuconego uruchomienia. claude agents --json zyskało również pole waitingFor (v2.1.162), które pokazuje, na co czeka zablokowana sesja działająca w tle, na przykład prompt uprawnień — to korzyść obserwowalności dla każdego koordynatora sondującego flotę agentów.

Tryb bezpieczny do zarządzania clean-room i rozwiązywania problemów. Claude Code v2.1.169 dodaje flagę --safe-mode (oraz odpowiadającą jej zmienną środowiskową CLAUDE_CODE_SAFE_MODE), która uruchamia sesję z jednocześnie wyłączonymi wszystkimi dostosowaniami: CLAUDE.md, plugins, skills, hooks i serwerami MCP.⁶⁰ To przeciwieństwo harness — celowy clean-room. Należy go użyć, aby odpowiedzieć na pytanie, które prędzej czy później zadaje każdy operator: „czy to zachowanie pochodzi od modelu, czy od czegoś, co skonfigurowałem?”. Gdy hook uruchamia się nieprawidłowo, skill aktywuje się mimo że nie powinien albo serwer MCP zatruwa kontekst, --safe-mode zapewnia znaną, pustą bazę do porównania. Jest to również prymityw zarządzania: sposób uruchomienia czystego modelu bez trwałych uprawnień, które zwykle przyznaje harness, co ma znaczenie, gdy trzeba odtworzyć wynik bez wpływu zdefiniowanego przez operatora rusztowania.

Uwaga o poziomach modeli. Od Claude Code v2.1.197 (30 czerwca 2026 r.) Claude Sonnet 5 jest dostarczanym domyślnym modelem nowych sesji — natywny kontekst 1M, promocyjne ceny 2 USD/10 USD za MTok do 31 sierpnia — zastępując Opus 4.8 jako gotowy wybór. Ten przewodnik traktuje Opus 5 (claude-opus-5) jako zalecany domyślny model agentowy: model, na którym należy uruchamiać autonomiczne harnesses, chyba że świadomie zostanie wybrany inny, ponieważ długohoryzontowe pętle agentowe o wysokiej stawce to właśnie obszar, w którym głębia rozumowania Opus uzasadnia jego koszt. Opus 5 został wydany 24 lipca 2026 r. jako nowy domyślny Opus w Claude Code v2.1.219 — kontekst 1M, 5 USD/25 USD za MTok (ta sama cena co zastępowany Opus 4.8), tryb fast za 10 USD/50 USD przy prędkości około 2,5× większej od domyślnej — a Anthropic podaje, że ponad dwukrotnie przewyższa Opus 4.8 w Frontier-Bench v0.1, osiągając wynik CursorBench 3.2 Fable 5 z różnicą poniżej 0,5% przy połowie kosztu.⁸⁴⁹¹ Ta sama cena, większe możliwości i model, który Anthropic określa jako „znacznie silniejszy w weryfikowaniu swojej pracy i uważnym iterowaniu”, to rzadkie ulepszenie, które w pracy z harness nie wymaga argumentu kosztowego; migracja z 4.8 polega na zmianie identyfikatora. W przypadku pracy wrażliwej na koszty lub o dużej przepustowości, gdzie wygrywa stosunek szybkości do inteligencji, warto przejść na Sonnet 5. Ponad Opus znajduje się Claude Fable 5 (claude-fable-5), wydany 9 czerwca 2026 r. — nowy poziom opisany jako najpotężniejszy model Anthropic, system „Mythos-class” przystosowany do bezpiecznego użycia ogólnego, wybieralny w Claude Code v2.1.170 przez /model claude-fable-5.⁶⁰ Po wyższy poziom należy sięgać świadomie, przy decyzjach, w których sama głębia rozumowania uzasadnia koszt, a nie ustawiać go domyślnie dla całej floty. Przejście na Opus 5 ma dwie konsekwencje porządkowe: Opus 4.7 nie jest już dostępny w trybie fast (/fast dotyczy teraz Opus 5 i Opus 4.8), a zapasowy Fable-5 klasyfikatora trybu auto — „najlepszy dostępny model Opus” od v2.1.176 — wskazuje teraz Opus 5.⁸⁴

Codex wydał multi-agent v2. Codex CLI v0.137.0 zachowuje wybór środowiska uruchomieniowego przy każdym wątku, udostępnia bardziej przejrzyste wartości domyślne kontynuacji i metadanych dla uruchamianych agentów (hide_spawn_agent_metadata ma teraz domyślnie wartość true) oraz przekazuje surowe zdarzenia nadrzędne do odbiorców podrzędnych. Model subagent pozostaje jawny: wbudowane typy agentów default/worker/explorer, niestandardowi agenci definiowani w TOML oraz mechanizmy kontroli współbieżności (agents.max_threads domyślnie 6, agents.max_depth domyślnie 1). To samo wydanie dodaje rozszerzenie skills v1 z rozstrzyganiem katalogu skills w każdej turze oraz nowe zdarzenia współtwórców cyklu życia rozpoczęcia wątku/błędu tury, zmniejszając lukę względem powierzchni hook/skill Claude Code, przy jednoczesnym zachowaniu podejścia kernel-sandbox jako domyślnej granicy. Codex v0.138.0–v0.139.0 następnie wzmocnił multi-agent v2 pod kątem zastosowań produkcyjnych: ładunki wiadomości między agentami są teraz szyfrowane, katalog konfiguracji agentów v2 wraz z LRU rezydencji agentów zarządza tym, którzy agenci pozostają rezydentni, a współbieżność jest liczona według aktywnego wykonania, a nie uruchomionych wątków, więc bezczynni agenci nie zajmują już slotu.⁶¹ Cykl życia API również dojrzał — close_agent przemianowano na interrupt_agent (v0.139.0), aby odzwierciedlić, że przerywa działającego agenta, a nie tylko zamyka uchwyt — a ostrzeżenia startowe MCP zgłoszone przez subagent pozostają teraz ograniczone do wątku właściciela, zamiast powielać się w transkrypcji rodzica.⁶¹ Dla każdego, kto buduje orkiestrację po stronie Codex, są to różnice między demonstracją a flotą: szyfrowany transport wiadomości, ograniczona rezydencja, współbieżność liczona według wykonań i ostrzeżenia, które nie przekraczają granicy wątku. Codex v0.140.0 otworzył następnie szczelinę między narzędziami: /import selektywnie pobiera konfigurację, konfigurację projektu i ostatnie czaty z Claude Code do Codex, a sesje stały się trwale usuwalne (codex delete / /delete, z zabezpieczeniami potwierdzenia).⁶⁴ /import to pierwsze oficjalne uznanie, że operatorzy przemieszczają się między harnesses — konfiguracja zbudowana dla jednego z nich nie jest już w nim uwięziona.

Pamięć i kontekst

Każda rozmowa z AI działa w ramach ograniczonego okna kontekstu. Wraz z rozwojem rozmowy system kompresuje wcześniejsze tury, aby zrobić miejsce na nową treść. Kompresja jest stratna. Decyzje architektoniczne udokumentowane w turze 3 mogą nie przetrwać do tury 15.⁹

Trzy mechanizmy załamania w rozmowach wieloturowych

Badanie MSR/Salesforce zidentyfikowało trzy niezależne mechanizmy, z których każdy wymaga innej interwencji:⁹

Strategia 1: System plików jako pamięć

Najbardziej niezawodna pamięć ponad granicami kontekstu znajduje się w systemie plików. Claude Code odczytuje CLAUDE.md i pliki pamięci na początku każdej sesji oraz po każdej kompresji.⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

Plik MEMORY.md przechowuje błędy, decyzje i wzorce między sesjami. Gdy odkryje Pan/Pani, że ((VAR++)) nie działa z set -e w bash, gdy VAR ma wartość 0, należy to zapisać. Trzy sesje później, gdy napotka Pan/Pani podobny przypadek brzegowy liczb całkowitych w Python, wpis w MEMORY.md ujawni ten wzorzec.¹⁵

Auto Memory (v2.1.32+): Claude Code automatycznie zapisuje i przywołuje kontekst projektu. Podczas pracy Claude zapisuje obserwacje w ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory ładuje pierwsze 200 wierszy do promptu systemowego na początku sesji. Warto zachować zwięzłość i umieszczać odnośniki do osobnych plików tematycznych zawierających szczegółowe notatki.⁶ Od wersji v2.1.210 zapis do MEMORY.md, który przekracza limit rozmiaru, kończy się błędem zamiast cichego obcięcia⁶⁹ — problem jest widoczny w chwili zapisu, a nie jako wpisy pamięci, które po cichu zniknęły. Jeśli harness automatyzuje zapisy pamięci, należy obsłużyć ten błąd; platforma sygnalizuje w ten sposób, że plik wymaga kuracji, a nie ponowienia próby.

Kuracja pamięci zamiast jej objętości (maj 2026): Niedawny preprint na arXiv dotyczący współpracy agentów LLM przedstawia rozszerzone przywoływanie jako możliwy tryb awarii: w eksperymentach autorów dłuższa widoczna historia pogorszyła współpracę w 18 z 28 ustawień gier modelowych.⁴⁸ Należy traktować to jako ostrzeżenie projektowe, a nie jako ostateczne prawo. Zasada produkcyjna jest już wystarczająco jasna: MEMORY.md powinien być krótki, szczegóły należy umieszczać w podlinkowanych plikach, a w przekazaniach pozostawiać podsumowania gotowe do podjęcia decyzji. Surowe zrzuty transkrypcji, logi narzędzi i długie kanały przywoływania powinny trafiać do przeszukiwalnego magazynu, a nie automatycznie do aktywnego promptu.

Strategia 2: Proaktywna kompresja

Polecenie /compact Claude Code podsumowuje rozmowę i zwalnia miejsce w kontekście, zachowując kluczowe decyzje, zawartość plików i stan zadania.¹⁵

Kiedy kompresować: - Po ukończeniu wyodrębnionego podzadania (zaimplementowana funkcja, naprawiony błąd) - Przed rozpoczęciem pracy w nowym obszarze codebase - Gdy Claude zaczyna powtarzać się lub zapominać wcześniejszy kontekst - Mniej więcej co 25–30 minut podczas intensywnych sesji

Niestandardowe instrukcje kompresji w CLAUDE.md:

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

Kompresja chroni rozmowę; polecenie /cd (Claude Code v2.1.169) chroni cache promptu. Przenosi sesję do nowego katalogu roboczego w trakcie pracy, nie przerywając cache zgromadzonego w turze.⁶⁰ Wcześniej zmiana katalogu oznaczała nową sesję i zimny cache. W przypadku długotrwałej sesji, która przechodzi z jednego repozytorium do sąsiedniego — co jest częste w pracy z monorepo i wieloma usługami — /cd zachowuje kosztowny prefiks cache, jednocześnie przekierowując kontekst systemu plików.

Strategia 3: Przekazania sesji

W przypadku zadań obejmujących wiele sesji należy tworzyć dokumenty przekazania, które ujmują pełny stan:

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

Struktura Status/Files/Decision/Blocked/Next zapewnia kolejnej sesji pełny kontekst przy minimalnym koszcie tokenów. Rozpoczęcie nowej sesji za pomocą claude -c (continue) lub odczytanie dokumentu przekazania pozwala od razu przejść do implementacji.¹⁵

Strategia 4: Iteracja ze świeżym kontekstem (pętla Ralph)

W przypadku sesji przekraczających 60–90 minut należy uruchamiać nową instancję Claude dla każdej iteracji. Stan utrzymuje się za pośrednictwem systemu plików, a nie pamięci konwersacyjnej. Każda iteracja otrzymuje pełny budżet kontekstu:¹⁶

Iteration 1: [fresh context] -> writes code, creates files, updates state
Iteration 2: [fresh context] -> reads state from disk, continues
Iteration 3: [fresh context] -> reads updated state, continues
...
Iteration N: [fresh context] -> reads final state, verifies criteria

Porównajmy to z jedną długą sesją:

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

Podejście ze świeżym kontekstem na iterację zamienia 15–20% narzutu na etap orientacji (odczyt plików stanu, przegląd historii git) na pełne zasoby poznawcze w każdej iteracji.¹⁶ Rachunek kosztów i korzyści jest następujący: dla sesji krótszych niż 60 minut jedna rozmowa jest wydajniejsza. Powyżej 90 minut świeży kontekst daje wyższą jakość wyników mimo narzutu.

Strategia 5: Zarządzana kuracja pamięci (Dreaming)

Managed Agents Anthropic dodało Dreaming jako Research Preview 6 maja 2026 r.³⁵ Według Anthropic: „Dreaming to zaplanowany proces, który przegląda sesje agentów i magazyny pamięci, wyodrębnia wzorce oraz kuratoruje wspomnienia, aby agenci z czasem się doskonalili”.³⁵

Dreaming działa w tle między sesjami, a nie na ścieżce krytycznej. Uzupełnia wzorzec systemu plików jako pamięci, zamiast go zastępować: plik MEMORY.md pozostaje nośną powierzchnią; Dreaming zapisuje kuratorowane wpisy pamięci w magazynie pamięci Managed Agents, który agent odczytuje na początku sesji. Oba wzorce współistnieją w harnessach łączących samodzielnie hostowany stan systemu plików z kuracją po stronie zarządzanej.

Dreaming jest w Research Preview, więc jego działanie może się zmienić. Udokumentowane powyżej wzorce session-handoffs i CLAUDE.md pozostają autorytatywnym mechanizmem pamięci dla samodzielnie hostowanych harnesses.

Antywzorce

Odczytywanie całych plików, gdy potrzebnych jest 10 wierszy. Odczyt pojedynczego pliku liczącego 2 000 wierszy zużywa 15 000–20 000 tokenów. Należy używać przesunięć wierszy: Read file.py offset=100 limit=20 pozwala zaoszczędzić zdecydowaną większość tego kosztu.¹⁵

Przechowywanie w kontekście szczegółowego wyjścia błędów. Po debugowaniu błędu kontekst zawiera ponad 40 stack trace’ów z nieudanych iteracji. Pojedyncze /compact po naprawieniu błędu usuwa ten zbędny balast.

Rozpoczynanie każdej sesji od odczytywania każdego pliku. Warto pozwolić narzędziom glob i grep Claude Code znajdować odpowiednie pliki na żądanie, oszczędzając ponad 100 000 tokenów niepotrzebnego wstępnego ładowania.¹⁵

Wzorce subagents

Subagents to wyspecjalizowane instancje Claude, które samodzielnie realizują złożone zadania. Większość rozpoczyna pracę z czystym kontekstem (bez treści z głównej rozmowy) — wyjątkiem jest opisany poniżej typ fork, który celowo dziedziczy cały kontekst — korzysta z określonych narzędzi i zwraca wyniki w formie podsumowań. Wyniki eksploracji nie rozbudowują niepotrzebnie głównej rozmowy; wracają do niej wyłącznie wnioski.⁵

Wbudowane typy subagents

Tworzenie niestandardowych subagents

Subagents definiuje się w .claude/agents/ (projektowe) lub ~/.claude/agents/ (osobiste):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Pola konfiguracji subagents

Izolacja worktree

Subagents mogą działać w tymczasowych git worktrees, które zapewniają kompletną, odizolowaną kopię repozytorium:⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

Izolacja worktree jest niezbędna podczas prac eksperymentalnych, które mogą uszkodzić bazę kodu.

Izolacja jest izolacją tylko wtedy, gdy granica rzeczywiście pozostaje szczelna. W Claude Code v2.1.210 naprawiono błąd, przez który subagents odizolowane za pomocą worktree mogły modyfikować główny checkout — czyli powodować dokładnie ten problem, któremu ten mechanizm ma zapobiegać.⁶⁹ Jeśli isolation: worktree pełni funkcję granicy bezpieczeństwa, a nie tylko udogodnienia, za wersję minimalną należy uznać v2.1.210. Towarzysząca temu zmiana uprawnień działa jednak w przeciwnym kierunku: od v2.1.211 reguły „always allow” są utrwalane w katalogu głównym repozytorium między worktrees, więc reguła zaakceptowana w jednym worktree obowiązuje także w innych worktrees tego samego repozytorium.⁶⁹ To właściwe rozwiązanie ergonomiczne dla agentów pracujących równolegle w worktrees, lecz oznacza również, że zezwolenie udzielone podczas jednorazowego eksperymentu pozostaje aktywne po jego zakończeniu — należy go udzielać z myślą o całym repozytorium, nie tylko o aktualnie używanym worktree.

Wersja v2.1.216 dokończyła te prace, przenosząc izolację worktree z poziomu poprawki błędu na poziom mechanizmu nadającego się do egzekwowania zabezpieczeń.⁷⁴ Poprawka z v2.1.210 uniemożliwiła subagents działającym w odizolowanym worktree modyfikowanie głównego checkoutu za pomocą zwykłego wywołania git, lecz sam git umożliwia jawne przekierowanie — przez git -C <path>, --git-dir oraz zmienne środowiskowe GIT_DIR/GIT_WORK_TREE — dlatego subagent odizolowany w worktree nadal mógł wskazać za pomocą dowolnego z tych mechanizmów współdzielony checkout. Wszystkie te drogi obejścia są teraz zamknięte. W tym samym wydaniu naprawiono sporadyczne uruchamianie sesji worktree w pozostałości worktree należącej do innego projektu, uniemożliwiono zapisom workflow i zaplanowanych zadań podążanie za dowiązaniem symbolicznym umieszczonym w .claude i prowadzącym poza projekt oraz zmieniono /rewind tak, by odmawiał przechodzenia przez dowiązania symboliczne i twarde. Wzorzec wspólny dla wszystkich czterech poprawek jest taki sam: granica izolacji musi być odporna na celowe przekierowanie — nadpisanie środowiska git czy podłożenie dowiązania symbolicznego — a nie tylko na zachowanie domyślne. Jeśli isolation: worktree stanowi w harness granicę bezpieczeństwa, a nie jedynie udogodnienie, nową wersją minimalną jest v2.1.216.

Równoległe subagents

Równoległych subagents warto używać do niezależnych zadań badawczych, które nie wymagają wzajemnej koordynacji:⁵

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Każdy agent działa we własnym oknie kontekstu, znajduje odpowiedni kod i zwraca podsumowanie. Główny kontekst pozostaje czysty.

Recursion guard

Bez limitów uruchamiania agenci delegują zadania agentom, którzy delegują je kolejnym agentom, a każdy z nich traci część kontekstu i zużywa tokeny. Wzorzec recursion guard wymusza przestrzeganie budżetów:¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Kluczowy wniosek: Należy stosować budżety uruchomień, a nie wyłącznie limity głębokości. Limity oparte na głębokości śledzą łańcuchy proces nadrzędny–proces potomny (blokując je na głębokości 3), lecz nie uwzględniają szerokości: 23 agentów na głębokości 1 nadal oznacza „głębokość 1”. Budżet uruchomień śledzi łączną liczbę aktywnych procesów potomnych przypadających na proces nadrzędny, ograniczoną konfigurowalnym maksimum. Model budżetowy odpowiada rzeczywistemu trybowi awarii (zbyt wielu agentów łącznie), zamiast opierać się na wskaźniku zastępczym (zbyt wielu poziomach zagnieżdżenia).⁷

Domyślna głębokość zagnieżdżenia zmieniała się już 3 razy; nie należy opierać na niej architektury. Claude Code v2.1.172 (10 czerwca 2026) umożliwił sub-agents uruchamianie własnych sub-agents i zagnieżdżanie ich do 5 poziomów — wcześniej delegowanie było w praktyce ograniczone do jednego poziomu.⁶² Tak pozostało od v2.1.172 do v2.1.216. Wersja v2.1.217 (21 lipca 2026) zmniejszyła limit do 1, domyślnie wyłączając zagnieżdżone uruchamianie. Następnie v2.1.219 (24 lipca 2026) przyjęła rozwiązanie pośrednie: „Subagents mogą teraz domyślnie uruchamiać zagnieżdżone subagents do głębokości 3 (wcześniej 1); ustawienie CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 wyłącza zagnieżdżanie”.⁸⁴ Najpierw 5, potem 1, następnie 3 — a dwie ostatnie zmiany w ciągu 3 dni.

Nie należy z tego wyciągać wniosku, że którakolwiek z tych wartości jest prawidłowa. Istotne jest to, że platforma nadal poszukuje odpowiedniej wartości domyślnej, dlatego dziedziczenie „tego, co akurat dostarcza platforma” nie jest właściwym rozwiązaniem dla harness. Głębokość zagnieżdżenia należy traktować jako jawną pozycję budżetu: ustawić CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH na poziomie rzeczywiście wymaganym przez architekturę — w przypadku większości orkiestracji jest to 1 lub 2 — aby aktualizacja nie mogła po cichu zmienić głębokości delegowania przez flotę. Niezależnie od tych zmian główny argument pozostaje taki sam: łańcuchy agentów delegujących zadania kolejnym agentom zużywają kontekst i tokeny szybciej, niż dostarczają wyniki, a głębokość jest zagrożeniem, które trzeba uwzględnić w budżecie, nie zaś funkcją, po którą warto sięgać. Opisany powyżej recursion guard zapobiega rozrośnięciu się głębokiego drzewa do setek aktywnych agentów niezależnie od kierunku kolejnej zmiany wartości domyślnej, a tylko samodzielnie ustawiony limit głębokości zachowa oczekiwane znaczenie po następnym wydaniu.

Tryb automatyczny weryfikuje teraz uruchomienia przed ich rozpoczęciem. Claude Code v2.1.178 usunął powiązaną lukę w mechanizmie nadzoru: w trybie automatycznym uruchomienia subagents są oceniane przez klasyfikator uprawnień przed uruchomieniem subagenta, a nie dopiero wtedy, gdy zaczyna on wykonywać działania.⁶³ Wcześniej można było uruchomić subagenta w celu zażądania działania, którego wykonanie byłoby zablokowane dla sesji nadrzędnej — samo uruchomienie stanowiło obejście zabezpieczeń. Weryfikacja w chwili uruchamiania oznacza, że recursion guard i model uprawnień wreszcie się uzupełniają: proces potomny nie może służyć jako pośrednik maskujący działanie zabronione przez zasady.

Platforma oferuje teraz natywny budżet uruchomień. Claude Code v2.1.212 (lipiec 2026) wprowadził wbudowane zabezpieczenia przed niekontrolowanymi pętlami: domyślny limit wynosi 200 uruchomień subagents na sesję (CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION pozwala go dostosować, a /clear zeruje licznik), natomiast WebSearch ma limit 200 wywołań na sesję (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ Wzorzec budżetu uruchomień, który od v1.0 dokumentowano w tej sekcji jako skrypt implementowany przez użytkownika, jest teraz zapewniany przez platformę — potwierdza to przewagę modelu budżetowego nad modelem głębokości. Warto jednak zwrócić uwagę na kalibrację: 200 uruchomień to o rząd wielkości więcej niż budżet 12 agentów w powyższej konfiguracji. Natywne limity stanowią bezpieczniki chroniące przed naprawdę niekontrolowaną pętlą, a nie budżety dostrojone do konkretnej architektury. Należy zachować własny mechanizm ochronny dla budżetów przypadających na proces nadrzędny, śledzenia głębokości i limitów odpowiadających rzeczywistym założeniom orkiestracji; limit platformy powinien wychwytywać wszystko, co zdoła go ominąć.

Zestaw wbudowanych zabezpieczeń obejmuje teraz 4 osie. 3 z nich zabezpieczają dokładnie te wartości, które śledzi opisany w tej sekcji mechanizm użytkownika: łączną liczbę uruchomień na sesję (v2.1.212, limit 200, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), głębokość zagnieżdżenia (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, obecnie domyślnie 3 i, jak wykazano, wartość niestabilna) oraz liczbę równoczesnych wykonań (v2.1.217, domyślnie 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS — pojedyncza wiadomość nie może już bez ograniczeń rozwinąć się w agentów działających w tle).⁷⁸⁸⁴ Wersja v2.1.219 dodaje 4. oś, której zazwyczaj nie obejmowały mechanizmy użytkownika: szerokość orkiestracji, czyli liczbę agentów dozwolonych w pojedynczym zaplanowanym workflow, dostarczoną jako domyślna wytyczna „należy dążyć do mniej niż 15 agentów” i konfigurowalną z dowolnego pliku ustawień za pomocą workflowSizeGuideline (omówionego poniżej w sekcji Workflow Tool). Wzorzec budżetu uruchomień jest teraz zabezpieczony przez platformę na każdej osi, do której został zaprojektowany, oraz na jednej dodatkowej.

Uwaga dotycząca kalibracji nadal obowiązuje, choć w nierównym stopniu. Limity 200 uruchomień i 20 agentów działających równocześnie to bezpieczniki — o rząd wielkości wyższe niż budżet 12 agentów do deliberacji w powyższej konfiguracji, dobrane tak, aby wykrywać niekontrolowane pętle, a nie kształtować architekturę. Wytyczna szerokości jest pierwszą natywną wartością należącą do tej samej kategorii co rzeczywisty budżet: 15 agentów na workflow jest bardzo bliskie wartości 12 przyjętej w tym przewodniku, więc zastosowanie wartości domyślnej platformy niczego nie kosztuje, a jej odrzucenie powinno wynikać z konkretnego powodu. 3 bezpieczniki należy ustawić na wartości, które można uzasadnić; wytyczną szerokości — zgodnie z zamierzonym kształtem orkiestracji.

Agent Teams (Research Preview)

Agent Teams koordynują wiele instancji Claude Code, które pracują niezależnie, komunikują się przez współdzieloną skrzynkę i listę zadań oraz mogą podważać wzajemne ustalenia:⁵

Włączanie: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Kiedy używać agent teams, a kiedy subagents:

Agent View i pętle celów (maj 2026)

Claude Code v2.1.139 dodał Agent View, interfejs w wersji Research Preview uruchamiany poleceniem claude agents, który na jednym ekranie pokazuje działające, zablokowane i zakończone sesje Claude Code.⁴²⁴³ Oficjalna dokumentacja przedstawia go jako sposób na przydzielanie wielu sesji i zarządzanie nimi, obserwowanie działań każdej sesji oraz identyfikowanie tych, które wymagają interwencji operatora.⁴³ Zapewnia to widok operacyjny pracy wielu agentów, którego nie mogą zastąpić końcowe podsumowania.

Podczas wdrażania wzorca opartego na subagents lub zespole warto używać Agent View, aby sprawdzać, które sesje są zablokowane, które nadal działają i czy rozkład pracy odpowiada zamierzonej architekturze. Nie należy jednak traktować go jako dowodu jakości. Zapewnia obserwowalność; o poprawności pracy nadal decydują testy, bramki przeglądu i raporty evidence gate.

W tym samym wydaniu dodano /goal, które określa warunek ukończenia i pozwala Claude kontynuować pracę przez wiele tur aż do spełnienia tego warunku, również w trybie interaktywnym, -p i Remote Control.⁴² /goal należy traktować jako pętlę ukończenia o zakresie sesji, a nie jako zamiennik deterministycznych bramek. Pomaga utrzymać koncentrację agenta na celu, lecz testy, weryfikacja cytowań, kontrola wdrożeń i security hooks powinny nadal opierać się na poleceniach lub skryptach wszędzie tam, gdzie niepowodzenie musi blokować dalsze działania.

Workflow Tool (v2.1.147+)

Dynamiczne workflows w Claude Code są już dostępną i domyślnie włączoną funkcją: od v2.1.154 koordynują w tle od dziesiątek do setek agentów, są monitorowane za pomocą /workflows, mają opcję /config „Dynamic workflow size” (v2.1.202) oraz klucz ustawień workflowSizeGuideline, którego domyślna wytyczna ma rozmiar średni — należy dążyć do mniej niż 15 agentów, chyba że wskazano inaczej (v2.1.219). Funkcja zadebiutowała wydanie wcześniej jako domyślnie wyłączone narzędzie Workflow w v2.1.147, ukryte za CLAUDE_CODE_WORKFLOWS=1; okres używania tej flagi należy już do historii, lecz przedstawiony wówczas argument architektoniczny pozostaje aktualny.⁵² Daje ona Claude Code wbudowany mechanizm orkiestracji dla przepływów, które wcześniej wymagały niestandardowych skryptów dispatch, stanu mailbox i konwencji koordynowania subagents.

Nie należy usuwać otaczającego go harness. Workflow może nadawać strukturę wykonaniu, lecz nie zastępuje modelu bezpieczeństwa. PreToolUse i PostToolUse hooks powinny pozostać warstwą blokującą, budżety uruchomień lub budżety kroków workflow muszą zapobiegać niekontrolowanemu wzrostowi szerokości, stan systemu plików powinien pozostać audytowalny, a końcowe raporty evidence gate nie mogą zależeć od samooceny modelu. W praktyce: Workflow należy stosować do określania kształtu orkiestracji, natomiast hooks, testy i bramki przeglądu — do ustalania prawdy.

Dynamiczne workflows mają teraz wbudowaną opinię na temat szerokości (v2.1.219). Domyślna wytyczna rozmiaru dynamicznych workflows to poziom średni — „należy dążyć do mniej niż 15 agentów” — przy czym w ustawieniu Dynamic workflow size w /config dostępne są inne rozmiary oraz opcja bez ograniczeń, a bieżąca wytyczna jest wyświetlana w wierszu stanu działającego workflow.⁸⁴ Wartość ta ma charakter doradczy, a nie wymuszany; ukierunkowuje planer zamiast blokować szeroki plan. O jej przydatności konfiguracyjnej decyduje sposób dystrybucji: nowy klucz ustawień workflowSizeGuideline można ustawić w dowolnym pliku ustawień — w tym w ustawieniach zarządzanych i projektowych, a od v0.3.219 jest on obecny w typach ustawień TypeScript SDK — dzięki czemu szerokość orkiestracji może zostać ustandaryzowana przez zespół lub organizację, zamiast być ponownie ustalana przez każdego operatora.⁸⁵ Należy ustawić ją na poziomie projektu, aby odzwierciedlała rzeczywisty sposób podziału pracy w bazie kodu. Dwie uwagi dla operatorów: wiersz /config jest ukrywany, gdy wartość pochodzi z pliku ustawień, co jest prawidłowym zachowaniem, lecz bez znajomości przyczyny może wyglądać jak brak ustawienia; ponadto, ponieważ wytyczna kieruje planerem zamiast blokować wykonanie, należy do kolumny kształtu, nie bezpieczeństwa. Za niekontrolowany wzrost szerokości nadal odpowiada limit uruchomień.

Warto zachować następującą perspektywę: jest to 4. oś wbudowanych zabezpieczeń — szerokość orkiestracji, obok liczby uruchomień, głębokości zagnieżdżenia i liczby równoczesnych wykonań — oraz pierwsza, którą Anthropic skalibrował do realistycznego rozmiaru roboczego, a nie do poziomu bezpiecznika chroniącego przed niekontrolowanym wzrostem. 15 agentów na workflow należy do tego samego rzędu wielkości co budżet 12 agentów do deliberacji stosowany w tym przewodniku od v1.0. Gdy wartość domyślna platformy i własny budżet, ustalone z różnych perspektyw, zbiegają się, stanowi to najbliższy odpowiednik niezależnego potwierdzenia, jaki można uzyskać dla takich wartości.

Forkowanie sesji i automatyczne przenoszenie MCP do tła (lipiec 2026)

Claude Code v2.1.212 przekształcił dwa mechanizmy orkiestracji.⁶⁹ /fork tworzy teraz nową sesję w tle na podstawie bieżącego stanu rozmowy — odgałęziona sesja działa niezależnie, podczas gdy oryginalna kontynuuje pracę — a poprzednie zachowanie wewnątrz sesji zmieniło nazwę na /subtask. Różnica ta ma znaczenie dla projektowania orkiestracji: /subtask to ograniczone zadanie poboczne w cyklu życia jednej sesji; /fork jest prostym sposobem utworzenia równoległej sesji w tle dziedziczącej pełny kontekst, bliższym uruchomieniu pętli Ralph niż subagentowi. Jeśli skrypty harness zakładały, że /fork pozostaje wewnątrz sesji, obecnie będą przydzielać pracę do tła.

W tym samym wydaniu wolne wywołania MCP są automatycznie przenoszone do tła: wywołanie narzędzia MCP, które trwa dłużej niż 2 minuty, zostaje automatycznie przeniesione do wykonania w tle (próg można dostosować za pomocą CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS).⁶⁹ Wolny serwer MCP nie blokuje już pętli agentowej — oznacza to jednak również, że „narzędzie zwróciło wynik” i „tura była kontynuowana” nie są już tym samym zdarzeniem, dlatego hooks lub skrypty zakładające synchroniczne zakończenie MCP powinny opierać się na wyniku narzędzia, a nie na granicy tury.

Na potrzeby orkiestracji bez interfejsu v2.1.211 dodał --forward-subagent-text (zmienna środowiskowa: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT), które przekazuje tekst odpowiedzi subagenta do wyjścia stream-json.⁶⁹ Proces koordynujący, który odbiera strumień procesu nadrzędnego, może teraz bezpośrednio obserwować postęp subagents, zamiast odpytywać transkrypcje lub czekać na końcowe podsumowanie — jest to obserwowalnościowe uzupełnienie domyślnie działających w tle subagents. Wersja v2.1.219 rozszerzyła tę funkcję poza pierwszy poziom: subagents uruchomione na głębokości 2 lub większej również pojawiają się w przekazywanym strumieniu, oznaczone identyfikatorem tool_use narzędzia Agent, które je uruchomiło.⁸⁴ To właśnie ten klucz powinien stanowić podstawę implementacji. Po ponownym domyślnym włączeniu zagnieżdżania płaski strumień tekstu subagents jest niejednoznaczny — identyfikator informuje koordynator, który proces nadrzędny utworzył dany proces potomny, dzięki czemu drzewo delegowania można odtworzyć ze strumienia zamiast je odgadywać. Jeśli odbiorca strumienia został napisany z myślą o jednym poziomie subagents, zobaczy teraz tekst agentów, o których istnieniu wcześniej nie wiedział; należy grupować dane według identyfikatora tool_use uruchamiającego procesu, zamiast zakładać, że każdy przekazany wiersz pochodzi od bezpośredniego procesu potomnego.

Orkiestracja wieloagentowa

Jednoagentowe systemy AI mają strukturalną słabość: nie potrafią podważać własnych założeń.⁷ Wieloagentowa deliberacja wymusza niezależną ocenę z wielu perspektyw, zanim jakakolwiek decyzja zostanie utrwalona.

Orkiestracja między narzędziami (kwiecień 2026): Google udostępnił jako open source Scion 7 kwietnia — wieloagentowy hiperwizor uruchamiający Claude Code, Gemini CLI oraz inne „głębokie agenty” jako równoległe procesy, każdy z odizolowanym kontenerem, git worktree i poświadczeniami. Działa lokalnie, jako hub lub w Kubernetes. Jawna filozofia: „isolation over constraints” — agenty działają z dużą autonomią w granicach wymuszanych na poziomie infrastruktury, a nie w prompt.²⁵ Bezpośrednio rozszerza to argument za izolacją subagents na różnych dostawców narzędzi. Jeśli workflow obejmuje Claude i modele OpenAI, Scion jest pierwszą realną implementacją referencyjną dla subagents między narzędziami z izolacją worktree + poświadczeń dla każdego agenta.

Debata nie jest panaceum: Klaster badań M3MAD-Bench (początek 2026) wykazał, że wieloagentowa debata osiąga plateau i może zostać wypaczona przez wprowadzający w błąd konsensus — trafne argumenty przegrywają, gdy inne agenty z przekonaniem twierdzą, że poprawna jest błędna odpowiedź.²⁶ Tool-MAD poprawia ten mechanizm, zapewniając każdemu agentowi heterogeniczny dostęp do narzędzi i używając ocen Faithfulness/Relevance na etapie sędziego. Przy budowaniu orkiestracji opartej na debacie warto inwestować w (a) heterogeniczność narzędzi dla każdego agenta oraz (b) ilościową punktację sędziego, zamiast zakładać, że więcej agentów = lepsze odpowiedzi.

Zarządzana orkiestracja wieloagentowa i Outcomes (Public Beta)

Jeśli nie chce Pan/Pani budować opisanej poniżej infrastruktury deliberacyjnej, Multiagent Orchestration weszło do Public Beta w Claude Managed Agents 6 maja 2026 r.³⁵ Według Anthropic: „When there is too much work for a single agent to do well, multiagent orchestration lets a lead agent break the job into pieces and delegate each one to a specialist with its own model, prompt, and tools.”³⁵ Specjaliści „pracują równolegle we współdzielonym systemie plików i wnoszą wkład do ogólnego kontekstu agenta prowadzącego”.³⁵

Śledzenie jest dostępne od razu. Według Anthropic: „you can also trace every step in the Claude Console: which agent did what, in what order, and why, giving you full visibility into how your task was delegated and executed.”³⁵

Towarzyszącą funkcją Public Beta jest Outcomes. Według Anthropic: „you write a rubric describing what success looks like and the agent works toward it. A separate grader evaluates the output against your criteria in its own context window, so it isn’t influenced by the agent’s reasoning.”³⁵ Jest to wersja managed service wzorca walidacji z dwiema bramkami, udokumentowanego w dalszej części tej sekcji: rubryka zastępuje ręcznie napisaną bramkę, a oddzielny oceniający zastępuje walidator konsensusu.

Samodzielnie hostowana deliberacja pozostaje właściwym rozwiązaniem, gdy walidacja musi integrować się z własną powierzchnią hooków (blokowanie PreToolUse, semantyka kodów wyjścia, niestandardowe dispatchers) lub gdy harness musi działać bez zewnętrznych zależności. Managed Multiagent jest właściwym rozwiązaniem, gdy rzeczywiście potrzebnym kontraktem jest standardowe delegowanie wraz z oceną według rubryki.

Minimalna działająca deliberacja

Należy zacząć od 2 agentów i 1 zasady: agenty muszą ocenić pracę niezależnie, zanim zobaczą wyniki pozostałych.⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

Ten wzorzec zapewnia 80% wartości. Wszystko pozostałe wnosi jedynie stopniową poprawę.

Wyzwalacz ufności

Nie każde zadanie wymaga deliberacji. Moduł oceny ufności analizuje cztery wymiary:¹⁷

1. Niejednoznaczność - Czy zapytanie ma wiele poprawnych interpretacji?
2. Złożoność dziedziny - Czy wymaga specjalistycznej wiedzy?
3. Stawka - Czy decyzja jest odwracalna?
4. Zależność od kontekstu - Czy wymaga zrozumienia szerszego systemu?

Wynik jest mapowany na trzy poziomy:

Próg dostosowuje się do typu zadania. Decyzje dotyczące bezpieczeństwa wymagają konsensusu na poziomie 0.85. Zmiany w dokumentacji potrzebują jedynie 0.50. Zapobiega to nadmiernemu rozbudowywaniu prostych zadań, a jednocześnie zapewnia kontrolę nad ryzykownymi decyzjami.⁷

Maszyna stanów

Siedem faz, z których każda jest bramkowana przez poprzednią:⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH: Niezależne agenty badają temat. Każdy agent otrzymuje inną personę (Technical Architect, Security Analyst, Performance Engineer i inne). Izolacja kontekstu zapewnia, że podczas researchu agenty nie widzą wzajemnie swoich ustaleń.

DELIBERATION: Agenty widzą wszystkie wyniki researchu i tworzą alternatywy. Agent Debate identyfikuje konflikty. Agent Synthesis łączy niesprzeczne ustalenia.

RANKING: Każdy agent ocenia każde zaproponowane podejście w 5 ważonych wymiarach:

Architektura walidacji z dwiema bramkami

Dwie bramki walidacyjne wyłapują problemy na różnych etapach:⁷

Bramka 1: walidacja konsensusu (hook PostToolUse). Uruchamia się bezpośrednio po zakończeniu pracy każdego agenta deliberacyjnego: 1. Faza musi osiągnąć co najmniej RANKING 2. Muszą zakończyć pracę co najmniej 2 agenty (konfigurowalne) 3. Wynik konsensusu musi spełniać próg dostosowany do zadania 4. Jeśli którykolwiek agent zgłosił sprzeciw, obawy muszą zostać udokumentowane

Bramka 2: Pride Check (hook Stop). Uruchamia się, zanim sesja będzie mogła zostać zamknięta: 1. Różnorodne metody: reprezentowanych jest wiele unikalnych person 2. Przejrzystość sprzeczności: sprzeciwy mają udokumentowane uzasadnienia 3. Obsługa złożoności: wygenerowano co najmniej 2 alternatywy 4. Ufność konsensusu: sklasyfikowana jako wysoka (powyżej 0.85) lub umiarkowana (0.70-0.84) 5. Dowód poprawy: końcowy poziom ufności przewyższa poziom początkowy

Dwa hooki w różnych punktach cyklu życia odpowiadają temu, jak faktycznie dochodzi do błędów: niektóre są natychmiastowe (niski wynik), a inne narastają stopniowo (mała różnorodność, brak dokumentacji sprzeciwów).⁷

Dlaczego zgodność jest niebezpieczna

Charlan Nemeth badała zdania odrębne od 1986 r. aż do swojej książki z 2018 r. In Defense of Troublemakers. Grupy z osobami zgłaszającymi sprzeciw podejmują lepsze decyzje niż grupy, które szybko osiągają zgodę. Osoba zgłaszająca sprzeciw nie musi mieć racji. Sam akt niezgody zmusza większość do zbadania założeń, które w przeciwnym razie pominęłaby.¹⁸

Wu i in. sprawdzili, czy agenty LLM potrafią rzeczywiście debatować, i stwierdzili, że bez strukturalnych zachęt do niezgody agenty zbiegają się ku najbardziej pewnie brzmiącej początkowej odpowiedzi, niezależnie od jej poprawności.¹⁹ Liang i in. wskazali główną przyczynę jako „Degeneration-of-Thought”: gdy LLM nabierze pewności co do stanowiska, autorefleksja nie potrafi wygenerować nowych kontrargumentów, przez co wieloagentowa ocena staje się strukturalnie konieczna.²⁰

Niezależność jest kluczowym ograniczeniem projektowym. Dwa agenty oceniające tę samą strategię wdrożenia, mając wgląd we wzajemne ustalenia, uzyskały wyniki 0.45 i 0.48. Te same agenty bez takiego wglądu: 0.45 i 0.72. Różnica między 0.48 a 0.72 to koszt zachowania stadnego.⁷

Wykrywanie pozornej zgodności

Moduł wykrywania konformizmu śledzi wzorce sugerujące, że agenty zgadzają się bez rzeczywistej oceny:⁷

Skupienie wyników: Wyniki wszystkich agentów mieszczące się w przedziale 0.3 punktu w 10-punktowej skali sygnalizują zanieczyszczenie wspólnym kontekstem, a nie niezależną ocenę. Gdy pięć agentów oceniających refaktoryzację uwierzytelniania przyznało ryzyku bezpieczeństwa oceny od 7.1 do 7.4, ponowne uruchomienie ze świeżą izolacją kontekstu rozszerzyło zakres wyników do 5.8-8.9.

Szablonowy sprzeciw: Agenty kopiują język obaw innych agentów zamiast tworzyć niezależne zastrzeżenia.

Brak perspektyw mniejszościowych: Jednomyślna aprobata person o sprzecznych priorytetach (Security Analyst i Performance Engineer rzadko zgadzają się we wszystkim).

Detektor konformizmu wychwytuje oczywiste przypadki (około 10-15% deliberacji, w których agenty zbyt szybko osiągają zgodność). W pozostałych 85-90% przypadków bramki konsensusu i pride check zapewniają wystarczającą walidację.

Co nie zadziałało w deliberacji

Swobodne rundy debaty. Trzy rundy tekstowej wymiany zdań dotyczącej indeksowania bazy danych wygenerowały 7,500 tokenów debaty. Runda 1: rzeczywista niezgoda. Runda 2: powtórzone stanowiska. Runda 3: identyczne argumenty wyrażone innymi słowami. Ustrukturyzowana punktacja wymiarów zastąpiła swobodną debatę, obniżając koszt o 60% i jednocześnie poprawiając jakość rankingu.⁷

Pojedyncza bramka walidacyjna. Pierwsza implementacja uruchamiała jeden hook walidacyjny na końcu sesji. Agent zakończył deliberację z wynikiem konsensusu 0.52 (poniżej progu), po czym przez 20 minut kontynuował pracę nad niezwiązanymi zadaniami, zanim hook końca sesji oznaczył błąd. Podział na dwie bramki (jedną przy zakończeniu zadania, drugą na końcu sesji) wyłapał te same problemy w różnych punktach cyklu życia.⁷

Koszt deliberacji

Każdy agent researchu przetwarza około 5,000 tokenów kontekstu i generuje 2,000-3,000 tokenów ustaleń. Przy 3 agentach oznacza to 15,000-24,000 dodatkowych tokenów na decyzję. Przy 10 agentach — około 50,000-80,000 tokenów.⁷

Przy obecnych cenach Opus 5 ($5/$25 za MTok) deliberacja z 3 agentami kosztuje około $0.23-0.30. Deliberacja z 10 agentami kosztuje $0.75-1.00. System uruchamia deliberację przy około 10% decyzji, więc zamortyzowany koszt wszystkich decyzji wynosi $0.08-0.10 na sesję. (We wcześniejszych wydaniach podawano wartości 3 razy wyższe, obliczone według historycznych cen $15/$75 dla Opus 4.x.) To, czy jest to opłacalne, zależy od kosztu błędnej decyzji.

Kiedy deliberować

Projektowanie CLAUDE.md

CLAUDE.md to zasady operacyjne dla agenta AI, a nie README przeznaczone dla ludzi.²¹ Agent nie musi rozumieć, dlaczego stosuje się conventional commits. Musi znać dokładne polecenie do uruchomienia oraz kryteria ukończenia zadania.

Hierarchia pierwszeństwa

Pliki reguł są ładowane automatycznie i zapewniają uporządkowany kontekst bez przeładowywania CLAUDE.md.⁶

Co jest ignorowane

Poniższe wzorce nie powodują żadnych zauważalnych zmian w zachowaniu agenta:²¹

Akapity prozy bez poleceń. „Cenimy czysty, dobrze przetestowany kod” to dokumentacja, a nie instrukcja operacyjna. Agent ją odczytuje, po czym pisze kod bez testów, ponieważ nie otrzymał żadnej konkretnej instrukcji do wykonania.

Niejednoznaczne wytyczne. „Należy zachować ostrożność przy migracjach bazy danych” nie stanowi ograniczenia. Stanowi je natomiast: „Przed zastosowaniem migracji uruchomić alembic check. Przerwać, jeśli brakuje ścieżki wycofania zmian”.

Sprzeczne priorytety. „Działać szybko i szybko publikować” w połączeniu z „Zapewnić kompleksowe pokrycie testami”, „Utrzymać czas wykonywania poniżej 5 minut” oraz „Uruchamiać pełne testy integracyjne przed każdym commitem”. Agent nie może spełnić wszystkich czterech wymagań jednocześnie, więc domyślnie pomija weryfikację.²¹

Przewodniki stylistyczne bez mechanizmu egzekwowania. „Przestrzegać przewodnika Google Python Style Guide” bez ruff check --select D nie daje agentowi żadnego sposobu na zweryfikowanie zgodności.

Co działa

Instrukcje zaczynające się od poleceń:

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Definicje ukończenia:

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Sekcje uporządkowane według zadań:

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

Reguły eskalacji:

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

Kolejność tworzenia

W przypadku rozpoczynania od zera należy dodawać sekcje według następujących priorytetów:²¹

1. Polecenia budowania i testowania (agent potrzebuje ich, zanim będzie mógł wykonać cokolwiek użytecznego)
2. Definicja ukończenia (zapobiega fałszywym deklaracjom ukończenia)
3. Reguły eskalacji (zapobiegają destrukcyjnym obejściom)
4. Sekcje uporządkowane według zadań (ograniczają analizowanie nieistotnych instrukcji)
5. Określenie zakresu katalogów (w monorepo pozwala odizolować instrukcje poszczególnych usług)

Preferencje stylistyczne należy pominąć, dopóki pierwsze cztery elementy nie będą działać.

Platforma przeprowadza teraz audyt CLAUDE.md. Od wydań z początku lipca 2026 roku (v2.1.203–v2.1.206) /doctor analizuje CLAUDE.md i proponuje usunięcie treści, które model może sam wywnioskować z repozytorium — powtórzonych struktur katalogów, konwencji frameworka już widocznych w kodzie czy list poleceń dublujących skrypty pakietu.⁶⁸ Jest to bezpośrednie potwierdzenie tezy tej sekcji przez twórców platformy: instrukcje uzasadniają zajmowane tokeny wtedy, gdy opisują to, czego agent nie może wywnioskować (zasady, progi, definicje ukończenia), a nie to, co może odczytać z dysku. Po znacznym rozroście CLAUDE.md należy uruchomić /doctor i potraktować propozycje skrócenia jako punkt wyjścia — warto jednak zachować reguły operacyjne, które narzędzie może oznaczyć jako „możliwe do wywnioskowania”, jeśli stanowią kluczowe ograniczenia, a nie jedynie opisy.

Importowanie plików

Odwołania do innych plików wewnątrz CLAUDE.md:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Składnia importu: ścieżka względna (@docs/file.md), bezwzględna (@/absolute/path.md) lub względem katalogu domowego (@~/.claude/file.md). Maksymalna głębokość: 5 poziomów importów.⁶

Zgodność instrukcji między narzędziami

AGENTS.md jest otwartym standardem rozpoznawanym przez wszystkie najważniejsze narzędzia do programowania wspomaganego przez AI.²¹ Jeśli zespół korzysta z wielu narzędzi, należy traktować AGENTS.md jako źródło kanoniczne, a odpowiednie sekcje odwzorować w plikach właściwych dla poszczególnych narzędzi:

Wzorce stosowane w AGENTS.md (polecenia na początku, zdefiniowane kryteria ukończenia, organizacja według zadań) sprawdzają się w każdym pliku instrukcji, niezależnie od narzędzia. Nie należy utrzymywać równoległych zestawów instrukcji, które z czasem zaczynają się różnić. Warto utworzyć jedno autorytatywne źródło i je odwzorowywać.

Uwagi dotyczące równoważności z Codex

Codex oferuje już pełnoprawne odpowiedniki głównych warstw harness, jednak migracja polega na przełożeniu wzorców, a nie na skopiowaniu plików. Przed rozpoczęciem pracy Codex odczytuje AGENTS.md, nakładając globalne wytyczne z ~/.codex na instrukcje projektu i zagnieżdżonych części repozytorium.³¹ Codex skills korzystają z tego samego modelu mentalnego SKILL.md i progresywnego ujawniania informacji: początkowo Codex zna nazwę skill, jej opis i ścieżkę pliku, a pełną treść wczytuje dopiero wtedy, gdy zdecyduje się jej użyć.³² Codex oferuje również natywne hooks, hooks dołączane do pluginów, zarządzane hooks, obsługę MCP oraz jawne przepływy pracy z subagents.³³³⁴

W wersjach Codex v0.138.0–v0.139.0 usprawniono wykrywanie AGENTS.md w nietrywialnych przestrzeniach roboczych: ładowanie odbywa się teraz przez abstrakcję systemu plików środowiska, a ścieżki logiczne są zachowywane podczas przeszukiwania. Dzięki temu właściwy plik zostaje wybrany nawet wtedy, gdy przestrzeń robocza korzysta ze zdalnego systemu plików lub drzewa dowiązań symbolicznych.⁶¹ Ma to znaczenie zawsze, gdy kanoniczny AGENTS.md stanowi autorytatywne źródło, a agent pracuje na repozytorium zamontowanym, zmaterializowanym w kontenerze lub opartym na dowiązaniach symbolicznych — czyli w sytuacjach, w których naiwne przeszukiwanie ścieżek może bez ostrzeżenia wybrać niewłaściwy plik instrukcji albo nie wybrać żadnego. Jeśli jeden autorytatywny AGENTS.md jest odwzorowywany w wielu usługach, tę wersję należy uznać za minimum pozwalające ufać, że agent rzeczywiście wczytał napisany przez Państwa plik.

W Codex v0.141.0 usprawniono następnie samą ścieżkę zdalnego wykonywania: zdalne executors łączą się teraz przez uwierzytelnione, kompleksowo szyfrowane kanały Noise-relay (płaszczyzna sterowania i executor nie muszą już ufać pośredniczącemu między nimi relay), wieloplatformowe zdalne wykonywanie zachowuje natywny katalog roboczy i powłokę executora, a TLS akceptuje podpisy certyfikatów P-521 używane przez firmowe serwery proxy.⁶⁵ Jeśli orkiestracja steruje executors Codex przez granicę sieciową, oznacza to przejście od założenia zaufanego relay do szyfrowania kompleksowego — należy przyjąć tę wersję jako podstawę każdej topologii ze zdalnymi executors.

Linia wydań z lipca 2026 roku pokazuje, że oba środowiska wykonawcze zmierzają z przeciwnych kierunków ku tym samym mechanizmom podstawowym.⁷² Codex v0.143.0 domyślnie ładuje narzędzia MCP za pomocą wyszukiwania narzędzi — schematy narzędzi są odraczane i pobierane na żądanie zamiast trafiać do kontekstu z wyprzedzeniem. Jest to ten sam wzorzec odroczonego ładowania narzędzi, który Claude Code udostępnia przez interfejs ToolSearch, a zarazem właściwe rozwiązanie w obu środowiskach, gdy duża liczba narzędzi MCP nadmiernie rozbudowuje kontekst. Codex v0.144.0 dodaje tryb zatwierdzania aplikacji writes: działania tylko do odczytu są wykonywane bez monitów, natomiast zapisy wymagają zatwierdzenia. To rzeczywiście nowy mechanizm uprawnień, umieszczony między trybem tylko do odczytu a automatycznym zatwierdzaniem, którego lista trybów Claude Code nie wyraża bezpośrednio (najbliższym odpowiednikiem jest tryb plan, który całkowicie blokuje zapisy, zamiast prosić o zgodę na każdy z nich). To samo wydanie wprowadza interaktywne uwierzytelnianie MCP do wersji GA. Z kolei v0.144.5 rozszerza wykrywanie niebezpiecznych poleceń, odzwierciedlając zabezpieczenia przed destrukcyjnymi poleceniami wprowadzone przez Claude Code w wersjach v2.1.183 i v2.1.208. W projektowaniu harness działających w różnych środowiskach najważniejsza jest ta konwergencja: odroczone ładowanie narzędzi, stopniowane zatwierdzanie zapisów i blokowanie niebezpiecznych poleceń na poziomie intencji stają się standardem, a nie cechami wyróżniającymi poszczególnych dostawców.

Codex v0.145.0 pogłębia tę konwergencję na dwóch płaszczyznach.⁷⁶ Ustabilizowano opcjonalny interfejs multi-agent V2: można teraz konfigurować modele sub-agents, poziomy rozumowania i współbieżność, a wcześniej usunięte role agentów zostały przywrócone — jest to odpowiedź Codex na konfigurację modelu i poziomu wysiłku dla każdego subagent w metadanych frontmatter plików .claude/agents/. Ponadto /import rozbudowano do pełnej migracji między harness: poza importem ustawień Claude Code, udostępnionym w wersji v0.140.0, polecenie migruje teraz ustawienia zarówno z Claude Code, jak i Cursor — w tym serwery MCP, pluginy, sesje, polecenia oraz pamięć na poziomie projektu. Dla zespołów korzystających z obu środowisk koszt migracji między nimi stale maleje w jednym kierunku; warstwy harness tworzone w Claude Code — serwery, skills jako polecenia i pamięć — w coraz większym stopniu stają się przenośnym stanem, a nie uzależnieniem od jednego dostawcy.

Praktyczne odwzorowanie:

Istotna różnica: subagents Claude mogą być wybierane automatycznie na podstawie opisów, podczas gdy Codex obecnie dokumentuje przepływy pracy z subagents jako jawne. Dlatego skills i hooks są właściwym domyślnym wyborem dla stale aktywnych zachowań harness w Codex; subagents służą do celowej pracy równoległej, przeglądu i eksploracji.

Testowanie instrukcji

Należy sprawdzić, czy agent rzeczywiście odczytuje instrukcje i ich przestrzega:

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

Rozstrzygający test: należy poprosić agenta o objaśnienie poleceń budowania. Jeśli nie potrafi ich odtworzyć dosłownie, instrukcje są zbyt rozwlekłe (treść została wypchnięta z kontekstu), zbyt nieprecyzyjne (agent nie potrafi wyodrębnić konkretnych działań) albo nie zostały odnalezione. Analiza 2 500 repozytoriów przeprowadzona przez GitHub wykazała, że nieprecyzyjność jest przyczyną większości niepowodzeń.²¹

Wzorce produkcyjne

Wzorce długiego horyzontu Opus 4.7 (kwiecień 2026)

Claude Opus 4.7 (16 kwietnia 2026 r.) wprowadzono z konkretnymi możliwościami, które zmieniają to, przed czym harness musi się chronić:²⁹

• Odporność na błędy narzędzi: Opus 4.7 kontynuuje pracę po błędach narzędzi, które zatrzymywały sesje Opus 4.6. Można ograniczyć — lecz nie wyeliminować — defensywne wrappery ponawiania prób w kodzie subagentów. Należy zachować zabezpieczenia na poziomie hooks; można usunąć z promptów konstrukcje typu „jeśli narzędzie zawiedzie, spróbuj ponownie trzy razy”.
• Poziom wysiłku xhigh: Wprowadzony wraz z Opus 4.7, obecnie obsługiwany przez bieżące modele Opus (Opus 4.8 udostępniono z nim jako /effort xhigh w wersji v2.1.154; Opus 5 go dziedziczy). Znajduje się między high a max. To zalecane ustawienie domyślne dla zadań programistycznych i agentowych. W przypadku długo działających subagentów xhigh wyraźnie przewyższa high przy nieproporcjonalnie mniejszym koszcie tokenów. max pozostaje właściwym wyborem dla jednorazowego, trudnego rozumowania; xhigh lepiej sprawdza się w zadaniach ciągłych.
• Limit budżetu tokenów: Konfigurowalny dla każdego uruchomienia agenta za pomocą output_config.task_budget (nagłówek beta task-budgets-2026-03-13). Model widzi odliczanie i płynnie dostosowuje zakres pracy do budżetu, zamiast niespodziewanie go wyczerpać. Warto używać go w pętlach agentowych, w których potrzebne są przewidywalne wydatki na tokeny bez poświęcania jakości krótkich promptów.
• Świadomość ukrytych potrzeb: Pierwszy model Claude, który przeszedł testy „implicit-need” — rozpoznając, kiedy dosłowna prośba użytkownika nie określa w pełni tego, czego faktycznie potrzebuje. Zmniejsza to potrzebę sekcji „clarifying rules” w CLAUDE.md. Jeśli CLAUDE.md zawiera 200 wierszy zabezpieczeń typu „uwzględnij też X, gdy użytkownik prosi o Y”, należy usunąć te, które są już obsługiwane natywnie.

Baza worktree, ścieżki sandbox i ustawienia administracyjne (7 maja 2026)

Claude Code v2.1.133 dodaje cztery ustawienia poziomu administratora, które warto znać w przypadku produkcyjnych harnessów:³⁹

To przywrócenie worktree.baseRef należy wskazać użytkownikom: agenci polegający na zachowaniu z wersji v2.1.128-v2.1.132 (worktrees tworzących gałęzie z lokalnego HEAD) tracą dostęp do niewypchniętej pracy w świeżych worktrees, jeśli ponownie nie wybiorą tej opcji.

Ankieta opinii OTel na potrzeby obserwowalności przedsiębiorstwa (8 maja 2026)

Claude Code v2.1.136 dodał CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL, aby ponownie włączyć ankietę jakości w sesji dla przedsiębiorstw przechwytujących odpowiedzi przez OpenTelemetry.⁴⁰ Jeśli organizacja przekazuje zdarzenia OTel do centralnego stosu obserwowalności, ta zmienna środowiskowa przywraca ankietę do ścieżki danych, dzięki czemu sygnał jakości przepływa tym samym potokiem co metryki opóźnień i błędów. Należy traktować ją jako opcję opt-in: domyślne ustawienie pozostawia ankietę wyłączoną, co jest właściwe w wdrożeniach bez OTel.

Korporacyjne launchery i wydajność na skalę MCP (lipiec 2026)

Dwie zmiany w v2.1.207 mają znaczenie dla wdrożeń produkcyjnych.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER pozwala środowiskom zarządzanym uruchamiać proces Claude Code przez korporacyjny plik binarny wrappera — jest to punkt integracji dla agentów endpointów, kontroli zasad podczas uruchamiania oraz środowisk, w których każdy proces musi działać pod wymaganym nadzorcą. Jeśli przedsiębiorstwo wcześniej symulowało to za pomocą aliasów powłoki lub rozwidlonych skryptów launchera, jest to obsługiwany punkt rozszerzenia.

Ta sama wersja ograniczyła narzut środowiska wykonawczego tam, gdzie harnessy odczuwają go najmocniej: nawet 7× szybsze rundy użycia narzędzi w sesjach z dużą liczbą narzędzi MCP oraz 79× mniejsze transkrypcje sesji.⁶⁸ Łagodzi to — bez odwracania — wskazówki Koszt jako architektura: podejście CLI-first nadal wygrywa w bezstanowych operacjach jednorazowych, lecz harness obsługujący dziesiątki narzędzi MCP nie ponosi już kary za każdą rundę, którą ponosił wiosną, a przechowywanie transkrypcji przestaje być ukrytym kosztem długich autonomicznych uruchomień.

Pętla jakości

Obowiązkowy proces przeglądu dla wszystkich nietrywialnych zmian:

1. Implementacja - Napisanie kodu
2. Przegląd - Ponowne przeczytanie każdego wiersza. Wyłapanie literówek, błędów logicznych i niejasnych fragmentów
3. Ocena - Uruchomienie evidence gate. Sprawdzenie wzorców, przypadków brzegowych i pokrycia testami
4. Udoskonalenie - Naprawienie każdego problemu. Nigdy nieodkładanie na „później”
5. Szersze spojrzenie - Sprawdzenie punktów integracji, importów i sąsiedniego kodu pod kątem regresji
6. Powtórzenie - Jeśli którekolwiek kryterium evidence gate nie zostanie spełnione, powrót do kroku 4
7. Raportowanie - Wymienienie, co się zmieniło, jak to zweryfikowano, oraz wskazanie konkretnych dowodów

Evidence gate

„Wierzę” i „powinno działać” nie są dowodami. Należy wskazać ścieżki plików, wyniki testów lub konkretny kod.

Jeśli nie można przedstawić dowodów dla któregokolwiek wiersza, należy wrócić do etapu Udoskonalenie.²²

Uprawnienie człowieka do scalania

Badanie arXiv z maja 2026 r. dotyczące 29 585 cykli życia pull requestów agentów AI rozdziela sprawczość operacyjną od nadzoru nad scalaniem.⁴⁷ Użyteczna lekcja architektoniczna jest prosta: agenci mogą rozpoczynać pracę, rozwijać gałęzie, otwierać PR-y, przeglądać pracę i podsumowywać ryzyko, podczas gdy uprawnienie do scalania pozostaje odrębną granicą nadzoru.

Należy wyraźnie określić tę granicę w harnessie. Agenci mogą przygotowywać PR-y i gromadzić dowody; należy wymagać zatwierdzenia przez człowieka dla scaleń, wydań i destrukcyjnych operacji na repozytorium, chyba że organizacja ma odrębnie audytowaną politykę automatyzacji. Gdy automatyzacja wykonuje scalenie, należy zachować logi rozróżniające wykonawcę od człowieka lub zasady, która je autoryzowała.

Wzorce obsługi błędów

Atomowe zapisy plików. Wielu agentów zapisujących jednocześnie do tego samego pliku stanu uszkadza JSON. Należy zapisywać do plików .tmp, a następnie wykonywać atomowe mv. System operacyjny gwarantuje, że mv jest atomowe w obrębie tego samego systemu plików.¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Odzyskiwanie po uszkodzeniu stanu. Jeśli stan zostanie uszkodzony, wzorzec odzyskiwania odtwarza go z bezpiecznych wartości domyślnych zamiast powodować awarię:¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

Pułapka bash ((VAR++)). ((VAR++)) zwraca kod wyjścia 1, gdy VAR wynosi 0, ponieważ 0++ jest obliczane jako 0, co bash traktuje jako fałsz. Przy włączonym set -e kończy to działanie skryptu. Należy zamiast tego użyć VAR=$((VAR + 1)).¹⁶

Klasyfikacja promienia rażenia

Należy klasyfikować każde działanie agenta według promienia rażenia i odpowiednio je ograniczać:²

Remote Control (łączenie z lokalnym Claude Code z dowolnej przeglądarki lub aplikacji mobilnej) zmienia bramkę „Zewnętrzne” z blokującego oczekiwania w asynchroniczne powiadomienie. Agent kontynuuje pracę nad następnym zadaniem, podczas gdy poprzednie można sprawdzić na telefonie.²

Specyfikacja zadań dla autonomicznych uruchomień

Skuteczne zadania autonomiczne zawierają trzy elementy: cel, kryteria ukończenia i wskaźniki kontekstu:¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

Kryteria muszą być weryfikowalne maszynowo: powodzenie/niepowodzenie testów, wynik lintera, kody statusu HTTP, kontrole istnienia plików. Wczesne zadanie, które prosiło agenta o „napisanie testów, które przechodzą”, zaowocowało assert True i assert 1 == 1. Technicznie poprawne. W praktyce bezwartościowe.¹⁶

Tryby awarii, na które należy uważać

Konkretny ślad sesji

Ślad sesji z autonomicznego uruchomienia przetwarzającego PRD z 5 historyjkami:²

1. Uruchamia się SessionStart. Dispatcher wstrzykuje: bieżącą datę, wykrywanie projektu, ograniczenia filozoficzne, inicjalizację śledzenia kosztów. Pięć hooks, łącznie 180 ms.

2. Agent odczytuje PRD, planuje pierwszą historyjkę. Uruchamia się UserPromptSubmit. Dispatcher wstrzykuje: kontekst aktywnego projektu, punkt odniesienia dla dryfu sesji.

3. Agent wywołuje Bash, aby uruchomić testy. Uruchamia się PreToolUse:Bash. Kontrola poświadczeń, walidacja sandbox, wykrywanie projektu. 90 ms. Testy są uruchamiane. Uruchamia się PostToolUse:Bash: rejestrowany jest heartbeat aktywności, kontrola dryfu.

4. Agent wywołuje Write, aby utworzyć plik. Uruchamia się PreToolUse:Write: kontrola zakresu pliku. Uruchamia się PostToolUse:Write: kontrola lint, śledzenie commitów.

5. Agent kończy historyjkę. Uruchamia się Stop. Bramka jakości sprawdza: czy agent wskazał dowody? Czy użył języka asekuracyjnego? Czy w diffie znajdują się komentarze TODO? Jeśli dowolna kontrola się nie powiedzie, kod wyjścia 2 powoduje kontynuowanie pracy przez agenta.

6. Niezależna weryfikacja: Świeży agent uruchamia zestaw testów, nie ufając samoopisowi poprzedniego agenta.

7. Równolegle uruchamiane są trzy agenty przeglądu kodu. Każdy niezależnie przegląda diff. Jeśli którykolwiek recenzent zgłosi CRITICAL, historyjka wraca do kolejki.

8. Historyjka przechodzi. Ładowana jest następna historyjka. Cykl powtarza się dla wszystkich 5 historyjek.

Łączna liczba uruchomionych hooks dla 5 historyjek: ~340. Łączny czas spędzony w hooks: ~12 sekund. Ten narzut zapobiegł trzem wyciekom poświadczeń, jednemu destrukcyjnemu poleceniu i dwóm niekompletnym implementacjom podczas jednego nocnego uruchomienia.

Studium przypadku: nocne przetwarzanie PRD

Produkcyjny harness przetworzył 12 PRDs (47 historyjek) w 8 nocnych sesjach. Metryki porównują pierwsze 4 PRDs (minimalny harness: tylko CLAUDE.md) z ostatnimi 8 (pełny harness: hooks, skills, quality gates, wieloagentowy przegląd).

Dwa wycieki poświadczeń wymagały rotacji kluczy API i audytu usług niższego szczebla: około 4 godzin reakcji na incydent. Narzut harnessu, który zapobiegł odpowiednikowi tego zdarzenia, wyniósł 2,4 sekundy bash na historyjkę. Wskaźnik fałszywego ukończenia spadł z 35% do 4%, ponieważ hook Stop niezależnie uruchamiał testy przed zezwoleniem agentowi na zgłoszenie zakończenia.

Aspekty bezpieczeństwa

Pięć zasad godnych zaufania agentów (Anthropic, kwiecień 2026)

Anthropic opublikowało 9 kwietnia 2026 r. formalne ramy wiarygodności agentów.²⁷ Pięć zasad jest równoległych do podejścia Evidence Gate przedstawionego w tym przewodniku — i je rozszerza:

Anthropic przekazało również MCP fundacji Linux Foundation’s Agentic AI Foundation, dołączając do AGENTS.md (obecnie wspólnie zarządzanego z OpenAI, Google, Cursor, Factory i Sourcegraph). Standardy interoperacyjności agentów są teraz niezależne od dostawców.²⁷

Bezstanowa tura i tożsamość zgłaszana przez sam MCP. Specyfikacja MCP zakończyła przejście na bezstanowy rdzeń (SEP-2575) wraz z rewizją z 28 lipca 2026 r., obecnie obowiązującą specyfikacją, która usuwa stanowy handshake initialize, wcześniej przenoszący tożsamość serwera. Zmiana w wersji roboczej specyfikacji, scalona 16 lipca (PR #3002), przywraca tożsamość jako powierzchnię opcjonalną: serwery mogą uwzględniać obiekt io.modelcontextprotocol/serverInfo w odpowiedzi _meta, a clientInfo staje się opcjonalne w żądaniach.⁷¹ Istotne dla bezpieczeństwa jest to, co specyfikacja mówi o zaufaniu: ta tożsamość jest zgłaszana samodzielnie i niezweryfikowana — wyłącznie do wyświetlania i logowania — i NIE POWINNA wpływać na decyzje dotyczące bezpieczeństwa. Jeżeli harness opiera allowlisty, reguły uprawnień lub audyt oparty na logach na deklarowanej nazwie serwera MCP, ta nazwa jest twierdzeniem, a nie poświadczeniem; zaufanie należy przypinać do transportu i konfiguracji (który serwer Pan/Pani skonfigurował(a) pod którym endpointem), nigdy do tego, za co podaje się serwer. Bezstanowa rewizja została wydana zgodnie z harmonogramem 28 lipca 2026 r. (obowiązkowe server/discover, negocjowanie wersji protokołu przez _meta, nagłówek Streamable HTTP) — powyższe wskazówki dotyczące zaufania opisują wydane zachowanie.

Narzędzia sandbox dla skills: Zespoły traktujące skills jako powierzchnię ataku mogą użyć SandyClaw firmy Permiso (uruchomionego 2 kwietnia 2026 r.), który wykonuje skills w dedykowanym sandbox i dostarcza werdykty poparte dowodami z detekcji Sigma/YARA/Nova/Snort. Jest to pierwszy produkt w kategorii skill-sandbox.²⁸

Sandbox

Claude Code obsługuje opcjonalny tryb sandbox (włączany przez settings.json lub polecenie /sandbox), który ogranicza dostęp do sieci i operacje na systemie plików za pomocą izolacji na poziomie systemu operacyjnego (seatbelt w macOS, bubblewrap w Linuxie). Po włączeniu sandbox uniemożliwia modelowi wykonywanie dowolnych żądań sieciowych lub uzyskiwanie dostępu do plików poza katalogiem projektu. Bez sandboxingu Claude Code używa modelu opartego na uprawnieniach, w którym zatwierdza się lub odrzuca poszczególne wywołania narzędzi.¹³

Minimalny poziom bezpieczeństwa z maja 2026 r. Claude Code v2.1.149 naprawiło obejście uprawnień katalogu roboczego PowerShell, kilka luk w analizie uprawnień związanych z regułami allow PowerShell i nieaktualnymi zmiennymi oraz błąd allowlisty zapisu sandbox dla git-worktree, który obejmował cały główny katalog repozytorium zamiast wyłącznie współdzielonych wewnętrznych elementów git.⁵³ Jeśli harness dopuszcza PowerShell lub agentów izolowanych przez worktree, należy traktować v2.1.149+ jako poziom minimalny i zachować wąskie reguły shell. Szerokie wyjątki PowerShell(*) i zapisu w całym repozytorium są skrótami orkiestracyjnymi, a nie granicami bezpieczeństwa.

Zaostrzenie sandbox OpenAI Agents SDK (v0.17.0, 8 maja 2026 r.). Po stronie OpenAI openai-agents-python v0.17.0 zaostrzyło równoległą granicę: LocalFile.src i LocalDir.src są teraz ograniczone do materializacyjnego base_dir (bieżącego katalogu roboczego procesu SDK podczas zastosowania manifestu), chyba że źródło zostało jawnie przyznane przez Manifest.extra_path_grants z SandboxPathGrant.⁴¹ Względne źródła lokalne są rozwiązywane względem base_dir; ścieżki bezwzględne muszą już znajdować się w jego obrębie albo mieć przyznane uprawnienie. Zamyka to problem granicy lokalnych artefaktów: wcześniejsze wersje pozwalały manifestom przenosić dowolne ścieżki hosta do obszaru roboczego sandbox. Migracja: należy deklarować zaufane katalogi główne hosta na poziomie manifestu przez SandboxPathGrant(path=..., read_only=True) dla montowań tylko do odczytu. extra_path_grants należy traktować jako zaufaną konfigurację aplikacji; nigdy nie należy wypełniać uprawnień na podstawie danych wyjściowych modelu ani niezaufanych danych wejściowych manifestu.

Kolejny minimalny poziom OpenAI Agents SDK (v0.17.3). Linia 0.17.1–0.17.3 dodała dalsze wzmocnienia sandbox i sesji: limity rozpakowywania archiwów, walidację podścieżek GitRepo, czytelniejsze błędy dostawcy sandbox, poświadczenia punktów montowania niewidoczne w poleceniach sandbox, odrzucanie względnych katalogów głównych obszaru roboczego sandbox oraz obsługę stanów końcowych Vercel-sandbox.⁵⁴ Jeżeli używane są sandboksy hostowane przez OpenAI lub wspierane przez dostawcę, a nie wyłącznie hooks Claude Code, należy traktować 0.17.3 jako obecny minimalny poziom dla wzorców z tej sekcji.

Trzy wzorce ograniczania w różnych produktach (Anthropic, maj 2026)

Wpis inżynieryjny Anthropic „How we contain Claude across products” (25 maja 2026 r.) jest własnym ujęciem dostawcy zasad, których ta sekcja uczy fragmentarycznie — sandboxu na poziomie ustawień opisanego powyżej, minimalnego poziomu izolacji worktree oraz postawy traktowania wszystkiego jako niezaufanego.⁸¹ Jego kluczowe założenie polega na dopasowaniu siły ograniczenia do powierzchni produktu, a samo to dopasowanie stanowi lekcję: nie istnieje jeden właściwy projekt izolacji, istnieje tylko izolacja dopasowana do tego, kto sprawuje nadzór i co może pójść nie tak.

• Efemeryczne kontenery gVisor (claude.ai). Wykonywanie po stronie serwera działa w kontenerach gVisor na izolowanej infrastrukturze z efemerycznym systemem plików na sesję. Model zagrożeń dotyczy izolacji infrastruktury i tenantów — komputer użytkownika nigdy nie jest osiągalny, więc nic lokalnego nie wymaga ochrony.
• Sandboxing systemu operacyjnego z człowiekiem w pętli (Claude Code). Wzorzec opisany w powyższym akapicie o sandbox, sformułowany jako polityka: Seatbelt w macOS i bubblewrap w Linuxie, z dozwolonym odczytem, zapisami ograniczonymi do obszaru roboczego oraz siecią domyślnie zablokowaną — człowiek zatwierdza to, czego granica nie obejmuje. Anthropic udostępniło runtime jako open source (sandbox-runtime), dzięki czemu granica podlega audytowi. Wpis otwarcie wskazuje słabe ogniwo: zatwierdzanych jest około 93% monitów o uprawnienia, a klasyfikator auto-mode — wyłapujący około 83% nadgorliwych zachowań przed wykonaniem i redukujący liczbę monitów zatwierdzenia o 84% — istnieje właśnie dlatego, że zmęczenie zatwierdzaniem jest właściwością bezpieczeństwa, a nie skargą na UX. To postawa warstwy kontroli, którą ten przewodnik śledzi od v2.1.193.
• Zapieczętowane VM (Claude Cowork). Pełne maszyny wirtualne na hypervisorach platform — Apple Virtualization framework w macOS, HCS w Windows — z zamontowanymi wyłącznie wybranym obszarem roboczym i folderem .claude; nic innego z hosta nie jest widoczne. Poświadczenia nigdy nie trafiają do VM: pozostają w keychain hosta, a każda sesja otrzymuje token o ograniczonym zakresie, który można niezależnie unieważnić. Defensywny proxy MITM wewnątrz VM wymusza tę zasadę, przepuszczając wyłącznie żądania zawierające własny, udostępniony token sesyjny VM — klucz osadzony przez atakującego jest odrzucany na granicy, ponieważ tylko VM zna jego pochodzenie.

Zasady projektowe leżące u podstaw tej taksonomii są częścią możliwą do przeniesienia. Najpierw ograniczaj na warstwie środowiska, a dopiero potem steruj na warstwie modelu: każda obrona probabilistyczna ma niezerowy współczynnik przeoczeń, dlatego deterministyczne granice muszą wychwytywać to, czego nie wychwyci sterowanie na poziomie promptu — jest to argument tego przewodnika, że hooks gwarantują wykonanie, sformułowany ponownie przez dostawcę. Dopasuj siłę izolacji do zdolności użytkownika do sprawowania nadzoru: programista może ocenić polecenie bash przed jego zatwierdzeniem; pracownik wiedzy nie — dlatego Code otrzymuje okno dialogowe uprawnień, a Cowork zapieczętowaną VM. Przedkładaj sprawdzone prymitywy nad własny kod izolacji: hypervisory, seccomp i runtime kontenerów przetrwały kontrolę adwersarialną lepiej niż własne proxy allowlist i parsery konfiguracji Anthropic. Traktuj lokalną konfigurację projektu oraz dane wyjściowe narzędzi jako niezaufane: instrukcja wpisu nakazuje traktować otwarcie projektu i ładowanie konfiguracji jak każde żądanie przychodzące z internetu, a dane wyjściowe narzędzia jako powierzchnię ataku nawet wtedy, gdy narzędzie jest zaufane — to samo podejście ten przewodnik stosuje do wiadomości między agentami, treści czytanych przez subagents oraz tożsamości MCP zgłaszanej samodzielnie. Trzymaj poświadczenia poza sandbox: tokeny o ograniczonym zakresie, możliwe do unieważnienia i przypisane do sesji, zamiast otaczających kluczy, które agent mógłby ujawnić.

Powierzchnia ustawień dogania pierwszą zasadę (v2.1.219). Łatwo poprzeć zasadę „najpierw ograniczaj na warstwie środowiska”, lecz jej rzeczywista konfiguracja była niezręczna, ponieważ sandbox Claude Code rozstrzygał to, czego nie obejmowały jego reguły, pytając — a monit o uprawnienia jest probabilistyczną obroną w deterministycznym kostiumie, jak przyznaje podana wyżej wartość 93% zatwierdzeń. sandbox.network.strictAllowlist usuwa pytanie dotyczące ruchu wychodzącego: po jego ustawieniu żądanie sandboxowanego polecenia do hosta spoza allowlisty jest bezwzględnie odrzucane zamiast powodować wyświetlenie monitu.⁸⁴ W połączeniu z sandbox.filesystem.disabled z v2.1.216 te dwa ustawienia tworzą postawę, a nie stos przełączników — ograniczenie systemu plików i sieci można wybierać niezależnie, a ograniczenie sieci można teraz uczynić deterministycznym. Dla nieobsługiwanego harness ważniejsze jest drugie z nich, ponieważ ruch wychodzący jest miejscem, w którym wstrzyknięta instrukcja staje się eksfiltracją, a skrajnym przypadkiem zmęczenia zatwierdzaniem jest brak osoby przy klawiaturze, która mogłaby się nim zmęczyć. Koszt jest zwykłym kosztem granicy deterministycznej: allowlista musi być poprawna, a zapomniany host kończy się nieprzejrzystym odrzuceniem zamiast pytaniem. Należy wyliczyć hosty, których agenci zasadnie potrzebują, a następnie usunąć monit.

Nic z tego nie zastępuje warstwy hook; znajduje się pod nią. Wzorce ograniczania stanowią deterministyczny fundament, a historia egzekwowania worktree w tym przewodniku pokazuje tę samą lekcję w miniaturze: granica liczy się tylko wtedy, gdy wytrzymuje celowe przekierowanie, a prymitywy, które najpewniej wytrzymają, to te, których nie napisano na tę okazję.

Granice uprawnień

System uprawnień kontroluje operacje na wielu poziomach:

Reguły uprawnień na poziomie parametrów (czerwiec 2026)

Claude Code v2.1.178 rozszerzyło reguły uprawnień z poziomu narzędzia na poziom parametru: Tool(param:value) dopasowuje się do parametrów wejściowych narzędzia, a * działa jako symbol wieloznaczny. Kanonicznym przykładem jest Agent(model:opus) — reguła blokująca uruchamianie subagents na określonym poziomie modelu.⁶³ Architektonicznie zamyka to lukę, której czteropoziomowa tabela powyżej nie mogła wyrazić: wcześniej można było zezwolić na narzędzie lub całkowicie go odmówić, lecz nie można było ograniczyć sposobu jego wywołania. Polityka zarządzania może teraz mówić „subagents mogą się uruchamiać, ale nie na poziomie Fable 5” albo „Bash jest dozwolony, ale nie z tą flagą” jako reguła deterministyczna, a nie żądanie na poziomie promptu.

Towarzyszące ustawienie zarządzane enforceAvailableModels (v2.1.175) ogranicza wybór modelu odgórnie: przypina model Default i uniemożliwia ustawieniom na poziomie użytkownika lub projektu rozszerzenie zarządzanej allowlisty availableModels.⁶³ Oba mechanizmy się uzupełniają — allowlista definiuje, które poziomy w ogóle istnieją w sesji, a reguły na poziomie parametrów ograniczają, jak subagents z nich korzystają. Od v2.1.196 administratorzy mogą również ustawić domyślny model dla całej organizacji z konsoli organizacji, widoczny jako „Org default” w /model, dzięki czemu cała flota dziedziczy zarządzaną wartość domyślną bez przypinania jej przez każdego operatora — jest to fundament uzupełniający sufit allowlisty.

Reguły allow ograniczone ścieżką są zakotwiczone w katalogu roboczym (lipiec 2026)

Claude Code v2.1.214 zamknęło ciche nadmierne dopasowanie w regułach uprawnień ograniczonych ścieżką: reguła allow z jednosegmentowym wzorcem dir/** — na przykład Edit(src/**) — automatycznie zatwierdzała edycje dowolnego katalogu o nazwie src na dowolnej głębokości, w tym vendor/some-package/src/ i każdego innego zagnieżdżonego src/, którego autor reguły nigdy nie zamierzał zatwierdzać. Takie reguły są teraz zakotwiczone wyłącznie w <cwd>/dir; jeżeli rzeczywiście potrzebne jest dopasowanie na dowolnej głębokości, należy je zadeklarować przez **/dir/**.⁷⁴ Reguły deny i ask celowo zachowują stare dopasowanie na dowolnej głębokości. Ta asymetria jest właściwym projektem bezpiecznej awarii: zbyt wąsko dopasowana reguła allow kończy się bezpiecznie (pojawia się monit), podczas gdy zbyt wąsko dopasowana reguła deny kończy się otwarciem luki (zablokowana ścieżka przechodzi) — dlatego reguły allow stały się bardziej rygorystyczne, a deny pozostały szerokie. Jeżeli ustawienia opierają się na jednosegmentowych wzorcach allow obejmujących zagnieżdżone ścieżki, od v2.1.214 po cichu przestały to robić; poprawka działa zgodnie z zamierzeniem, jednak warto przejrzeć allowlisty i ponownie zadeklarować zakres, który jest rzeczywiście potrzebny.

Zabezpieczenia auto mode przed destrukcyjnymi poleceniami (czerwiec 2026)

Claude Code v2.1.183 zawęziło promień rażenia auto mode dla operacji, które po cichu powodują utratę pracy lub likwidują środowiska. Auto mode teraz bezwzględnie blokuje — chyba że zostały jawnie zażądane w sesji — destrukcyjne operacje git (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend, gdy commit nie został utworzony przez agenta w tej sesji; oraz likwidację infrastruktury (terraform destroy, pulumi destroy, cdk destroy), chyba że wskazano konkretny stack.⁶⁵ Architektonicznie jest to uzupełnienie kontroli uruchamiania i reguł na poziomie parametrów opisanych powyżej: zamiast kontrolować które narzędzie lub w jaki sposób jest uruchamiane, kontroluje mały zestaw konkretnych nieodwracalnych poleceń według intencji — agent nadal może je wykonać, lecz wyłącznie na wyraźne polecenie, a nie z własnej inicjatywy. W autonomicznym harness należy zakodować tę samą zasadę we własnych hooks PreToolUse: polecenia niszczące stan zasługują na regułę domyślnego odrzucenia, którą znosi wyłącznie jednoznaczny sygnał operatora.

Lipiec 2026: auto mode trafia do przedsiębiorstw, a jednego monitu nie można zrzec się. Auto mode osiągnął GA w Amazon Bedrock, Google Vertex AI i Microsoft Foundry w v2.1.207, z ustawieniem zarządzanym disableAutoMode jako rezygnacją dla przedsiębiorstw — postawa klasyfikatora jako warstwy kontroli jest teraz dostępna na każdej własnej platformie przedsiębiorstw, a jego wyłączenie jest jawną decyzją w zakresie zarządzania, a nie luką platformy.⁶⁸ Następnie v2.1.208 uczyniło zabezpieczenie przed katastrofalnym usunięciem bezwzględnym: monity potwierdzające katastrofalne usunięcia przebijają się przez zarówno --dangerously-skip-permissions, jak i auto mode.⁶⁸ Jest to istotny precedens — pierwsze potwierdzenie w Claude Code, którego nie może zrzec się żadna postawa uprawnień, w tym jawna flaga obejścia. Projekty autonomicznych harness, które zakładały, że --dangerously-skip-permissions oznacza dosłownie zero monitów, powinny uwzględnić ten jeden wyjątek; uruchamia się on dokładnie tam, gdzie nieobsługiwana pętla może wyrządzić największą nieodwracalną szkodę.

Zabezpieczenia przed fabrykowaniem (lipiec 2026)

Wydania v2.1.203–v2.1.206 zamknęły dwie ścieżki, dzięki którym agent mógł sfałszować własny ślad audytowy.⁶⁸ Po pierwsze, reguła auto-mode blokuje teraz manipulowanie plikami transkrypcji — zapis sesji nie jest już czymś, co mogą przepisać wywołania narzędzi tej samej sesji. Po drugie, powiadomienia o zadaniach w tle wyraźnie stwierdzają teraz, że podczas działania zadania nie wystąpiło żadne ludzkie wejście. Druga zmiana dotyczy subtelnej awarii: model podsumowujący zadanie w tle mógł wcześniej przedstawić (lub wymyślić) „zatwierdzenie” w transkrypcji, które nigdy nie nastąpiło, a nic w powiadomieniu temu nie przeczyło. Teraz samo powiadomienie stanowi kontrdowód.

Wniosek architektoniczny uogólnia się na Evidence Gate: transkrypcje, powiadomienia i logi są powierzchniami audytu, a powierzchnie audytu nie mogą być zapisywalne przez podmiot, który audytują. Platforma egzekwuje to teraz dla własnej transkrypcji; tę samą zasadę należy zastosować w harness — raporty dowodowe, wyniki testów i rejestry deliberacji powinny znajdować się poza ścieżką zapisywalną przez model.

Obrona przed prompt injection

Skills i hooks zapewniają ochronę warstwową przed prompt injection:

Skills z ograniczeniami narzędzi uniemożliwiają przejętemu promptowi uzyskanie dostępu do zapisu:

allowed-tools: Read, Grep, Glob

Hooks PreToolUse walidują każde wywołanie narzędzia niezależnie od tego, jak model został spromptowany:

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

Izolacja subagent ogranicza promień rażenia. Subagent z permissionMode: plan nie może wprowadzać zmian, nawet jeśli jego prompt został przejęty.

Minimalny poziom platformy wzrósł w lipcu 2026 r. Claude Code v2.1.210 wzmocniło Agent tool przeciwko pośredniemu prompt injection przenoszonemu w treści przeczytanej przez subagent — zatruty plik, strona internetowa lub wynik narzędzia pobrany przez subagent ma mniejszą możliwość sterowania samą powierzchnią delegowania.⁶⁹ A v2.1.211 wzmocniło ludzkie ogniwo łańcucha: podglądy uprawnień teraz neutralizują znaki Unicode nadpisania dwukierunkowego, zerowej szerokości i znaki podobne wizualnie, więc polecenia nie można już skonstruować tak, aby wyświetlało się jako nieszkodliwe w oknie zatwierdzania, wykonując jednocześnie coś innego.⁶⁹ Druga poprawka ma największe znaczenie dla harness, w których człowiek zatwierdza renderowane podglądy pod presją czasu — wyświetlanie także było powierzchnią injection. Żadna z tych zmian nie zastępuje obron na poziomie hook opisanych wyżej; podnosi minimalny poziom pod nimi.

Logi agentów i guardrails są powierzchniami bezpieczeństwa

Dwa zalecenia z maja 2026 r. wzmacniają pewien wzorzec: infrastruktura agentów tworzy nowe miejsca, w których wrażliwa zawartość i wykonywalne polityki mogą wyciekać lub zostać ominięte. Advisory GHSA-f3jg-756w-gm35 firmy GitHub dotyczy problemu filtra payload Gryph Agents, przez który wrażliwa zawartość payload narzędzi mogła pozostawać w lokalnych logach SQLite przy domyślnym zachowaniu logowania.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p dotyczy ucieczki z sandbox niestandardowego kodu guardrail LiteLLM w chronionym przez administratora endpointcie proxy.⁴⁶

Reguła produkcyjna: transkrypcje agentów, payloady narzędzi, logi SQLite i wykonywanie guardrail należy traktować jako wrażliwą infrastrukturę. Należy redagować dane przed utrwaleniem, stosować limity retencji oraz utrzymywać niestandardowy kod guardrail w sandbox i w stanie umożliwiającym przegląd. Reguła na poziomie promptu „nie loguj sekretów” nie wystarczy; ścieżka logowania i guardrail wymaga deterministycznych testów.

Bezpieczeństwo hook

HTTP hooks interpolujące zmienne środowiskowe w nagłówkach wymagają jawnej listy allowedEnvVars, aby zapobiec eksfiltracji dowolnych zmiennych środowiskowych:¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

Podział odpowiedzialności między człowieka a agenta

Bezpieczeństwo w architekturach agentowych wymaga jasnego podziału odpowiedzialności człowieka i agenta:¹⁷

Wzorzec jest następujący: ludzie odpowiadają za decyzje wymagające kontekstu organizacyjnego, oceny etycznej lub kierunku strategicznego. Agenci odpowiadają za decyzje wymagające obliczeniowego przeszukiwania dużych przestrzeni możliwości. Hooks egzekwują tę granicę.

Rekurencyjne egzekwowanie hook

Hooks uruchamiają się również dla działań subagent.¹³ Jeśli Claude uruchamia subagent przez Agent tool, hooks PreToolUse i PostToolUse wykonują się dla każdego narzędzia używanego przez subagent. Bez rekurencyjnego egzekwowania hook subagent mógłby ominąć zabezpieczenia. Zdarzenie SubagentStop umożliwia uruchomienie czyszczenia lub walidacji po zakończeniu pracy subagent.

Nie jest to opcjonalne. Agent, który uruchamia subagent bez własnych hooks bezpieczeństwa, jest agentem mogącym wykonać force-push do main, odczytać pliki poświadczeń lub uruchomić destrukcyjne polecenia, podczas gdy zabezpieczenia obserwują główną rozmowę i nie robią nic.

Koszt jako architektura

Koszt jest decyzją architektoniczną, a nie operacyjnym dodatkiem.² Trzy poziomy:

Poziom tokenów. Kompresja promptu systemowego. Należy usunąć przykłady kodu z samouczków (model zna APIs), scalić zduplikowane reguły między plikami i zastąpić wyjaśnienia ograniczeniami. „Odrzucaj wywołania narzędzi dopasowane do wrażliwych ścieżek” wykonuje tę samą pracę co 15-wierszowe wyjaśnienie, dlaczego nie należy odczytywać poświadczeń.

Poziom agenta. Świeże uruchomienia zamiast długich rozmów. Każda historia w autonomicznym uruchomieniu otrzymuje nowego agenta z czystym kontekstem. Kontekst nigdy nie puchnie, ponieważ każdy agent zaczyna od nowa. Briefing zamiast pamięci: modele wykonują jasny briefing lepiej, niż poruszają się po 30 krokach nagromadzonego kontekstu.

Poziom architektury. Najpierw CLI, a dopiero potem MCP, gdy operacja jest bezstanowa. Wywołanie claude --print do jednorazowej oceny kosztuje mniej i nie dodaje narzutu połączenia. MCP ma sens, gdy narzędzie potrzebuje trwałego stanu lub strumieniowania.

Ramy decyzyjne

Kiedy stosować poszczególne mechanizmy:

Skills vs Hooks vs Subagents

FAQ

Ile hooks to za dużo?

Ograniczeniem jest wydajność, a nie liczba. Każdy hook uruchamia się synchronicznie, dlatego łączny czas wykonania hooks jest doliczany do każdego dopasowanego wywołania narzędzia. 95 hooks w ustawieniach użytkownika i projektu działa bez zauważalnych opóźnień, gdy każdy hook kończy się w czasie krótszym niż 200 ms. Warto obserwować następujący próg: jeśli hook PostToolUse dodaje ponad 500 ms do każdej edycji pliku, sesja staje się ociężała. Przed wdrożeniem warto profilować hooks za pomocą time.¹⁴

Czy hooks mogą zablokować uruchomienie polecenia przez Claude Code?

Tak. Hooks PreToolUse blokują dowolną akcję narzędzia, kończąc działanie kodem 2. Claude Code anuluje oczekującą akcję i pokazuje modelowi dane wyjściowe stderr hooka. Claude widzi przyczynę odrzucenia i proponuje bezpieczniejszą alternatywę. Kod wyjścia 1 oznacza nieblokujące ostrzeżenie, przy którym akcja nadal jest wykonywana.³

Gdzie należy umieścić pliki konfiguracji hooks?

Konfiguracje hooków należy umieścić w .claude/settings.json dla hooks na poziomie projektu (commitowanych do repozytorium i współdzielonych z zespołem) albo w ~/.claude/settings.json dla hooks na poziomie użytkownika (osobistych, stosowanych w każdym projekcie). Hooks na poziomie projektu mają pierwszeństwo, gdy istnieją oba warianty. Aby uniknąć problemów z katalogiem roboczym, dla plików skryptów należy używać ścieżek bezwzględnych.¹⁴

Czy każda decyzja wymaga deliberation?

Nie. Moduł pewności ocenia decyzje w czterech wymiarach (niejednoznaczność, złożoność, stawka, zależność od kontekstu). Deliberation uruchamiają tylko decyzje, których łączna ocena pewności jest niższa niż 0,70 — około 10% wszystkich decyzji. Poprawki dokumentacji, zmiany nazw zmiennych i rutynowe edycje całkowicie pomijają deliberation. Architektura bezpieczeństwa, zmiany schematu bazy danych i nieodwracalne wdrożenia uruchamiają ją konsekwentnie.⁷

Jak testować system zaprojektowany tak, by generował niezgodę?

Należy testować zarówno ścieżki powodzenia, jak i ścieżki błędów. Powodzenie: agenci konstruktywnie się nie zgadzają i osiągają konsensus. Błąd: agenci zbyt szybko osiągają zgodność, nigdy nie osiągają konsensusu lub przekraczają budżety uruchomień. Testy end-to-end symulują każdy scenariusz za pomocą deterministycznych odpowiedzi agentów, weryfikując, że obie bramki walidacyjne wychwytują każdy udokumentowany tryb błędu. Produkcyjny system deliberation uruchamia 141 testów w trzech warstwach: 48 testów integracyjnych Bash, 81 testów jednostkowych Python i 12 symulacji pipeline end-to-end.⁷

Jaki jest wpływ deliberation na opóźnienia?

Deliberation z 3 agentami dodaje 30–60 sekund czasu zegarowego (ten projekt deliberation uruchamia agentów sekwencyjnie przez Agent tool; od wersji v2.1.198 platforma sama uruchamia subagents współbieżnie w tle). Deliberation z 10 agentami dodaje 2–4 minuty. Hooks sprawdzające konsensus i pride check wykonują się w czasie krótszym niż 200 ms. Głównym wąskim gardłem jest czas inferencji LLM na agenta, a nie narzut orkiestracji.⁷

Jak długi powinien być plik CLAUDE.md?

Każda sekcja powinna mieć mniej niż 50 wierszy, a cały plik — mniej niż 150 wierszy. Długie pliki są obcinane przez okna kontekstowe, dlatego na początku należy umieścić najważniejsze instrukcje: polecenia i definicje zakończenia przed preferencjami stylu.²¹

Czy działa to z narzędziami innymi niż Claude Code?

Zasady architektoniczne (hooks jako deterministyczne bramki, skills jako wiedza domenowa, subagents jako odizolowane konteksty, system plików jako pamięć) mają zastosowanie koncepcyjne do każdego systemu agentowego. Konkretna implementacja wykorzystuje zdarzenia cyklu życia Claude Code, wzorce matcherów i Agent tool. AGENTS.md przenosi te same wzorce do Codex, Cursor, Copilot, Amp i Windsurf.²¹ Wzorzec harness jest niezależny od narzędzia, nawet jeśli szczegóły implementacji są specyficzne dla narzędzia.

Karta szybkiego odniesienia

Konfiguracja hooków

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Frontmatter Skill

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Definicja subagenta

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

Kody wyjścia

Kluczowe polecenia

Lokalizacje plików

Dziennik zmian

Źródła