Architektura agentów: tworzenie środowisk programistycznych wspieranych przez AI

W skrócie: Claude Code nie jest oknem czatu z dostępem do plików. To programowalne środowisko wykonawcze z 30 udokumentowanymi zdarzeniami cyklu życia, z których każde można obsłużyć za pomocą skryptów powłoki, niemożliwych do pominięcia przez model. Łącząc hooks w dispatchers, dispatchers w skills, skills w agents, a agents w przepływy pracy, uzyskuje się autonomiczny harness programistyczny, który egzekwuje ograniczenia, deleguje pracę, zachowuje pamięć między sesjami i koordynuje wieloagentowe procesy deliberacji. W Claude Code v2.1.147 dodano domyślnie wyłączone narzędzie Workflow (CLAUDE_CODE_WORKFLOWS=1), przesuwając deterministyczną orkiestrację wieloagentową z czysto użytkowych skryptów w stronę natywnego elementu środowiska wykonawczego; v2.1.149 potwierdza tę samą zasadę od strony bezpieczeństwa, wprowadzając poprawki dotyczące obchodzenia uprawnień w PowerShell oraz listy dozwolonych operacji sandboxa dla git worktree. Za poprawność nadal odpowiadają hooks i evidence gates.⁵²⁵³ Ten przewodnik omawia każdą warstwę tego stosu: od pojedynczego hook po system konsensusu złożony z 10 agents. Nie wymaga żadnych frameworków. Wyłącznie bash i JSON.

Andrej Karpathy ukuł określenie na to, co powstaje wokół agenta LLM: claws. Są to hooks, skrypty i mechanizmy orkiestracji, dzięki którym agent może oddziaływać na świat poza swoim oknem kontekstu.¹ Większość programistów traktuje agentów AI do tworzenia kodu jak interaktywnych asystentów. Wpisują prompt, obserwują, jak agent edytuje plik, i przechodzą dalej. Takie podejście ogranicza produktywność do zakresu, który można osobiście nadzorować.

Model mentalny oparty na infrastrukturze jest inny: agent AI do tworzenia kodu to programowalne środowisko wykonawcze z jądrem LLM. Każda czynność wykonywana przez model przechodzi przez kontrolowane przez Państwa hooks. Definiuje się zasady, a nie prompty. Model działa w obrębie infrastruktury tak samo, jak serwer WWW działa zgodnie z regułami nginx. Nie siedzi się przed nginx, wpisując żądania. Konfiguruje się go, wdraża i monitoruje.

To rozróżnienie jest istotne, ponieważ korzyści z infrastruktury kumulują się. Hook blokujący dane uwierzytelniające w poleceniach bash chroni każdą sesję, każdego agenta i każde autonomiczne uruchomienie. Skill zawierający kryteria oceny jest stosowany konsekwentnie niezależnie od tego, czy uruchamiają go Państwo, czy agent. Agent sprawdzający kod pod kątem bezpieczeństwa wykonuje te same kontrole bez względu na to, czy jest obserwowany.²

Najważniejsze wnioski

• Hooks gwarantują wykonanie; prompty — nie. Hooks należy stosować do lintingu, formatowania, kontroli bezpieczeństwa oraz wszystkiego, co musi zostać uruchomione za każdym razem, niezależnie od zachowania modelu. Kod wyjścia 2 blokuje działania. Kod wyjścia 1 jedynie wyświetla ostrzeżenie.³
• Skills przechowują wiedzę dziedzinową i aktywują się automatycznie. Pole description decyduje o wszystkim. Claude wykorzystuje rozumowanie LLM (a nie dopasowywanie słów kluczowych), aby określić, kiedy zastosować skill.⁴
• Subagents zapobiegają przepełnieniu kontekstu. Odizolowane okna kontekstu przeznaczone do eksploracji i analizy pozwalają utrzymać główną sesję w zwartej formie. Niezależne subagents należy uruchamiać równolegle, a zespoły agentów stosować wtedy, gdy pracownicy potrzebują trwałej koordynacji.⁵
• Pamięć znajduje się w systemie plików. Pliki pozostają dostępne między kolejnymi oknami kontekstu. CLAUDE.md, MEMORY.md, foldery z regułami oraz dokumenty przekazania tworzą ustrukturyzowany system pamięci zewnętrznej.⁶
• Wieloagentowa deliberacja pozwala wykrywać pominięte kwestie. Pojedynczy agent nie potrafi podważyć własnych założeń. Dwóch niezależnych agentów o różnych priorytetach oceny wykrywa błędy strukturalne, których quality gates nie są w stanie wyeliminować.⁷
• Harness pattern jest całym systemem. CLAUDE.md, hooks, skills, agents i pamięć nie są niezależnymi funkcjami. Razem tworzą deterministyczną warstwę między Państwem a modelem, która skaluje się wraz z automatyzacją.

Jak korzystać z tego przewodnika

Każda sekcja opiera się na poprzedniej. Znajdujące się na końcu ramy decyzyjne zawierają tabelę pomocną przy wyborze odpowiedniego mechanizmu dla każdego rodzaju 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: komponowalny zestaw plików, skryptów i konwencji, który otacza agenta programistycznego AI deterministyczną infrastrukturą. Jego elementy:

┌──────────────────────────────────────────────────────────────┐
│                      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 foldery reguł określają, co agent wie o projekcie. Są ładowane automatycznie na początku sesji i po każdej kompakcji. Stanowią długoterminową pamięć architektoniczną agenta.

Warstwa rozszerzeń: skills dostarczają wiedzy dziedzinowej i aktywują się automatycznie zależnie od kontekstu. hooks zapewniają deterministyczne bramki uruchamiane przy każdym pasującym wywołaniu narzędzia. Pliki pamięci przechowują stan między sesjami. Agenci niestandardowi udostępniają wyspecjalizowane konfiguracje subagents.

Warstwa orkiestracji: Wzorce wieloagentowe koordynują niezależnych agentów podczas badań, przeglądów i analiz. Limity uruchomień zapobiegają niekontrolowanej rekursji. 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 korzystają z warstwy podstawowej wyłącznie do orkiestracji i podejmowania ostatecznych decyzji.²

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

Do początku 2026 roku jedyną realną możliwością było „zbudowanie własnego harness”. Zmieniło się to w kwietniu 2026 roku. Anthropic udostępniło Claude Managed Agents w publicznej wersji beta (8 kwietnia): pętlę harness + wykonywanie narzędzi + kontener sandbox + trwałość stanu jako REST API, rozliczane według standardowej liczby tokenów z dopłatą 0,08 USD za godzinę sesji. Aktualizacja Agents SDK firmy OpenAI (16 kwietnia) sformalizowała ten sam podział — harness i zasoby obliczeniowe jako osobne warstwy, z natywnymi dostawcami sandbox (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) oraz funkcjami tworzenia migawek i odtwarzania stanu, pozwalającymi przetrwać utratę kontenera.²³²⁴

Bardziej rozbudowane możliwości SDK po stronie OpenAI pojawiły się w openai-agents Python v0.14.0 (wydanym 15 kwietnia 2026 roku i ogłoszonym 16 kwietnia): podklasa SandboxAgent klasy Agent zawiera default_manifest, instrukcje sandbox i możliwości; Manifest opisuje kontrakt świeżego obszaru roboczego (pliki, foldery, pliki lokalne, repozytoria Git, zmienne środowiskowe, użytkowników i punkty montowania); SandboxRunConfig umożliwia konfigurowanie dla każdego uruchomienia klienta sandbox, wstrzykiwania aktywnej sesji, nadpisywania manifestu, migawek oraz 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 kompakcję. Pamięć sandbox zachowuje wyodrębnione wnioski między uruchomieniami i ujawnia je stopniowo; obszary robocze obsługują pliki lokalne, wpisy repozytoriów Git oraz zdalne punkty montowania (S3, R2, GCS, Azure Blob, S3 Files); migawki można przenosić między dostawcami. Dostępne backendy to: UnixLocalSandboxClient, DockerSandboxClient oraz hostowani klienci Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop i Vercel, dostępni przez opcjonalne dodatki.²⁴

Dla projektów Python, które chcą osadzić środowisko uruchomieniowe Claude Code jako bibliotekę — pomiędzy „wywoływaniem claude w powłoce” a „wysyłaniem żądań REST API do Managed Agents” — trzecią możliwością jest claude-agent-sdk-python. Seria wydań z 28–29 kwietnia (v0.1.69 → v0.1.71) zaktualizowała dołączony CLI do wersji v2.1.123, podniosła minimalną wersję zależności mcp do >=1.19.0 (starsze wersje bez komunikatu odrzucały wartości CallToolResult zwracane przez działające w procesie narzędzia MCP, przez co model otrzymywał blok z błędem walidacji) oraz zapewniła zgodność schematu SandboxNetworkConfig z TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Według stanu na 2026-08-01 pakiet w PyPI ma wersję v0.2.128 (zawiera Claude CLI v2.1.220, a minimalna wersja mcp wynosi obecnie >=1.23.0), natomiast TypeScript SDK ma wersję v0.3.220; linia 0.2.x stanowi przyrostowe rozwinięcie interfejsu 0.1.x opisanego w tym miejscu — poniższe opcje include_hook_events, skills i konfiguracji sandbox pozostają aktualne — a najnowsze wydania koncentrują się na niezawodności czyszczenia podprocesów i strumieni NDJSON.⁸⁶

Jeśli harness obejmuje warstwę głosową lub czasu rzeczywistego, w wersji openai-agents-python v0.17.0 (8 maja 2026) domyślnym modelem RealtimeAgent stał się gpt-realtime-2.⁴¹ Istniejące sesje czasu rzeczywistego automatycznie zaczną korzystać z nowego modelu domyślnego; aby na potrzeby ewaluacji zachować poprzednie działanie, należy jawnie przypiąć wcześniejszy model.

W lipcu 2026 roku oferta zarządzana po stronie OpenAI wzbogaciła się również o rozwiązanie wieloagentowe: openai-agents-python v0.18.2 (11 lipca) i openai-agents-js v0.13.2 (10 lipca) wprowadzają w wersji beta obsługę hostowanych systemów wieloagentowych — zarządzaną przez OpenAI orkiestrację wielu agentów jako usługę hostowaną, będącą bezpośrednim odpowiednikiem publicznej wersji beta Managed Multiagent Orchestration firmy Anthropic, opisanej w sekcji Orkiestracja wieloagentowa.⁷³ Obaj dostawcy oferują już na poziomie wieloagentowym ten sam kompromis, który poniższa tabela przedstawia dla pojedynczych agentów: dostawca uruchamia pętlę delegowania, ale użytkownik rezygnuje z możliwości korzystania z hooks.

Rozdzielenie ścieżek architektonicznych stało się faktem:

Które rozwiązanie wybrać: samodzielny hosting pozostaje właściwym wyborem dla zespołów dysponujących kompetencjami infrastrukturalnymi, chcących kontrolować własne skills/hooks lub gruntownie optymalizujących konkretny przepływ pracy. Rozwiązanie zarządzane sprawdzi się w zespołach bez dedykowanych inżynierów platformowych, gdy szybkość uzyskania wartości jest ważniejsza niż możliwości dostosowania albo gdy uruchomienia agentów muszą niezawodnie przetrwać zamknięcie laptopa bez konieczności samodzielnego budowania warstwy trwałości. Oba podejścia są zgodne — można uruchomić samodzielnie hostowany harness, który deleguje określone długotrwałe zadania do Managed Agents przez 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 ma określone zadanie. Drzewo ~/.claude/ stanowi osobistą infrastrukturę mającą zastosowanie do wszystkich projektów. Drzewo .claude/ w każdym repozytorium jest właściwe dla danego projektu i współdzielone przez git. Razem tworzą kompletny harness.

System skills

Skills to rozszerzenia uruchamiane przez model. Claude wykrywa je i stosuje automatycznie na podstawie kontekstu, bez konieczności ich jawnego wywoływania.⁴ Gdy zauważą Państwo, że po raz kolejny wyjaśniają ten sam kontekst w różnych sesjach, warto utworzyć skill.

Kiedy utworzyć skill

Skills służą do przechowywania wiedzy, którą Claude ma zawsze do dyspozycji. Polecenia slash służą do wykonywania działań wywoływanych jawnie. Przy wyborze między tymi rozwiązaniami warto zapytać: „Czy Claude ma stosować to automatycznie, czy to ja mam decydować, kiedy to uruchomić?”.

Tworzenie skill

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

Każdy skill wymaga pliku SKILL.md z metadanymi frontmatter w formacie 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

Opis pól frontmatter

Pole opisu ma kluczowe znaczenie

Na początku sesji Claude Code wyodrębnia wartości name i description każdego skill oraz umieszcza je w kontekście Claude. Po wysłaniu wiadomości Claude korzysta z wnioskowania modelu językowego, aby ustalić, czy któryś skill jest odpowiedni. Niezależna analiza kodu źródłowego Claude Code potwierdza ten mechanizm: opisy skills są umieszczane w sekcji available_skills promptu systemowego, a model wybiera odpowiednie skills za pomocą standardowego rozumienia języka.¹⁰

Nieprawidłowy 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: wykonywane działanie (przegląd kodu pod kątem konkretnych rodzajów problemów), sytuacje, w których należy go użyć (analiza zmian, PR-ów i jakości), oraz frazy wyzwalające (przegląd, audyt, kontrola), które użytkownicy wpisują w naturalny sposób.

Warto pamiętać, że automatyczna aktywacja jest regulowanym ustawieniem, a nie niezmienną zasadą: od wersji v2.1.215 Claude nie uruchamia już samodzielnie wbudowanych skills /verify i /code-review — działają one wyłącznie po jawnym wywołaniu. To celowe wycofanie się z aktywacji sterowanej opisem w przypadku rozbudowanych skills do przeglądu, których nieproszone uruchamianie kosztowało więcej, niż przynosiło korzyści.⁷⁴

Budżet kontekstu

Wszystkie opisy skills współdzielą budżet kontekstu, który skaluje się dynamicznie do 1% okna kontekstu, z wartością zapasową wynoszącą 8 000 znaków.⁴ Jeśli skills jest wiele, każdy opis powinien być zwięzły, a najważniejszy przypadek użycia należy umieścić na początku. Budżet można zastąpić za pomocą zmiennej środowiskowej SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ jednak lepszym rozwiązaniem są krótsze i precyzyjniejsze opisy. Aby sprawdzić, czy jakieś skills zostały wykluczone, należy uruchomić /context podczas sesji.

Pliki pomocnicze i organizacja

Skills mogą odwoływać się do dodatkowych plików znajdujących się 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

W pliku SKILL.md należy odwoływać się do nich za pomocą linków względnych. Claude odczytuje te pliki na żądanie po aktywowaniu skill. Plik SKILL.md powinien mieć mniej niż 500 wierszy, a szczegółowe materiały referencyjne należy przenieść do plików pomocniczych.¹²

Udostępnianie skills przez Git

Skills projektu (.claude/skills/ w katalogu głównym repozytorium) są udostępniane za pośrednictwem systemu kontroli 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 pobiorą zmiany, automatycznie otrzymają również skill. Bez instalacji i bez konfiguracji. To najskuteczniejszy sposób ujednolicania wiedzy specjalistycznej w całym zespole.

Skills jako biblioteka promptów

Poza skills o pojedynczym przeznaczeniu struktura katalogów może pełnić funkcję uporządkowanej biblioteki 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 Państwa wiedzy specjalistycznej. Razem tworzą bazę wiedzy, z której Claude korzysta automatycznie, zależnie od kontekstu. Młodszy programista otrzymuje wskazówki na poziomie starszego specjalisty bez konieczności proszenia o nie.

Łączenie skills z hooks

Skills mogą definiować we frontmatter własne hooks, które są aktywne tylko podczas działania danego skill. Pozwala to tworzyć zachowania właściwe dla danej dziedziny bez zaśmiecania 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 dotyczące filozofii pracy aktywują się automatycznie za pomocą hooks SessionStart, wprowadzając ograniczenia jakościowe do każdej sesji bez jawnego wywołania. Sam skill stanowi wiedzę. Hook zapewnia egzekwowanie zasad. Razem tworzą warstwę polityk.

Typowe błędy dotyczące skills

Zbyt szerokie opisy. Skill git-rebase-helper, który aktywuje się przy każdym prompcie związanym z gitem (rebase, scalanie, 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 konkurujących o budżet. Większa liczba skills oznacza więcej opisów konkurujących o 1% budżetu kontekstu. Jeśli skills przestają się aktywować, należy sprawdzić w /context, które z nich zostały wykluczone. Lepiej postawić na mniejszą liczbę dobrze opisanych skills niż na wiele nieprecyzyjnych.

Kluczowe informacje ukryte w plikach pomocniczych. Claude odczytuje SKILL.md natychmiast, ale uzyskuje dostęp do plików pomocniczych tylko w razie potrzeby. Jeśli kluczowe informacje znajdują się w pliku pomocniczym, Claude może ich nie znaleźć. Najważniejsze informacje należy umieszczać bezpośrednio w SKILL.md.⁴

Powierzchnia skills w SDK (8 maja 2026)

Samodzielnie hostowane harnesses korzystające z claude-agent-sdk-python v0.1.77+ powinny deklarować dostępne skills za pomocą opcji skills w ClaudeAgentOptions, a nie przestarzałej wartości "Skill" w allowed_tools.³⁷ Skrót "Skill" jest przestarzały, natomiast dedykowana opcja przekazuje Claude Code bardziej uporządkowane informacje o dostępnych skills. Wersja v0.1.77 zawiera CLI v2.1.133.

Ujednolicenie plugins i skills w .claude/skills/ (29 maja 2026)

Skills od zawsze były ładowane z katalogu projektu .claude/skills/. Claude Code v2.1.157 rozszerza obsługę tego katalogu na plugins: plugin umieszczony w .claude/skills/ jest teraz ładowany automatycznie, bez rejestracji w marketplace, a polecenie claude plugin init <name> tworzy tam nowy szkielet wraz z poprawnie połączonymi manifestem i SKILL.md.⁵⁸ Zamyka to lukę między 2 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 oraz serwer MCP, lecz wcześniej wymagał instalacji przez marketplace. Praktyczny skutek dla projektowania harness: narzędzia o zakresie projektowym nie muszą już trafiać do rejestru przed udostępnieniem — wystarczy je utworzyć i zatwierdzić w repozytorium, a członkowie zespołu otrzymają tę samą powierzchnię po wykonaniu git pull. Plugins nadal obsługują przypadki wymagające instalowalnego pakietu (hooks + skills + serwery MCP + agenci w jednym pliku ZIP); zmiana polega na tym, że projekt nie musi już uruchamiać marketplace wyłącznie po to, aby załadować plugin z własnego drzewa katalogów.

Ukrywanie wbudowanej powierzchni jako mechanizm zarządzania (8 czerwca 2026)

Skills zapewniają możliwości, a możliwości tworzą powierzchnię 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 wbudowane skills, przepływy pracy i polecenia slash.⁶⁰ W utwardzonym lub regulowanym harness jest to celowe ograniczenie powierzchni ataku: operator, który przeprowadził audyt i zatwierdził określony zestaw skills projektowych oraz osobistych, może wyłączyć wszystko, co Anthropic dostarcza w standardzie, dzięki czemu model będzie analizował wyłącznie powierzchnię zweryfikowaną przez operatora. Należy traktować to tak samo jak listę dozwolonych narzędzi — domyślna konfiguracja oferuje szerokie możliwości, a jej wyłączenie jest decyzją dotyczącą zarządzania, nie przełącznikiem wygody.

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

W wersji Claude Code v2.1.178 narzędzia projektowe stały się świadome lokalizacji. Skills w zagnieżdżonych katalogach .claude/skills są teraz ładowane podczas pracy nad plikami znajdującymi się w danym katalogu, a nie wyłącznie z katalogu głównego repozytorium; w przypadku konfliktu 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 według odległości od katalogu roboczego: gdy nazwa agenta, przepływu pracy lub stylu wyjściowego koliduje w zagnieżdżonych katalogach .claude/, pierwszeństwo ma element znajdujący się najbliżej katalogu roboczego, a zapis przepływu pracy o zakresie projektowym trafia do najbliższego istniejącego katalogu .claude/workflows/, zamiast zawsze do katalogu głównego.⁶³ W monorepo lub repozytorium zagnieżdżającym inne repozytoria oznacza to różnicę między jedną płaską, globalną powierzchnią a narzędziami poszczególnych pakietów, które aktywują się zależnie od kontekstu — katalog services/api/.claude/skills/ może zawierać skills właściwe dla API, widoczne wyłącznie podczas pracy w tym drzewie, bez konfliktu ze skill o tej samej nazwie w services/web/.

Architektura hooks

Hooks 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 /? Dziesięciowierszowy skrypt bash sprawdza polecenie względem listy blokowanych operacji i odrzuca je, zanim jeszcze trafi ono do powłoki. Hook uruchamia się niezależnie od tego, czy model tego chce.

Dostępne zdarzenia

W chwili aktualizacji tego przewodnika Claude Code udostępnia 30 udokumentowanych zdarzeń cyklu życia w ośmiu kategoriach. Lista zdarzeń rozszerza się wraz z kolejnymi wydaniami, dlatego dokumentację referencyjną należy traktować jako źródło prawdy, a przed skonfigurowaniem produkcyjnych hooks warto sprawdzić ściągę, która zawiera aktualną, pełną tabelę:¹³

DirectoryAdded (v2.1.219) eliminuje lukę dotyczącą przestrzeni roboczej w trakcie sesji. Lista zdarzeń pozostawała niezmieniona od wprowadzenia MessageDisplay w wersji v2.1.152; DirectoryAdded jest pierwszym nowym zdarzeniem cyklu życia od tamtej pory i uruchamia się po zarejestrowaniu nowego katalogu roboczego w trakcie sesji za pomocą /add-dir lub żądania sterującego register_repo_root pochodzącego z SDK.⁸⁴ Luka, którą eliminuje, jest istotna: dotychczas harness mógł szczegółowo zweryfikować przestrzeń roboczą podczas SessionStart, po czym do sesji można było dołączyć drugie repozytorium bez wywołania jakiegokolwiek hook. Wszystkie założenia dotyczące przestrzeni roboczej sprawdzane podczas uruchamiania — kontrole zaufania, skanowanie w poszukiwaniu sekretów, reguły zakresu ścieżek wyprowadzone ze struktury drzewa, wczytywanie zasad dla poszczególnych repozytoriów — należy sprawdzić ponownie w tym miejscu, ponieważ zestaw katalogów sesji nie jest już niezmienny od chwili jej uruchomienia. Zdarzenie ma charakter informacyjny, a nie blokujący, dlatego należy traktować je jako sygnał do ponownego wyznaczenia stanu i zapisania pochodzenia, nie jako gate; jeżeli dodanie określonego katalogu ma być zawsze zabronione, należy odmówić dostępu w ustawieniach, zamiast próbować zawetować tę operację za pomocą hook. Obsługa po stronie SDK pojawiła się w tym samym wydaniu (TypeScript v0.3.219 dodaje DirectoryAdded do zdarzeń cyklu życia protokołu sterującego), dzięki czemu harnesses hostowane w SDK obsługują je na takich samych zasadach jak te hostowane w CLI.⁸⁵

Znaczenie kodów wyjścia

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

Konfiguracja hooks

Hooks znajdują się w plikach ustawień. Hooks współdzielone należy umieszczać na poziomie projektu (.claude/settings.json), a osobiste — na poziomie użytkownika (~/.claude/settings.json):

{
  "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ść właściwą dla danego zdarzenia. W przypadku zdarzeń narzędzi dopasowuje wartości tool_name, takie jak Bash, Edit, Write, Read, Glob, Grep, nazwy narzędzi MCP, np. mcp__server__tool, albo * oznaczającą wszystkie narzędzia. Proste nazwy i listy rozdzielone znakiem | są dopasowywane dokładnie; wartości zawierające inne znaki są wyrażeniami regularnymi JavaScript. Niektóre zdarzenia nie obsługują matcherów i po skonfigurowaniu uruchamiają się zawsze.¹³ Od wersji 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 przeznaczony dla jednego agenta lub serwera nie uruchamia się już dla każdej nazwy, która jedynie zawiera dany ciąg znaków; aby objąć wszystkie narzędzia z serwera MCP o nazwie zawierającej łącznik, należy podać jawny wzorzec mcp__brave-search__.*.⁶⁶ W wersji v2.1.214 tę samą dyscyplinę zastosowano do wzorców ścieżek: warunek if: hook korzystający z 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 zmiana z wersji v2.1.195, ta poprawka zastępuje przypadkowo szeroki zakres jawnie zadeklarowaną intencją; należy skontrolować wszystkie warunki hooks, które niejawnie polegały na wcześniejszym zachowaniu obejmującym dowolną głębokość.

Protokół wejścia/wyjścia hooks

Hooks otrzymują na stdin dane JSON 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"
}

Aby uzyskać zaawansowaną kontrolę, hooks PreToolUse mogą zwracać dane JSON, by zmodyfikować dane wejściowe narzędzia, wstrzyknąć kontekst lub podejmować decyzje dotyczące uprawnień. Należy używać opakowania hookSpecificOutput — starszy format najwyższego poziomu decision/reason jest przestarzały w przypadku 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 utworzeniem jakiegokolwiek hook należy zapytać: jakiego rodzaju gwarancji potrzebuję?¹⁴

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

{
  "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. Hooks PreToolUse dla Bash sprawdzają polecenia i blokują destrukcyjne wzorce za pomocą kodu 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 weryfikują stan w punktach decyzyjnych. Hooks 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 hooks inne niż polecenia powłoki

Claude Code obsługuje pięć typów hooks:¹³

Command hooks (type: "command") uruchamiają skrypty powłoki. Są szybkie, deterministyczne i nie zużywają tokenów. MCP tool hooks (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.

Prompt hooks (type: "prompt") wysyłają jednorazowy prompt do szybkiego modelu Claude. Model zwraca { "ok": true }, aby zezwolić na operację, lub { "ok": false, "reason": "..." }, aby ją zablokować. Sprawdzają się przy złożonych ocenach, których nie da się wyrazić za pomocą wyrażeń regularnych.

Agent hooks (type: "agent") uruchamiają subagent z dostępem do narzędzi (Read, Grep, Glob) w celu przeprowadzenia wieloetapowej weryfikacji. Są eksperymentalne; w bramkach produkcyjnych lepiej stosować command hooks, a agent hooks zarezerwować dla kontroli, które rzeczywiście wymagają sprawdzenia konkretnych 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 agent hook zawierają subagent_type, dzięki czemu współdzielony hook może odróżnić uruchomienie security-reviewer od explorer lub standardowego worker bez zgadywania na podstawie treści promptu.⁴⁹

HTTP hooks (type: "http") wysyłają dane wejściowe zdarzenia w formacie JSON jako żądanie POST pod wskazany URL i otrzymują w odpowiedzi dane 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 hooks

Hooks mogą działać w tle bez blokowania wykonywania. W przypadku operacji niekrytycznych, takich jak powiadomienia i rejestrowanie zdarzeń, 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. Nie wolno go stosować do formatowania, walidacji ani żadnych operacji, które muszą zakończyć się przed następnym działaniem.

Dispatchers zamiast niezależnych hooks

Uruchomienie siedmiu hooks reagujących na to samo zdarzenie, z których każdy niezależnie odczytuje stdin, prowadzi do sytuacji wyścigu. Dwa hooks zapisujące równocześnie do tego samego pliku stanu JSON spowodują obcięcie danych JSON. W rezultacie każdy kolejny hook analizujący ten plik przestanie działać.²

Rozwiązaniem jest jeden dispatcher na każde zdarzenie, który uruchamia hooks sekwencyjnie, korzystając z 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 hooks

Pięć technik debugowania hooks, które zawodzą bez widocznego błędu:¹⁴

1. Testować skrypty niezależnie. Przekazać przykładowe dane JSON przez potok: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Używać stderr do danych diagnostycznych. Dane stderr przy kodzie wyjścia 2 są przekazywane z powrotem do Claude jako komunikat o błędzie. Nieblokujące dane stderr (kod wyjścia 1, 3 itd.) są widoczne tylko w trybie szczegółowym (Ctrl+O).
3. Uważać na błędy jq. Nieprawidłowe ścieżki JSON zwracają po cichu null. Wyrażenia jq należy testować na rzeczywistych danych wejściowych narzędzia.
4. Sprawdzać kody wyjścia. PreToolUse hook korzystający z exit 1 nie wymusza żadnych ograniczeń, choć może sprawiać wrażenie działającego.
5. Dbać o szybkość hooks. Hooks działają synchronicznie. Każdy hook powinien kończyć działanie w czasie krótszym niż 2 sekundy, a najlepiej poniżej 500 ms.

Strumieniowanie zdarzeń hooks po stronie SDK

Samodzielnie hostowane harnesses zbudowane na claude-agent-sdk-python (v0.1.74+, 6 maja 2026) mogą subskrybować zdarzenia hooks 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, a obiekty HookEventMessage (PreToolUse, PostToolUse, Stop i inne) będą zwracane z tego samego iteratora co komunikaty asystenta i wyniki narzędzi. Odpowiada to opcji includeHookEvents w TypeScript SDK; w tym samym wydaniu dołączony CLI zaktualizowano do wersji v2.1.129.

Wzorzec strumienia zdarzeń jest właściwym wyborem, gdy harness działa już w Python i sygnały hooks mają trafiać do tego samego przepływu sterowania co dane wyjściowe modelu. Kontrakt hooks opartych na skryptach powłoki (kody wyjścia, dane JSON ze stdin, dispatchers) pozostaje właściwym rozwiązaniem dla harnesses, które łączą wiele narzędzi, współdzielą hooks między Claude Code a Codex lub wymagają semantyki kodów wyjścia do blokowania operacji.

Seria wydań TypeScript SDK z lipca 2026 (v0.3.205–v0.3.208) nadała również bardziej kontraktowy charakter samemu protokołowi strumieniowemu.⁷⁰ Przerwania zwracają teraz typowane potwierdzenia: potwierdzenie przerwania wskazuje za pomocą identyfikatorów UUID still_queued, które komunikaty nadal oczekują w kolejce, a sesje ogłaszają funkcję interrupt_receipt_v1 w system/init. Dzięki temu koordynator może odróżnić sytuację, w której „przerwanie zostało przyjęte”, od sytuacji, w której „przerwanie minęło się z komunikatem będącym już w trakcie przetwarzania”. Ramki command_lifecycle raportują dla każdego komunikatu stany queued/started/completed/cancelled/discarded — to pierwsza natywna odpowiedź na pytanie „co stało się z wysłanym komunikatem”, niewymagająca wnioskowania z transkrypcji. Dodano także mniejsze elementy: typ AgentToolCompletedOutput dla danych ukończenia subagent oraz możliwość zwracania przez wywołania zwrotne canUseTool wartości {behavior: 'allow'} bez pola updatedInput.

Jedna pozycja w tej serii wyznacza minimalny poziom bezpieczeństwa, a nie nową funkcję: w wersji v0.3.208 naprawiono błąd, przez który przerwanie wywołane podczas oczekiwania na hook było interpretowane jako pomyślne wykonanie hook — w efekcie narzędzie kontrolowane przez PreToolUse hook mogło zostać uruchomione po przerwaniu przez wywołującego.⁷⁰ Jeżeli harness używa hooks po stronie SDK jako bramki uprawnień i polega na przerwaniu w celu anulowania trwających operacji, wersję v0.3.208 należy traktować jako minimalną; we wcześniejszych wersjach „przerwane” nie oznaczało niezawodnie „zablokowane”. Python v0.2.127 (24 lipca 2026) to drugi w ciągu miesiąca przypadek obejścia zabezpieczeń według tego schematu — query() zamykało stdin po pierwszej ramce result, gdy subagents w tle nadal działały, przez co ich wywołania narzędzi SDK-MCP kończyły się błędem "Stream closed" i całkowicie omijały PreToolUse hooks.⁸⁵ Warto nazwać ten wzorzec i go monitorować: egzekwowanie reguł przez hooks po stronie SDK zawodzi w sposób otwarty na granicach cyklu życia — podczas przerwania, zamykania lub zamknięcia strumienia — gdy transport przestaje działać przed odebraniem werdyktu hook. Co gorsza, dzieje się to bez widocznego sygnału, ponieważ pominięty hook wygląda dokładnie tak samo jak hook, który wyraził zgodę. Należy przypiąć minimalne wersje obu SDK i zachować warstwę shell hooks jako mechanizm egzekwowania, którego działanie można udowodnić.

Poziom effort i pochodzenie sesji (7–8 maja 2026)

Dwa dodatki w Claude Code v2.1.132 i v2.1.133 zapewniają hooks i podprocesom lepsze informacje o kontekście wykonywania:³⁸³⁹

• effort.level w danych wejściowych hook. Hooks 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 danych JSON. Pozwala to dostosować koszt hook do poziomu effort: pominąć kosztowną walidację przy low, a uruchomić pełną bramkę bezpieczeństwa przy xhigh lub max.
• Zmienna środowiskowa CLAUDE_CODE_SESSION_ID w podprocesach Bash. Podprocesy narzędzia Bash otrzymują teraz tę samą wartość session_id, którą widzą hooks, udostępnioną jako CLAUDE_CODE_SESSION_ID. Eliminuje to lukę w identyfikowaniu pochodzenia zdarzeń przez narzędzia, które rejestrują stan osobno dla każdej sesji, a wcześniej nie mogły powiązać zdarzeń podprocesów ze zdarzeniami hooks.

Oba sygnały są dostępne bez zmian w kodzie; istniejące hooks, które ignorują nowe pola, nadal działają.

autoMode.hard_deny oraz poprawki hooks i pluginów w wersji v2.1.136 (8 maja 2026)

W wersji Claude Code v2.1.136 dodano nowy poziom bezwzględnej odmowy do trybu automatycznego oraz usunięto zestaw problemów z pluginami i MCP, które wpływały na długotrwałe działanie 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. Mechanizm ten znajduje się ponad istniejącymi regułami dopasowania zezwoleń i odmów, stanowiąc niepodważalny instrument nadzoru. Należy go używać do reguł, których nigdy nie wolno omijać (wymuszone wypychanie zmian do gałęzi main, pliki zawierające dane poufne, dostęp do produkcyjnej bazy danych), nawet jeśli operator zatwierdził szerszą kategorię w swoich ustawieniach osobistych. - autoMode.classifyAllShell (v2.1.193). Domyślnie klasyfikator trybu automatycznego sprawdza jedynie polecenia powłoki pasujące do wzorców wykonywania dowolnego kodu. To ustawienie kieruje każde polecenie Bash/PowerShell do klasyfikatora — jest to podejście zapewniające maksymalny zakres kontroli w zarządzanym harness — a ta sama wersja udostępnia powody odmowy w transkrypcji, powiadomieniu i /permissions, dzięki czemu ciche blokady stają się decyzjami podlegającymi audytowi. W wersji v0.142.2 Codex zaostrzył zasady dotyczące analogicznego mechanizmu: polecenia PowerShell zawierające wykonywalne regiony AST, których klasyfikator bezpieczeństwa nie może sprawdzić, wymagają teraz zatwierdzenia, zamiast przechodzić bez ostrzeżenia.⁶⁶ - Hook ask wyznacza dolną granicę decyzji klasyfikatora (v2.1.211). Rozstrzygnięto już kwestię pierwszeństwa hook względem trybu automatycznego: hook PreToolUse, który zwraca decyzję uprawnień ask, ustala jako minimalny wynik końcowy wyświetlenie monitu — tryb automatyczny nie może ponownie zmienić tej decyzji na zezwolenie w przypadku poleceń Bash wykonywanych poza sandboxem.⁶⁹ W zarządzanym harness jest to brakujący poziom gwarancji: ask zwrócone przez hook stanowi deterministyczny punkt zatrzymania wymagający udziału człowieka, który pozostaje aktywny nawet przy w pełni automatycznym podejściu do uprawnień. W przypadku operacji, dla których potrzebna jest decyzja człowieka, a nie odmowa, należy używać ask (zamiast polegać wyłącznie na blokadach z kodem wyjścia 2). - Model klasyfikatora jest przypisany na czas sesji (v2.1.210). Klasyfikator trybu automatycznego domyślnie korzysta z modelu Sonnet 5, który zostaje przypisany na czas sesji, dlatego zmiana modelu w jej trakcie nie wpływa już na to, który model klasyfikuje uprawnienia.⁶⁹ Spójność klasyfikacji jest właściwością mechanizmu nadzoru; ta zmiana usuwa trudno zauważalne źródło rozbieżności. - Serwery MCP nie znikają już po /clear. Serwery skonfigurowane w .mcp.json, wtyczkach i konektorach claude.ai były bez ostrzeżenia usuwane z aktywnego zestawu po wykonaniu /clear w rozszerzeniu VS Code, wtyczce JetBrains i Agent SDK. Poprawkę wprowadzono w wersji v2.1.136. Jeśli występował problem „serwer MCP X zniknął w trakcie sesji”, właśnie to było jego przyczyną. - 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 operacje zapisu podczas odświeżania nadpisywały się wzajemnie. - Tryb planowania prawidłowo blokuje teraz zapis plików. Pasująca reguła zezwalająca Edit(...) omijała ochronę przed zapisem w trybie planowania. Tryb planowania jest teraz egzekwowany niezależnie od reguł zezwalających. - Hook Stop i UserPromptSubmit wtyczek nie przestają już działać w trakcie sesji. Czyszczenie pamięci podręcznej usuwało nadal używane przez aktywną sesję pliki wersji wtyczek, co powodowało awarie właśnie tych dwóch zdarzeń hook. Poprawka zachowuje przypięte wersje będące w użyciu. - Wpis skills w plugin.json. Ustawienie skills ukrywało domyślny katalog skills/ wtyczki. Obecnie wpis jest prawidłowo łączony z ustawieniem domyślnym, a wskazanie ścieżki do pliku powoduje wyświetlenie jednoznacznego błędu zamiast cichej awarii. - Dezaktualizacja zmiennych środowiskowych hook SessionStart z CLAUDE_ENV_FILE. Zmienne eksportowane przez hook SessionStart za pośrednictwem CLAUDE_ENV_FILE stawały się nieaktualne po /resume lub /clear. Naprawiono to w wersji v2.1.136. Podczas tych zdarzeń sesje ponownie wczytują teraz plik środowiskowy.

W przypadku harness służących do nadzoru operacyjnie najistotniejsze pozycje to autoMode.hard_deny (nowy instrument) oraz poprawka zapobiegająca znikaniu MCP (cicha awaria, która zakłócała długie sesje). Wszystkie pozostałe zmiany to usprawnienia zwiększające wygodę użytkowania.

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

W Claude Code v2.1.139 dodano dwa szczegóły dotyczące hook, które mają znaczenie dla produkcyjnych harness: formę wykonywania hook poleceń args: string[] oraz continueOnBlock dla hook PostToolUse.⁴²⁴⁴ Gdy hook wymaga wartości dynamicznych lub symboli zastępczych ścieżek, warto używać args. Polecenie jest wówczas uruchamiane bezpośrednio, bez powłoki, co eliminuje całą klasę błędów związanych z cudzysłowami i wstrzykiwaniem poleceń.

Opcji continueOnBlock należy używać, gdy hook PostToolUse ma przekazać Claude powód odrzucenia i kontynuować turę zamiast kończyć przepływ. Należy traktować ją jako funkcję poprawiającą komfort pracy operatora, a nie sposób na obejście zabezpieczeń. Bramka blokująca nadal powinna uniemożliwiać niebezpieczny rezultat.

Ta sama wersja przekazuje CLAUDE_PROJECT_DIR serwerom stdio MCP i pozwala konfiguracjom wtyczek odwoływać się do ${CLAUDE_PROJECT_DIR} w poleceniach.⁴² Narzędzia MCP powinny rozwiązywać ścieżki względne projektu na podstawie tej wartości, a nie katalogu roboczego procesu, z którego przypadkowo uruchomiono serwer. Wersje z początku lipca 2026 (v2.1.203–v2.1.206) rozszerzyły tę samą zasadę na poziom protokołu: lista MCP roots/list obejmuje teraz dodatkowe katalogi robocze sesji, a po ich zmianie wysyłane są powiadomienia roots/list_changed — dzięki temu serwer respektujący katalogi główne MCP odzwierciedla rzeczywistą strukturę obszaru roboczego obejmującego wiele katalogów, zamiast zakładać istnienie jednego katalogu projektu.⁶⁸

Claude Code v2.1.140 to przede wszystkim wersja poprawiająca niezawodność z perspektywy operatorów harness: naprawia brak uruchamiania hook ConfigChange po zmianie ustawień, usuwa przypadki brzegowe, w których disableAllHooks i allowManagedHooksOnly nie współdziałały prawidłowo na różnych poziomach ustawień, oraz zapobiega ujawnianiu w oknach dialogowych uprawnień niezamierzonych zmiennych środowiskowych zwracanych przez wyniki hook.⁴⁹ Dzięki temu istniejące wzorce nadzoru opisane w tej sekcji działają niezawodniej; nowa architektura hook nie jest wymagana.

Claude Code v2.1.141 dodaje do danych wyjściowych hook pole terminalSequence, przeznaczone do obsługi powiadomień na pulpicie, tytułów okien i sygnałów dźwiękowych bez terminala sterującego.⁵⁰ Należy traktować je jako mechanizm sygnalizowania operatorowi, a nie egzekwowania zasad. Bramy bezpieczeństwa i jakości powinny nadal informować o błędach za pośrednictwem standardowego kontraktu blokującego: ustrukturyzowanych danych wyjściowych hook wraz z zachowaniem przy wyjściu, które zapobiega niebezpiecznej operacji. Ta sama wersja dodaje claude agents --cwd <path> do ograniczania widoku Agent View do jednego katalogu, CLAUDE_CODE_PLUGIN_PREFER_HTTPS do instalowania wtyczek w środowiskach bez kluczy GitHub SSH oraz ANTHROPIC_WORKSPACE_ID do reguł federacji tożsamości obciążeń obejmujących więcej niż jeden obszar roboczy.⁵⁰ Są to szczegóły architektury zespołowych harness: węższe widoki operacyjne, mniej założeń dotyczących instalacji wtyczek oraz jawne określanie zakresu tokenów korporacyjnych.

Claude Code v2.1.142 ma większe znaczenie dla orkiestracji sesji działających w tle niż dla semantyki hook.⁵¹ claude agents może teraz uruchamiać sesje w tle z jawnymi flagami katalogu, ustawień, MCP, wtyczki, uprawnień, modelu i poziomu wysiłku, zamiast polegać na stanie skryptu opakowującego. W tej wersji tryb szybki domyślnie korzystał z Opus 4.7, a CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 pozwalało przypiąć Opus 4.6 w harness, którego zmierzone działanie zależało od zachowania tego modelu — od wersji v2.1.219 Opus 4.7 został całkowicie wycofany z trybu szybkiego, a /fast ma zastosowanie do Opus 5 i Opus 4.8.⁸⁴ Wykrywanie pliku SKILL.md w katalogu głównym wtyczki oraz widoczność LSP udostępnianego przez wtyczkę ograniczają niejednoznaczności związane z pakowaniem. Poprawki dotyczące MCP_TOOL_TIMEOUT, wcześniej istniejących drzew roboczych sesji w tle, usypiania i wybudzania demona oraz sprzątania po aktualizacji, a także czyszczenia pamięci podręcznej wtyczek usuwają luki w niezawodności, które w przeciwnym razie mogłyby wyglądać na błędy orkiestracji.

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

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

Hook Stop/SubagentStop zyskały kanał sterujący. Od wersji Claude Code v2.1.163 hook Stop lub SubagentStop może zwrócić hookSpecificOutput.additionalContext, aby przekazać Claude informację zwrotną i kontynuować turę bez oznaczania odpowiedzi jako błędu hook. Wcześniej jedynym rzeczywistym narzędziem hook Stop była blokada z kodem wyjścia 2, która jest prezentowana jako błąd i wliczana do limitu kolejnych blokad. W przypadku harness z bramą jakości jest to bardziej przejrzysty mechanizm: hook Stop, który wykryje sytuację „zadeklarowano ukończenie, ale testy nie przechodzą”, może teraz przekazać „oto elementy, które nadal nie działają — kontynuuj”, zamiast stosować twardą blokadę. Blokady należy używać w przypadku rzeczywistych warunków zatrzymania, a additionalContext do przekazywania komunikatu „praca nie jest jeszcze ukończona — oto dlaczego”.

Komunikacja między sesjami nie przenosi już zapożyczonych uprawnień. Wersja v2.1.166 wzmocniła zabezpieczenia w scenariuszach wielosesyjnych: wiadomości przekazywane za pośrednictwem SendMessage z innej sesji Claude nie przenoszą już uprawnień użytkownika będącego ich źródłem, dlatego sesja odbierająca odrzuca przekazane żądania uprawnień, a tryb automatyczny je blokuje. Jeśli w ramach orkiestracji agenci komunikują się ze sobą, wiadomość przychodzącą należy traktować jako niezaufane dane, a nie jako uwierzytelnioną instrukcję. Jest to ta sama zasada, którą sekcja dotycząca bezpieczeństwa stosuje do danych wyjściowych narzędzi, rozszerzona na komunikację między agentami. Od wersji v2.1.199 Claude Code wykrywa również i zgłasza ostrzeżenie, gdy SendMessage trafia do niewłaściwego odbiorcy z powodu nadania tej samej nazwy dwóm agentom — stanowi to uzupełnienie granicy uprawnień w zakresie niezawodności, ponieważ wiadomość docierająca do niewłaściwego agenta o tej samej nazwie jest odrębną klasą błędów orkiestracji. Odporność modelu stała się pełnoprawnym ustawieniem. Ustawienie fallbackModel pozwala teraz utworzyć łańcuch obejmujący maksymalnie 3 modele zapasowe, uruchamiane kolejno, gdy model podstawowy jest przeciążony lub niedostępny. W przypadku nieoczekiwanych, nieponawialnych błędów API dana tura jest automatycznie ponawiana raz z użyciem modelu zapasowego. W długotrwale działającym autonomicznym harnessie oznacza to, że chwilowa awaria modelu podstawowego prowadzi do kontrolowanego ograniczenia możliwości zamiast przerwania całego przebiegu. Polecenie claude agents --json otrzymało również pole waitingFor (v2.1.162), które pokazuje, na co oczekuje zablokowana sesja działająca w tle, na przykład na potwierdzenie uprawnień — to istotna poprawa obserwowalności dla każdego koordynatora monitorującego flotę agentów.

Tryb bezpieczny do zarządzania w środowisku clean-room i rozwiązywania problemów. Claude Code v2.1.169 wprowadza 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, wtyczkami, skills, hooks i serwerami MCP.⁶⁰ To przeciwieństwo harnessu — celowo utworzone środowisko clean-room. Pozwala odpowiedzieć na pytanie, które prędzej czy później zadaje sobie każdy operator: „czy to zachowanie wynika z działania modelu, czy z mojej konfiguracji?”. Gdy hook uruchamia się nieprawidłowo, skill aktywuje się w niewłaściwym momencie albo serwer MCP zanieczyszcza kontekst, --safe-mode zapewnia znany, pusty punkt odniesienia, z którym można porównać zachowanie systemu. Jest to również mechanizm zarządzania: sposób na uruchomienie samego modelu bez żadnych trwałych uprawnień, które zwykle nadaje mu harness. Ma to znaczenie, gdy trzeba odtworzyć wynik bez wpływu jakiejkolwiek struktury pomocniczej zdefiniowanej przez operatora.

Uwaga dotycząca poziomów modeli. Od wersji Claude Code v2.1.197 (30 czerwca 2026) Claude Sonnet 5 jest domyślnie dostarczanym modelem dla nowych sesji — oferuje natywny kontekst 1M i promocyjne ceny 2/10 USD za MTok do 31 sierpnia — zastępując Opus 4.8 jako wybór dostępny od razu po instalacji. W tym przewodniku Opus 5 (claude-opus-5) jest zalecanym domyślnym modelem agentowym: to model, na którym warto uruchamiać autonomiczne harnessy, chyba że świadomie wybrano inaczej, ponieważ właśnie w długoterminowych pętlach agentów o wysokiej stawce głębia rozumowania Opus uzasadnia jego koszt. Opus 5 został wydany 24 lipca 2026 jako nowy domyślny Opus w Claude Code v2.1.219 — kontekst 1M, cena 5/25 USD za MTok (taka sama jak zastępowanego Opus 4.8) oraz tryb szybki w cenie 10/50 USD, zapewniający około 2,5-krotnie większą szybkość od trybu domyślnego — a według Anthropic osiąga ponad dwukrotnie lepszy wynik niż Opus 4.8 w Frontier-Bench v0.1 oraz wynik gorszy zaledwie o 0,5% od Fable 5 w CursorBench 3.2, kosztując przy tym o połowę mniej.⁸⁴⁸⁷ Ta sama cena, większe możliwości i model, który Anthropic określa jako „znacznie lepszy w weryfikowaniu własnej pracy i starannym iterowaniu”, tworzą rzadki przypadek aktualizacji, której w zastosowaniach harnessowych nie trzeba uzasadniać kosztami; migracja z wersji 4.8 wymaga jedynie zmiany identyfikatora. W przypadku zadań wrażliwych na koszty lub wymagających dużej przepustowości warto przejść na Sonnet 5, gdy przewagę daje jego stosunek szybkości do inteligencji. Powyżej Opus znajduje się Claude Fable 5 (claude-fable-5), wydany 9 czerwca 2026 — nowy poziom opisywany jako najpotężniejszy model Anthropic, system klasy „Mythos” przystosowany do bezpiecznego użytku ogólnego, który można wybrać w Claude Code v2.1.170 za pomocą /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 jako po uniwersalne ustawienie dla całej floty. Przejście na Opus 5 ma 2 konsekwencje porządkowe: Opus 4.7 nie jest już dostępny w trybie szybkim (/fast ma teraz zastosowanie do Opus 5 i Opus 4.8), a model zapasowy Fable-5 klasyfikatora trybu automatycznego — „najlepszy dostępny model Opus” od wersji v2.1.176 — wskazuje teraz Opus 5.⁸⁴

Codex udostępnił multi-agent v2. Codex CLI v0.137.0 pozostawia wybór środowiska uruchomieniowego poszczególnym wątkom, zapewnia przejrzystsze ustawienia domyślne dotyczące dalszych poleceń i metadanych tworzonych agentów (hide_spawn_agent_metadata ma teraz domyślnie wartość true) oraz przekazuje nieprzetworzone zdarzenia nadrzędne do procesów nasłuchujących agentów potomnych. Model subagents pozostaje jawny: wbudowane typy agentów default/worker/explorer, niestandardowi agenci definiowani w TOML oraz mechanizmy kontroli współbieżności (agents.max_threads ma domyślną wartość 6, a agents.max_depth — 1). Ta sama wersja dodaje rozszerzenie skills v1 z rozpoznawaniem katalogu skills w każdej turze oraz nowe zdarzenia współtwórców cyklu życia przy rozpoczęciu wątku i błędzie tury. Zmniejsza to różnicę względem interfejsu hooks/skills oferowanego przez Claude Code, a jednocześnie zachowuje podejście oparte na sandboxie jądra jako domyślnej granicy. Następnie wersje Codex v0.138.0–v0.139.0 wzmocniły multi-agent v2 z myślą o środowiskach produkcyjnych: komunikaty przesyłane między agentami są teraz szyfrowane, katalog konfiguracji agentów v2 wraz z mechanizmem LRU rezydentności agentów zarządza tym, którzy agenci pozostają rezydentni, a współbieżność jest liczona według aktywnego wykonywania, a nie liczby utworzonych wątków, dzięki czemu bezczynni agenci nie zajmują już dostępnych miejsc.⁶¹ Dojrzał również cykl życia API — nazwę close_agent zmieniono na interrupt_agent (v0.139.0), aby odzwierciedlić fakt, że operacja przerywa działającego agenta, a nie tylko zamyka uchwyt — natomiast ostrzeżenia uruchomieniowe MCP zgłoszone przez subagent pozostają teraz ograniczone do wątku właściciela, zamiast powielać się w transkrypcji rodzica.⁶¹ Dla osób tworzących orkiestrację po stronie Codex właśnie te elementy wyznaczają granicę między demonstracją a flotą: szyfrowany transport wiadomości, ograniczona rezydentność, współbieżność liczona według wykonywanych zadań i ostrzeżenia, które nie przenikają przez granice wątków. Codex v0.140.0 otworzył następnie punkt integracji między narzędziami: /import selektywnie pobiera konfigurację początkową, konfigurację projektu i ostatnie czaty z Claude Code do Codex, a sesje można odtąd trwale usuwać (codex delete / /delete, z zabezpieczeniami wymagającymi potwierdzenia).⁶⁴ /import jest pierwszym oficjalnym potwierdzeniem, że operatorzy przechodzą między harnessami — konfiguracja przygotowana dla jednego z nich nie pozostaje już w nim uwięziona.

Pamięć i kontekst

Każda rozmowa z AI odbywa się w ramach ograniczonego okna kontekstowego. W miarę rozwoju rozmowy system kompresuje wcześniejsze wypowiedzi, aby zrobić miejsce na nowe treści. Kompresja jest stratna. Decyzje architektoniczne udokumentowane w 3. turze mogą nie przetrwać do 15. tury.⁹

Trzy mechanizmy załamania w rozmowach wieloturowych

W badaniu MSR/Salesforce zidentyfikowano trzy niezależne mechanizmy, z których każdy wymaga innego działania:⁹

Strategia 1: system plików jako pamięć

Najbardziej niezawodna pamięć przekraczająca granice kontekstu znajduje się w systemie plików. Claude Code odczytuje CLAUDE.md oraz pliki pamięci na początku każdej sesji i 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 z wielu sesji. Po odkryciu, że ((VAR++)) nie działa z set -e w bashu, gdy VAR wynosi 0, należy to zapisać. Trzy sesje później, przy podobnym przypadku brzegowym dotyczącym liczby całkowitej w Python, wpis w MEMORY.md przypomni 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. Na początku sesji Auto Memory wczytuje pierwszych 200 wierszy do promptu systemowego. Plik powinien być zwięzły, a szczegółowe notatki należy umieszczać w osobnych plikach tematycznych i dodawać do nich odnośniki.⁶ Od wersji v2.1.210 zapis do MEMORY.md, który przekracza limit rozmiaru, kończy się błędem zamiast cichego obcięcia zawartości⁶⁹ — problem ujawnia się podczas zapisu, a nie później w postaci wpisów pamięci, które niepostrzeżenie zniknęły. Jeśli harness automatyzuje zapisywanie pamięci, należy obsłużyć ten błąd; platforma sygnalizuje w ten sposób konieczność uporządkowania pliku, a nie ponowienia operacji.

Porządkowanie pamięci zamiast zwiększania jej objętości (maj 2026): Niedawny preprint w arXiv dotyczący współpracy agentów LLM przedstawia rozszerzone przywoływanie informacji jako potencjalny mechanizm awarii: w eksperymentach autorów dłuższa widoczna historia pogorszyła współpracę w 18 z 28 konfiguracji gier z udziałem modeli.⁴⁸ Należy potraktować to jako ostrzeżenie projektowe, a nie ostatecznie potwierdzoną regułę. Zasada dotycząca środowiska produkcyjnego jest już dostatecznie jasna: MEMORY.md powinien być krótki, szczegóły należy umieszczać w osobnych plikach i dodawać do nich odnośniki, a w przekazaniach umieszczać podsumowania gotowe do wykorzystania przy podejmowaniu decyzji. Surowe zrzuty transkrypcji, logi narzędzi i obszerne strumienie przywoływanych informacji powinny trafiać do przeszukiwalnego magazynu, a nie automatycznie do aktywnego promptu.

Strategia 2: proaktywna kompresja

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

Kiedy przeprowadzać kompresję: - Po ukończeniu odrębnego podzadania (wdrożeniu funkcji, naprawieniu błędu) - Przed rozpoczęciem pracy nad nowym obszarem bazy kodu - Gdy Claude zaczyna się powtarzać 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ę, natomiast polecenie /cd (Claude Code v2.1.169) chroni pamięć podręczną promptu. Umożliwia przeniesienie trwającej sesji do nowego katalogu roboczego bez naruszania pamięci podręcznej zgromadzonej w toku rozmowy.⁶⁰ Wcześniej zmiana katalogu oznaczała rozpoczęcie nowej sesji z pustą pamięcią podręczną. W długiej sesji, która przenosi się z jednego repozytorium do sąsiedniego — co często zdarza się podczas pracy z monorepozytoriami i wieloma usługami — /cd zachowuje kosztowny prefiks w pamięci podręcznej, jednocześnie wskazując nowy kontekst systemu plików.

Strategia 3: przekazywanie sesji

W przypadku zadań obejmujących wiele sesji należy tworzyć dokumenty przekazania zawierające 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 (kontynuacja) lub odczytanie dokumentu przekazania pozwala od razu przejść do implementacji.¹⁵

Strategia 4: iteracje ze świeżym kontekstem (Ralph loop)

W przypadku sesji trwających dłużej niż 60–90 minut należy dla każdej iteracji uruchamiać nową instancję Claude. Stan jest utrwalany w systemie plików, a nie w pamięci rozmowy. Każda iteracja otrzymuje pełny budżet kontekstu:¹⁶

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

Dla porównania — pojedyncza długa sesja:

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

Podejście polegające na użyciu świeżego kontekstu w każdej iteracji wiąże się z narzutem rzędu 15–20% na etap orientacji (odczytywanie plików stanu i przeglądanie historii git), ale zapewnia pełne zasoby poznawcze w każdej iteracji.¹⁶ Rachunek kosztów i korzyści wygląda następująco: w przypadku sesji krótszych niż 60 minut wydajniejsza jest pojedyncza rozmowa. Po przekroczeniu 90 minut świeży kontekst zapewnia lepszą jakość wyników mimo dodatkowego narzutu.

Strategia 5: zarządzane porządkowanie pamięci (Dreaming)

W Managed Agents firmy Anthropic dodano funkcję Dreaming jako Research Preview 6 maja 2026.³⁵ Według Anthropic: „Dreaming to zaplanowany proces, który przegląda sesje agentów i magazyny pamięci, wyodrębnia wzorce oraz porządkuje wspomnienia, dzięki czemu agenci z czasem działają coraz lepiej”.³⁵

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 kluczową warstwą, natomiast Dreaming zapisuje uporządkowane wpisy w magazynie pamięci Managed Agents, który agent odczytuje na początku sesji. Oba wzorce współistnieją w harnesses łączących samodzielnie hostowany stan w systemie plików z porządkowaniem pamięci po stronie usługi zarządzanej.

Dreaming znajduje się w fazie Research Preview, dlatego jego działanie może ulec zmianie. Opisane powyżej wzorce przekazywania sesji i CLAUDE.md pozostają nadrzędnym mechanizmem pamięci dla samodzielnie hostowanych harnesses.

Antywzorce

Odczytywanie całych plików, gdy potrzeba 10 wierszy. Jednorazowe odczytanie pliku zawierają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.¹⁵

Pozostawianie w kontekście obszernych komunikatów o błędach. Po usunięciu błędu kontekst może nadal zawierać ponad 40 śladów stosu z nieudanych iteracji. Jedno użycie /compact po naprawieniu błędu uwalnia kontekst od tego zbędnego obciążenia.

Rozpoczynanie każdej sesji od odczytania wszystkich plików. Warto pozwolić narzędziom glob i grep w Claude Code wyszukiwać 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. Rozpoczynają pracę z czystym kontekstem (bez zanieczyszczeń z głównej rozmowy), korzystają z określonych narzędzi i zwracają wyniki w formie podsumowań. Rezultaty eksploracji nie rozbudowują 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 subagent

Izolacja worktree

Subagents mogą działać w tymczasowych git worktrees, które zapewniają pełną, 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 przy pracach 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łówną kopię roboczą — czyli powodować dokładnie tę awarię, której ten mechanizm ma zapobiegać.⁶⁹ Jeśli isolation: worktree stanowi granicę bezpieczeństwa, a nie tylko udogodnienie, należy uznać wersję v2.1.210 za minimalną. Towarzysząca temu zmiana uprawnień działa jednak w przeciwnym kierunku: od wersji v2.1.211 reguły „always allow” są zachowywane w katalogu głównym repozytorium pomiędzy worktrees, więc reguła zaakceptowana w jednym worktree obowiązuje także w sąsiednich worktrees tego samego repozytorium.⁶⁹ To odpowiednia ergonomia dla agentów pracujących równolegle w worktrees, oznacza jednak, że zezwolenie udzielone podczas jednorazowego eksperymentu zachowuje ważność po jego zakończeniu — należy udzielać go z myślą o całym repozytorium, a nie tylko o aktualnie używanym worktree.

Wersja v2.1.216 dokończyła tę pracę, przenosząc izolację worktree z poziomu naprawy błędu na poziom rygorystycznego egzekwowania.⁷⁴ Poprawka z wersji v2.1.210 uniemożliwiła subagents w odizolowanych worktrees modyfikowanie głównej kopii roboczej poprzez zwykłe wywołanie git, ale sam git udostępnia jawne mechanizmy przekierowania — git -C <path>, --git-dir oraz zmienne środowiskowe GIT_DIR/GIT_WORK_TREE — a odizolowany subagent nadal mógł skierować dowolny z nich do współdzielonej kopii roboczej. Wszystkie te drogi obejścia zostały teraz zamknięte. W tym samym wydaniu naprawiono również sporadyczne uruchamianie sesji worktree w pozostałości po worktree należącym do innego projektu, uniemożliwiono zapisom z workflow i zaplanowanych zadań podążanie za dowiązaniem symbolicznym umieszczonym w .claude i prowadzącym poza projekt oraz sprawiono, że /rewind odmawia przechodzenia przez dowiązania symboliczne i twarde. Wzorzec we wszystkich czterech poprawkach jest taki sam: granica izolacji musi wytrzymać celowe przekierowanie — nadpisanie środowiska git czy umieszczenie dowiązania symbolicznego — a nie tylko zachowanie domyślne. Jeśli isolation: worktree stanowi w harness granicę bezpieczeństwa, a nie udogodnienie, nową wersją minimalną jest v2.1.216.

Równoległe subagents

Równoległych subagents należy 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 z kolei delegują je następnym agentom, a każdy kolejny traci część kontekstu i zużywa tokeny. Wzorzec recursion guard narzuca budżety:¹⁶

#!/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"

Najważniejszy wniosek: należy stosować budżety uruchomień, a nie wyłącznie limity głębokości. Limity oparte na głębokości śledzą łańcuchy rodzic–dziecko (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 dzieci każdego rodzica i ogranicza ją konfigurowalnym maksimum. Model budżetowy odpowiada rzeczywistemu trybowi awarii (zbyt wielu agentów łącznie), a nie wskaźnikowi zastępczemu (zbyt wiele poziomów zagnieżdżenia).⁷

Domyślna głębokość zagnieżdżenia zmieniała się już trzykrotnie — nie należy na niej opierać architektury. Claude Code v2.1.172 (10 czerwca 2026) umożliwił sub-agents uruchamianie własnych sub-agents, z zagnieżdżeniem do 5 poziomów — wcześniej delegowanie było w praktyce ograniczone do jednego poziomu.⁶² Tak było od wersji v2.1.172 do v2.1.216. Wersja v2.1.217 (21 lipca 2026) ograniczyła głębokość do 1, domyślnie wyłączając zagnieżdżone uruchamianie. Następnie wersja 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); aby wyłączyć zagnieżdżanie, należy ustawić CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1”.⁸⁴ Najpierw pięć, potem jeden, następnie trzy — przy czym dwie ostatnie zmiany nastąpiły w ciągu trzech dni.

Wniosek nie polega na tym, że którakolwiek z tych liczb jest właściwa. Platforma nadal poszukuje odpowiedniej wartości domyślnej, dlatego harness nie powinien dziedziczyć po prostu „tego, co akurat dostarczono”. Głębokość zagnieżdżenia należy traktować jako jawną pozycję budżetową: ustawić CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH na głębokość faktycznie potrzebną w danej architekturze — w większości systemów orkiestracji będzie to 1 lub 2 — aby aktualizacja nie mogła po cichu zmienić głębokości delegowania w całej flocie. Niezależnie od tych zmian podstawowy argument pozostaje ten 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ć. To właśnie powyższy recursion guard zapobiega rozgałęzieniu głębokiego drzewa w setki aktywnych agentów, niezależnie od kierunku kolejnej zmiany wartości domyślnej. Tylko samodzielnie ustawiony limit głębokości po następnym wydaniu nadal oznacza to, czego można się po nim spodziewać.

Auto mode ocenia teraz uruchomienia przed ich rozpoczęciem. W Claude Code v2.1.178 usunięto powiązaną lukę w nadzorze: w auto mode uruchomienia subagent są oceniane przez klasyfikator uprawnień przed uruchomieniem subagent, a nie dopiero wtedy, gdy zacznie wykonywać działania.⁶³ Wcześniej można było uruchomić subagent w celu zażądania działania, którego sesja nadrzędna nie mogłaby wykonać — samo uruchomienie stanowiło obejście zabezpieczeń. Ocena podczas uruchamiania sprawia, że recursion guard i model uprawnień wreszcie się spotykają: dziecko nie może służyć do „wyprania” działania zabronionego przez zasady.

Platforma udostępnia teraz natywny budżet uruchomień. W Claude Code v2.1.212 (lipiec 2026) dodano wbudowane zabezpieczenia przed niekontrolowanymi pętlami: domyślny limit wynosi 200 uruchomień subagent na sesję (można go dostosować za pomocą CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION, a /clear zeruje licznik), natomiast WebSearch ograniczono do 200 wywołań na sesję (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ Wzorzec budżetu uruchomień, dokumentowany w tej sekcji od wersji v1.0 jako skrypt tworzony przez użytkownika, jest teraz zapewniany przez platformę — potwierdza to przewagę modelu budżetowego nad modelem głębokości. Trzeba 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 są bezpiecznikami chroniącymi przed rzeczywiście niekontrolowaną pętlą, a nie budżetami dostrojonymi do konkretnej architektury. Warto zachować własny guard dla budżetów poszczególnych rodziców, śledzenia głębokości i limitów odpowiadających faktycznym założeniom orkiestracji; limit platformy powinien przechwytywać wszystko, co zdoła go ominąć.

Zestaw wbudowanych zabezpieczeń obejmuje teraz cztery osie. Trzy z nich chronią dokładnie te aspekty, które śledzi własny guard opisany w tej sekcji: łą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, przy czym wartość ta jest wyraźnie niestabilna) oraz współbieżne wykonywanie (v2.1.217, domyślnie 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS — pojedyncza wiadomość nie może już uruchomić nieograniczonej liczby agentów w tle).⁷⁸⁸⁴ Wersja v2.1.219 dodaje czwartą oś, której własne guard zwykle nie obejmowały: szerokość orkiestracji, czyli liczbę agentów dopuszczalnych w pojedynczym zaplanowanym workflow. Udostępniono ją jako domyślną wytyczną „dążyć do mniej niż 15 agentów”, konfigurowaną z dowolnego pliku ustawień za pomocą workflowSizeGuideline (omówione w sekcji Workflow Tool poniżej). Wzorzec budżetu uruchomień ma teraz zabezpieczenie na każdej osi, dla której został zaprojektowany, oraz na jednej dodatkowej.

Uwaga dotycząca kalibracji nadal obowiązuje, choć nie w jednakowym stopniu. 200 uruchomień i 20 współbieżnych agentów to bezpieczniki — wartości o rząd wielkości większe od budżetu 12 agentów dla deliberation z powyższej konfiguracji, dobrane tak, by zatrzymać niekontrolowaną pętlę, a nie kształtować architekturę. Wytyczna szerokości jest pierwszą natywną wartością utrzymaną na poziomie rzeczywistego budżetu: 15 agentów na workflow jest bardzo bliskie wartości 12 przyjętej w tym przewodniku. Zastosowanie ustawienia domyślnego platformy nic nie kosztuje, a odstępstwo od niego powinno wynikać z konkretnego powodu. Trzy 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ę za pomocą współdzielonej skrzynki pocztowej i listy 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)

W Claude Code v2.1.139 dodano Agent View — interfejs w wersji research-preview, uruchamiany poleceniem claude agents, który na jednym ekranie pokazuje uruchomione, zablokowane i zakończone sesje Claude Code.⁴²⁴³ Oficjalna dokumentacja przedstawia go jako sposób na uruchamianie wielu sesji i zarządzanie nimi, sprawdzanie działań poszczególnych sesji oraz identyfikowanie tych, które wymagają interwencji operatora.⁴³ Dzięki temu praca wielu agentów zyskuje widok operacyjny, którego nie zapewniają podsumowania końcowe.

Podczas wdrażania wzorca subagent lub zespołu warto użyć Agent View, aby sprawdzić, które sesje są zablokowane, które nadal działają oraz czy podział pracy odpowiada zamierzonej architekturze. Nie należy jednak traktować tego jako dowodu jakości. To obserwowalność; o poprawności pracy nadal rozstrzygają testy, bramki przeglądu i raporty dowodowe.

W tym samym wydaniu dodano /goal, które ustawia warunek ukończenia i pozwala Claude kontynuować pracę przez wiele tur aż do jego spełnienia, także w trybie interaktywnym, -p oraz Remote Control.⁴² /goal należy traktować jako pętlę ukończenia ograniczoną do sesji, a nie zamiennik deterministycznych bramek. Pomaga utrzymać koncentrację agenta na celu, jednak tam, gdzie niepowodzenie musi blokować dalszą pracę, testy, kontrole cytowań, kontrole wdrożenia i security hooks powinny nadal opierać się na poleceniach lub skryptach.

Workflow Tool (v2.1.147+)

Claude Code v2.1.147 dodaje domyślnie wyłączone narzędzie Workflow do deterministycznej orkiestracji wielu agentów. Można je włączyć za pomocą CLAUDE_CODE_WORKFLOWS=1.⁵² Z perspektywy architektury jest to istotne, ponieważ Claude Code zyskuje wbudowany mechanizm orkiestracji przepływów, które wcześniej wymagały niestandardowych skryptów dispatch, stanu skrzynki pocztowej i konwencji koordynacji subagent.

Nie należy usuwać otaczającego go harness. Workflow może uporządkować wykonanie, lecz nie zastępuje modelu bezpieczeństwa. Należy zachować hooks PreToolUse i PostToolUse jako warstwę blokującą, budżety uruchomień lub budżety kroków workflow zapobiegające niekontrolowanemu wzrostowi szerokości, audytowalny stan systemu plików oraz końcowe raporty dowodowe niezależne od samooceny modelu. W praktyce: Workflow służy do określania kształtu orkiestracji, natomiast hooks, testy i bramki przeglądu — do ustalania prawdy.

Dynamiczne workflows mają teraz wbudowaną opinię o szerokości (v2.1.219). Dynamiczne workflows domyślnie korzystają z wytycznej średniego rozmiaru — „dążyć do mniej niż 15 agentów” — a inne rozmiary oraz opcja bez ograniczeń są dostępne w sekcji Dynamic workflow size w /config. Bieżąca wytyczna jest również wyświetlana w wierszu stanu działającego workflow.⁸⁴ Jest to zalecenie, nie twardy limit; ukierunkowuje planner, zamiast blokować szeroki plan. Warto je skonfigurować ze względu na sposób dystrybucji: nowy klucz ustawień workflowSizeGuideline można określić w dowolnym pliku ustawień — także w ustawieniach zarządzanych i projektowych — a od wersji v0.3.219 znajduje się on w typach ustawień TypeScript SDK. Dzięki temu szerokość orkiestracji może zostać ustandaryzowana na poziomie zespołu lub organizacji, zamiast być każdorazowo odkrywana przez operatorów.⁸⁵ Warto ustawić ją na poziomie projektu, aby zakodować sposób, w jaki prace w danej bazie kodu faktycznie dzielą się na części. Dwie uwagi dla operatora: wiersz w /config ukrywa się, gdy wartość pochodzi z pliku ustawień — to prawidłowe zachowanie, choć bez znajomości przyczyny może wyglądać jak brak ustawienia; ponadto, ponieważ wytyczna kieruje planner, a nie blokuje wykonanie, należy do kolumny kształtu, a nie bezpieczeństwa. Za niekontrolowaną szerokość nadal odpowiada limit uruchomień.

Warto zachować następującą perspektywę: jest to czwarta oś wbudowanych zabezpieczeń — szerokość orkiestracji, obok liczby uruchomień, głębokości zagnieżdżenia i współbieżnego wykonywania — a zarazem pierwsza, którą Anthropic skalibrował do wiarygodnego rozmiaru roboczego, nie zaś jako bezpiecznik na wypadek niekontrolowanej sytuacji. Piętnaście agentów na workflow to ten sam rząd wielkości co budżet 12 agentów dla deliberation, stosowany w tym przewodniku od wersji v1.0. Gdy ustawienie domyślne platformy i własny budżet zbiegają się z przeciwnych kierunków, stanowi to najbliższy odpowiednik niezależnego potwierdzenia, jaki można uzyskać dla takich liczb.

Rozgałęzianie 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 ścieżka działa niezależnie, podczas gdy pierwotna kontynuuje pracę — a poprzednie zachowanie wewnątrz sesji otrzymało nazwę /subtask. To rozróżnienie ma znaczenie dla projektowania orkiestracji: /subtask jest ograniczonym zakresem odejściem od głównego toku w ramach cyklu życia jednej sesji; /fork to niedrogi sposób tworzenia równoległej sesji w tle, która dziedziczy pełny kontekst i przypomina bardziej uruchomienie pętli Ralph niż subagent. Jeśli skrypty harness zakładały, że /fork pozostaje w obrębie sesji, obecnie wysyłają pracę do tła.

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

Do bezobsługowej orkiestracji w wersji v2.1.211 dodano --forward-subagent-text (zmienna środowiskowa: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT), które przekazuje tekst odpowiedzi subagent do wyjścia stream-json.⁶⁹ Proces koordynujący, który odbiera strumień sesji nadrzędnej, może teraz bezpośrednio obserwować postępy subagent, zamiast odpytywać transkrypcje lub czekać na końcowe podsumowanie — to obserwowalność uzupełniająca domyślne działanie subagents w tle. 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 uruchamiającego je Agent.⁸⁴ To właśnie na tym kluczu należy oprzeć implementację. Gdy zagnieżdżanie jest ponownie domyślnie włączone, płaski strumień tekstu subagent staje się niejednoznaczny — identyfikator wskazuje koordynatorowi, który rodzic utworzył dane dziecko, dzięki czemu drzewo delegowania można odtworzyć ze strumienia, zamiast próbować je wywnioskować. Jeśli konsument strumienia został napisany z myślą o jednym poziomie subagents, zobaczy teraz tekst pochodzący od agentów, o których istnieniu wcześniej nie wiedział; dane należy grupować według identyfikatora tool_use uruchamiającego agenta, zamiast zakładać, że każdy przekazany wiersz należy do bezpośredniego dziecka.

Orkiestracja wieloagentowa

Jednoagentowe systemy AI mają strukturalny martwy punkt: nie potrafią kwestionować własnych założeń.⁷ Wieloagentowa deliberacja wymusza niezależną ocenę z wielu perspektyw, zanim jakakolwiek decyzja zostanie zablokowana.

Orkiestracja międzynarzędziowa (kwiecień 2026): Google udostępnił Scion jako oprogramowanie open source 7 kwietnia — to wieloagentowy hipernadzorca uruchamiający Claude Code, Gemini CLI oraz inne „głębokie agenty” jako równoległe procesy, każdy z izolowanym kontenerem, git worktree i poświadczeniami. Działa lokalnie, w hubie lub na Kubernetes. Wyraźna filozofia: „izolacja zamiast ograniczeń” — agenty działają z wysoką autonomią w obrębie granic egzekwowanych na warstwie infrastruktury, a nie w promptach.²⁵ Rozszerza to bezpośrednio argument o izolacji subagentów na różnych dostawców narzędzi. Jeśli przepływ pracy obejmuje Claude oraz modele OpenAI, Scion jest pierwszą realną referencyjną implementacją międzynarzędziowych subagentów z izolacją worktree i poświadczeń per-agent.

Debata nie jest cudownym lekiem: Klaster badawczy M3MAD-Bench (początek 2026) ustalił, że wieloagentowa debata osiąga plateau i może być podważana przez mylący konsensus — trafne argumenty przegrywają, gdy inne agenty z pewnością siebie twierdzą coś błędnego.²⁶ Tool-MAD poprawia to, dając każdemu agentowi heterogeniczny dostęp do narzędzi i stosując oceny Faithfulness/Relevance na etapie sędziowskim. Przy budowie orkiestracji w stylu debaty warto zainwestować w (a) heterogeniczność narzędzi per agent oraz (b) ilościową punktację sędziowską, zamiast zakładać, że więcej agentów = lepsze odpowiedzi.

Zarządzana orkiestracja wieloagentowa i Outcomes (Public Beta)

Jeśli nie chce się budować infrastruktury deliberacji opisanej poniżej, Multiagent Orchestration weszła w fazę Public Beta w Claude Managed Agents 6 maja 2026.³⁵ Według Anthropic: „Gdy pojedynczy agent ma zbyt dużo pracy do wykonania na wysokim poziomie, orkiestracja wieloagentowa pozwala wiodącemu agentowi podzielić zadanie na części i delegować każdą z nich do specjalisty z własnym modelem, promptem i narzędziami.”³⁵ Specjaliści „pracują równolegle na współdzielonym systemie plików i wnoszą wkład do ogólnego kontekstu wiodącego agenta.”³⁵

Śledzenie jest wbudowane. Według Anthropic: „można również prześledzić każdy krok w Claude Console: który agent co zrobił, w jakiej kolejności i dlaczego, co daje pełną widoczność tego, w jaki sposób zadanie zostało zdelegowane i wykonane.”³⁵

Towarzyszącą funkcją Public Beta jest Outcomes. Według Anthropic: „pisze się rubrykę opisującą, jak wygląda sukces, a agent pracuje nad jej spełnieniem. Oddzielny oceniający (grader) ewaluuje wynik względem podanych kryteriów we własnym oknie kontekstowym, dzięki czemu nie jest pod wpływem rozumowania agenta.”³⁵ To wersja zarządzana usługą wzorca walidacji dwubramkowej udokumentowanego w dalszej części tego rozdziału: rubryka zastępuje ręcznie napisaną bramkę, a oddzielny grader zastępuje walidator konsensusu.

Samodzielnie hostowana deliberacja pozostaje właściwą odpowiedzią, gdy walidacja musi integrować się z własną powierzchnią hooków (blokowanie PreToolUse, semantyka kodu wyjścia, niestandardowe dispatchery) lub gdy harness musi działać bez zewnętrznych zależności. Managed Multiagent jest właściwą odpowiedzią, gdy standardowe delegowanie plus ocenianie według rubryki to faktycznie potrzebny kontrakt.

Minimalna sensowna deliberacja

Należy zacząć od 2 agentów i 1 reguły: agenty muszą oceniać niezależnie, zanim zobaczą wzajemną pracę.⁷

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 pokrywa 80% wartości. Wszystko inne dodaje stopniową poprawę.

Wyzwalacz pewności

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

1. Niejednoznaczność — Czy zapytanie ma wiele prawidłowych interpretacji?
2. Złożoność dziedziny — Czy wymaga wyspecjalizowanej wiedzy?
3. Stawka — Czy decyzja jest odwracalna?
4. Zależność kontekstowa — Czy wymaga zrozumienia szerszego systemu?

Wynik mapuje się na trzy poziomy:

Próg dostosowuje się do typu zadania. Decyzje dotyczące bezpieczeństwa wymagają konsensusu 0,85. Zmiany w dokumentacji potrzebują jedynie 0,50. Zapobiega to nadmiernemu rozbudowywaniu prostych zadań, jednocześnie zapewniając, że ryzykowne decyzje zostaną dokładnie przeanalizowane.⁷

Maszyna stanów

Siedem faz, każda otwierana 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 agenty nie mogą widzieć wzajemnych ustaleń podczas badania.

DELIBERATION: Agenty widzą wszystkie ustalenia z badań i generują alternatywy. Agent Debate identyfikuje konflikty. Agent Synthesis łączy niesprzeczne ustalenia.

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

Architektura walidacji dwubramkowej

Dwie bramki walidacyjne wychwytują problemy na różnych etapach:⁷

Bramka 1: Walidacja konsensusu (hook PostToolUse). Uruchamia się natychmiast po zakończeniu pracy każdego agenta deliberacji: 1. Faza musi osiągnąć co najmniej RANKING 2. Minimum 2 agenty zakończyły pracę (konfigurowalne) 3. Wynik konsensusu spełnia próg adaptacyjny dla zadania 4. Jeśli jakikolwiek agent zgłosił sprzeciw, obawy muszą być udokumentowane

Bramka 2: Pride Check (hook Stop). Uruchamia się przed zamknięciem sesji: 1. Zróżnicowane metody: reprezentowanych jest wiele unikalnych person 2. Przejrzystość sprzeczności: sprzeciwy mają udokumentowane powody 3. Obsługa złożoności: wygenerowano co najmniej 2 alternatywy 4. Pewność konsensusu: sklasyfikowana jako silna (powyżej 0,85) lub umiarkowana (0,70–0,84) 5. Dowody poprawy: końcowa pewność przewyższa pewność początkową

Dwa hooki w różnych punktach cyklu życia odpowiadają temu, jak rzeczywiście pojawiają się awarie: niektóre są natychmiastowe (zły wynik), a niektóre stopniowe (niska różnorodność, brak dokumentacji sprzeciwu).⁷

Dlaczego zgoda jest niebezpieczna

Charlan Nemeth badała sprzeciw mniejszości od 1986 roku aż po jej książkę z 2018 r. In Defense of Troublemakers. Grupy z dysydentami podejmują lepsze decyzje niż grupy szybko osiągające zgodę. Dysydent nie musi mieć racji. Sam akt sprzeciwu zmusza większość do zbadania założeń, które w innym przypadku zostałyby pominięte.¹⁸

Wu i in. zbadali, czy agenty LLM potrafią naprawdę debatować, i ustalili, że bez strukturalnych zachęt do nieporozumień agenty zbiegają się w kierunku najbardziej pewnie brzmiącej początkowej odpowiedzi, niezależnie od jej poprawności.¹⁹ Liang i in. zidentyfikowali źródłową przyczynę jako „Degeneration-of-Thought”: gdy LLM ustabilizuje pewność siebie w danej pozycji, autorefleksja nie potrafi wygenerować nowych kontrargumentów, co czyni wieloagentową ewaluację strukturalnie niezbędną.²⁰

Niezależność jest krytycznym ograniczeniem projektowym. Dwa agenty oceniające tę samą strategię wdrożenia z widocznością wzajemnych ustaleń wygenerowały wyniki 0,45 i 0,48. Te same agenty bez widoczności: 0,45 i 0,72. Różnica między 0,48 a 0,72 to koszt zachowań stadnych.⁷

Wykrywanie fałszywej zgody

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

Klastrowanie wyników: Każdy agent oceniający w przedziale 0,3 punktu w 10-stopniowej skali sygnalizuje skażenie wspólnym kontekstem, a nie niezależną ocenę. Gdy pięć agentów oceniających refaktoryzację uwierzytelniania ocenia ryzyko bezpieczeństwa w przedziale od 7,1 do 7,4, ponowne uruchomienie ze świeżą izolacją kontekstu rozłożyło wyniki na 5,8–8,9.

Szablonowy sprzeciw: Agenty kopiujące wzajemnie język obaw, zamiast generować 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 (mniej więcej 10–15% deliberacji, w których agenty zbiegają się zbyt szybko). Dla pozostałych 85–90% bramki konsensusu i pride check zapewniają wystarczającą walidację.

Co nie zadziałało w deliberacji

Swobodne rundy debaty. Trzy rundy wymiany tekstu wokół dyskusji o indeksowaniu bazy danych wyprodukowały 7 500 tokenów debaty. Runda 1: prawdziwa różnica zdań. Runda 2: powtórzone pozycje. Runda 3: identyczne argumenty innymi słowami. Strukturyzowana punktacja wymiarów zastąpiła swobodną debatę, obniżając koszt o 60% przy jednoczesnej poprawie jakości rankingu.⁷

Pojedyncza bramka walidacji. Pierwsza implementacja uruchamiała jeden hook walidacyjny na końcu sesji. Agent zakończył deliberację z wynikiem konsensusu 0,52 (poniżej progu), a następnie kontynuował niezwiązane zadania przez 20 minut, zanim hook końca sesji oznaczył awarię. Podział na dwie bramki (jedna na zakończenie zadania, druga na koniec sesji) wychwytywał te same problemy w różnych punktach cyklu życia.⁷

Koszt deliberacji

Każdy agent badawczy przetwarza około 5 000 tokenów kontekstu i generuje 2 000–3 000 tokenów ustaleń. Przy 3 agentach to 15 000–24 000 dodatkowych tokenów na decyzję. Przy 10 agentach mniej więcej 50 000–80 000 tokenów.⁷

Przy obecnych cenach Opusa 3-agentowa deliberacja kosztuje około 0,68–0,90 USD. 10-agentowa deliberacja kosztuje 2,25–3,00 USD. System wyzwala deliberację mniej więcej w 10% decyzji, więc zamortyzowany koszt wszystkich decyzji wynosi 0,23–0,30 USD na sesję. To, czy warto, zależy od tego, ile kosztuje zła decyzja.

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ługotrwałych zadań w Opus 4.7 (kwiecień 2026)

Claude Opus 4.7 (16 kwietnia 2026) wprowadzono z konkretnymi możliwościami, które zmieniają zakres zabezpieczeń wymaganych od harness:²⁹

• Odporność na awarie narzędzi: Opus 4.7 kontynuuje pracę po awariach narzędzi, które zatrzymywały sesje Opus 4.6. Można ograniczyć — ale nie wyeliminować — defensywne mechanizmy ponawiania prób w kodzie subagents. Należy zachować zabezpieczenia na poziomie hooks, a ograniczyć zawarte w promptach instrukcje typu „jeśli narzędzie zawiedzie, spróbuj ponownie trzy razy”.
• Poziom nakładu xhigh (tylko Opus-4.7): Znajduje się między high a max. Jest zalecanym ustawieniem domyślnym dla zadań programistycznych i agentowych. W przypadku długotrwałych subagents poziom xhigh wyraźnie przewyższa high, przy mniej niż proporcjonalnym wzroście kosztu tokenów. max pozostaje właściwym wyborem do jednorazowego, złożonego wnioskowania; xhigh sprawdza się lepiej w długotrwałych zadaniach.
• 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 aktualizowane odliczanie i płynnie dostosowuje zakres pracy do budżetu, zamiast niespodziewanie go wyczerpać. Warto korzystać z tej funkcji w pętlach agentowych, gdy potrzebne jest przewidywalne zużycie tokenów bez obniżania jakości krótkich promptów.
• Rozpoznawanie niejawnych potrzeb: Pierwszy model Claude, który przeszedł testy „implicit-need” — rozpoznaje, kiedy dosłowna prośba użytkownika nie określa w pełni jego rzeczywistych potrzeb. Dzięki temu sekcja „clarifying rules” w CLAUDE.md staje się mniej potrzebna. Jeśli CLAUDE.md zawiera 200 wierszy zabezpieczeń w rodzaju „uwzględnij również X, gdy użytkownik poprosi o Y”, należy usunąć te, które model obsługuje już natywnie.

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

Claude Code v2.1.133 dodaje 4 ustawienia poziomu administracyjnego, które warto znać w przypadku produkcyjnych harnesses:³⁹

Wycofanie zmiany dotyczącej worktree.baseRef należy szczególnie wyraźnie zakomunikować użytkownikom: agenci polegający na zachowaniu z wersji v2.1.128–v2.1.132 (worktrees tworzące gałęzie na podstawie lokalnego HEAD) tracą dostęp do niewypchniętej pracy w nowych worktrees, chyba że ponownie włączą tę opcję.

Ankieta opinii OTel do obserwowalności w przedsiębiorstwach (8 maja 2026)

Claude Code v2.1.136 dodano CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL, aby ponownie włączyć ankietę jakości w sesji dla przedsiębiorstw przechwytujących odpowiedzi za pośrednictwem OpenTelemetry.⁴⁰ Jeśli organizacja przesyła 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 funkcję opcjonalną: domyślnie ankieta pozostaje wyłączona, co jest właściwe w przypadku wdrożeń bez OTel.

Korporacyjne programy uruchamiające i wydajność przy skali MCP (lipiec 2026)

Dwie zmiany w v2.1.207 mają znaczenie dla wdrożeń produkcyjnych.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER pozwala zarządzanym środowiskom uruchamiać proces Claude Code za pośrednictwem korporacyjnego pliku binarnego wrappera — punktu integracji dla agentów punktów końcowych, kontroli zasad podczas uruchamiania oraz środowisk, w których każdy proces musi działać pod nadzorem obowiązkowego supervisora. Jeśli wcześniej przedsiębiorstwo imitowało takie rozwiązanie za pomocą aliasów powłoki lub rozwidlonych skryptów uruchamiających, jest to obecnie oficjalnie obsługiwany punkt integracji.

To samo wydanie ograniczyło narzut środowiska uruchomieniowego tam, gdzie harnesses odczuwają go najmocniej: rundy użycia narzędzi są nawet 7× szybsze w sesjach z dużą liczbą narzędzi MCP, a transkrypcje sesji są 79× mniejsze.⁶⁸ Łagodzi to — choć nie odwraca — zalecenia przedstawione w sekcji Koszt jako architektura: podejście oparte najpierw na CLI nadal wygrywa w bezstanowych, jednorazowych operacjach, lecz harness zawierający dziesiątki narzędzi MCP nie ponosi już takiego narzutu na rundę jak wiosną, a przechowywanie transkrypcji przestaje być ukrytym kosztem długotrwałych autonomicznych uruchomień.

Quality loop

Obowiązkowy proces przeglądu wszystkich nietrywialnych zmian:

1. Implementacja — napisanie kodu
2. Przegląd — ponowne przeczytanie każdego wiersza. Wychwycenie 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. Dopracowanie — naprawienie każdego problemu. Bez odkładania czegokolwiek „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. Raport — wyszczególnienie zmian i sposobu ich weryfikacji wraz z przytoczeniem konkretnych dowodów

Evidence gate

„Uważam” i „powinno” nie są dowodami. Należy wskazać ścieżki plików, wyniki testów lub konkretny kod.

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

Uprawnienia człowieka do scalania

Badanie arXiv z maja 2026, obejmujące cykle życia 29 585 pull requestów agentów AI, oddziela autonomię operacyjną od nadzoru nad scalaniem.⁴⁷ Wniosek architektoniczny jest prosty: agenci mogą rozpoczynać pracę, rozwijać gałęzie, otwierać PR-y, przeprowadzać przeglądy i podsumowywać ryzyko, natomiast uprawnienia do scalania pozostają odrębną granicą nadzoru.

Granica ta powinna być jawnie określona w harness. Agenci mogą przygotowywać PR-y i gromadzić dowody; scalenia, wydania i destrukcyjne operacje na repozytorium powinny wymagać zatwierdzenia przez człowieka, chyba że organizacja dysponuje osobno audytowaną polityką automatyzacji. Gdy scalenie wykonuje automatyzacja, należy zachować logi rozróżniające wykonawcę od człowieka lub zasady, które je autoryzowały.

Wzorce obsługi błędów

Atomowe zapisy plików. Jednoczesny zapis wielu agentów do tego samego pliku stanu powoduje uszkodzenie JSON. Należy zapisywać dane do plików .tmp, a następnie atomowo wykonywać mv. System operacyjny gwarantuje atomowość operacji mv 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 ulegnie uszkodzeniu, 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 ((VAR++)) w bash. ((VAR++)) zwraca kod wyjścia 1, gdy VAR ma wartość 0, ponieważ wynikiem 0++ jest 0, co bash interpretuje jako fałsz. Przy włączonym set -e powoduje to zakończenie skryptu. Zamiast tego należy użyć VAR=$((VAR + 1)).¹⁶

Klasyfikacja blast radius

Każde działanie agenta należy sklasyfikować według blast radius i odpowiednio zabezpieczyć:²

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

Specyfikacja zadań dla autonomicznych uruchomień

Skuteczne zadania autonomiczne obejmują 3 elementy: cel, kryteria ukończenia i odnośniki do 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 lub niepowodzenie testów, wynik lintera, kody stanu HTTP, sprawdzenie istnienia plików. W jednym z pierwszych zadań poproszono agenta o „napisanie testów, które przechodzą”, co poskutkowało assert True i assert 1 == 1. Technicznie poprawne. W praktyce bezwartościowe.¹⁶

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

Konkretny przebieg sesji

Przebieg autonomicznej sesji przetwarzającej PRD z 5 historyjkami:²

1. Uruchamia się SessionStart. Dispatcher wstrzykuje: bieżącą datę, wykrywanie projektu, ograniczenia wynikające z przyjętej filozofii oraz inicjalizację śledzenia kosztów. 5 hooks, łącznie 180 ms.

2. Agent odczytuje PRD i planuje pierwszą historyjkę. Uruchamia się UserPromptSubmit. Dispatcher wstrzykuje: kontekst aktywnego projektu i wartość bazową dryfu sesji.

3. Agent wywołuje Bash, aby uruchomić testy. Uruchamia się PreToolUse:Bash. Kontrola danych uwierzytelniających, walidacja sandbox i wykrywanie projektu. 90 ms. Testy zostają uruchomione. Uruchamia się PostToolUse:Bash: rejestrowany jest sygnał aktywności i wykonywana jest kontrola dryfu.

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

5. Agent kończy historyjkę. Uruchamia się Stop. Quality gate sprawdza: czy agent przytoczył dowody? Czy użył języka asekuracyjnego? Czy w diff znajdują się komentarze TODO? Jeśli którakolwiek kontrola zakończy się niepowodzeniem, zwracany jest kod wyjścia 2, a agent kontynuuje pracę.

6. Niezależna weryfikacja: Nowy agent uruchamia zestaw testów, nie polegając na deklaracji poprzedniego agenta.

7. 3 agentów przeglądających kod uruchamia się równolegle. Każdy niezależnie sprawdza diff. Jeśli którykolwiek recenzent oznaczy problem jako CRITICAL, historyjka wraca do kolejki.

8. Historyjka przechodzi weryfikację. Wczytywana jest następna. Cykl powtarza się dla wszystkich 5 historyjek.

Łączna liczba hooks uruchomionych dla 5 historyjek: około 340. Łączny czas działania hooks: około 12 sekund. Ten narzut zapobiegł 3 wyciekom danych uwierzytelniających, 1 destrukcyjnemu poleceniu i 2 niekompletnym implementacjom podczas jednego nocnego uruchomienia.

Studium przypadku: nocne przetwarzanie PRD

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

Dwa wycieki danych uwierzytelniających wymagały rotacji kluczy API i audytu usług zależnych, co oznaczało około 4 godzin reagowania na incydenty. Narzut harness, który zapobiegł podobnym zdarzeniom, wynosił 2,4 sekundy działania bash na historyjkę. Wskaźnik fałszywego ukończenia spadł z 35% do 4%, ponieważ Stop hook niezależnie uruchamiał testy, zanim pozwolił agentowi zgłosić ukończenie pracy.

Kwestie bezpieczeństwa

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

9 kwietnia 2026 organizacja Anthropic opublikowała formalne ramy wiarygodności agentów.²⁷ Pięć zasad odpowiada koncepcji evidence gate przedstawionej w tym przewodniku — i ją rozszerza:

Organizacja Anthropic przekazała również MCP fundacji Agentic AI Foundation działającej przy Linux 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 samodzielnie deklarowana tożsamość w MCP (lipiec 2026). Specyfikacja MCP jest w trakcie przechodzenia na bezstanowy rdzeń (SEP-2575), który usuwa stanowy uścisk dłoni inicjalizacji, dotychczas przekazujący tożsamość serwera. Zmiana w wersji roboczej specyfikacji, scalona 16 lipca (PR #3002), przywraca tożsamość jako opcjonalny element interfejsu: serwery mogą umieszczać obiekt io.modelcontextprotocol/serverInfo w _meta odpowiedzi, a clientInfo staje się opcjonalne w żądaniach.⁷¹ Z punktu widzenia bezpieczeństwa najważniejsze jest stanowisko specyfikacji dotyczące zaufania: ta tożsamość jest deklarowana samodzielnie i niezweryfikowana — służy wyłącznie do wyświetlania i rejestrowania — oraz NIE POWINNA stanowić podstawy decyzji dotyczących bezpieczeństwa. Jeśli harness uzależnia listy dozwolonych elementów, reguły uprawnień lub audyt oparty na logach od nazwy zadeklarowanej przez serwer MCP, nazwa ta jest twierdzeniem, a nie poświadczeniem; zaufanie należy przypisać transportowi i konfiguracji (serwerowi skonfigurowanemu przez Państwa pod określonym punktem końcowym), nigdy temu, za co podaje się sam serwer. Sfinalizowaną wersję bezstanowej specyfikacji zaplanowano na 28 lipca 2026 — należy oczekiwać, że szczegóły na poziomie protokołu opisane w tej sekcji zostaną doprecyzowane w kolejnej aktualizacji.

Narzędzia do izolowania skills: Z myślą o zespołach, które traktują skills jako powierzchnię ataku, firma Permiso udostępniła SandyClaw (2 kwietnia 2026). Narzędzie uruchamia skills w dedykowanym sandboxie i przedstawia poparte dowodami werdykty mechanizmów wykrywania Sigma/YARA/Nova/Snort. To pierwszy produkt w kategorii sandboxów dla skills.²⁸

Sandbox

Claude Code obsługuje opcjonalny tryb sandbox (włączany za pomocą settings.json lub polecenia /sandbox), który ogranicza dostęp do sieci i operacje na systemie plików poprzez izolację na poziomie systemu operacyjnego (seatbelt w systemie macOS, bubblewrap w systemie Linux). Po włączeniu sandbox uniemożliwia modelowi wysyłanie dowolnych żądań sieciowych oraz uzyskiwanie dostępu do plików spoza katalogu projektu. Bez sandboxa Claude Code korzysta z modelu opartego na uprawnieniach, w którym poszczególne wywołania narzędzi są zatwierdzane lub odrzucane przez użytkownika.¹³

Minimalna bezpieczna wersja z maja 2026. W Claude Code v2.1.149 naprawiono obejście uprawnień katalogu roboczego w PowerShell, kilka luk w analizie uprawnień dotyczących reguł zezwalających i nieaktualnych zmiennych PowerShell oraz błąd listy dozwolonych zapisów sandboxa dla git worktree, która obejmowała cały katalog główny repozytorium głównego zamiast wyłącznie współdzielonych wewnętrznych elementów git.⁵³ Jeśli harness dopuszcza PowerShell lub agentów izolowanych za pomocą worktree, należy uznać v2.1.149+ za wersję minimalną i utrzymywać wąski zakres reguł powłoki. Szerokie reguły PowerShell(*) i wyjątki zapisu obejmujące całe repozytorium są skrótami orkiestracyjnymi, a nie granicami bezpieczeństwa.

Zaostrzenie sandboxa OpenAI Agents SDK (v0.17.0, 8 maja 2026). Po stronie OpenAI wersja 0.17.0 pakietu openai-agents-python zaostrzyła analogiczną granicę: LocalFile.src i LocalDir.src są teraz ograniczone do katalogu materializacji base_dir (bieżącego katalogu roboczego procesu SDK w chwili zastosowania manifestu), chyba że źródło zostanie jawnie dopuszczone za pomocą 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 tym katalogu albo mieć przyznane uprawnienie. Zamyka to lukę w granicy lokalnych artefaktów: wcześniejsze wersje pozwalały manifestom pobierać dowolne ścieżki hosta do obszaru roboczego sandboxa. Migracja: zaufane katalogi główne hosta należy zadeklarować na poziomie manifestu za pomocą SandboxPathGrant(path=..., read_only=True) w przypadku montowania tylko do odczytu. extra_path_grants należy traktować jako zaufaną konfigurację aplikacji; nigdy nie należy tworzyć uprawnień na podstawie danych wyjściowych modelu ani niezaufanych danych manifestu.

Kolejna minimalna wersja OpenAI Agents SDK (v0.17.3). W wydaniach 0.17.1–0.17.3 dodano dalsze zabezpieczenia sandboxa i sesji: limity wyodrębniania archiwów, walidację podścieżek GitRepo, czytelniejsze błędy dostawcy sandboxa, przechowywanie danych uwierzytelniających punktów montowania poza poleceniami sandboxa, odrzucanie względnych katalogów głównych obszaru roboczego sandboxa oraz obsługę stanów końcowych sandboxa Vercel.⁵⁴ Jeśli korzystają Państwo z sandboxów hostowanych przez OpenAI lub obsługiwanych przez dostawców, a nie wyłącznie z hooks Claude Code, należy uznać wersję 0.17.3 za obecne minimum dla wzorców opisanych w tej sekcji.

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

Wpis techniczny organizacji Anthropic „Jak izolujemy Claude w różnych produktach” (25 maja 2026) przedstawia stanowisko samego dostawcy wobec zasad, które ta sekcja omawia fragmentarycznie — sandboxa na poziomie ustawień opisanego powyżej, minimalnego poziomu izolacji worktree oraz traktowania wszystkiego jako niezaufane.⁸¹ Jego główna idea polega na dopasowaniu siły izolacji do powierzchni produktu, a samo to dopasowanie stanowi lekcję: nie istnieje jeden właściwy projekt izolacji, lecz izolacja dostosowana do tego, kto sprawuje nadzór i co może pójść nie tak.

• Efemeryczne kontenery gVisor (claude.ai). Wykonywanie po stronie serwera odbywa się w kontenerach gVisor na odizolowanej infrastrukturze, z efemerycznym systemem plików przypisanym do każdej sesji. Model zagrożeń obejmuje izolację infrastruktury i dzierżawców — komputer użytkownika nigdy nie jest osiągalny, więc nie ma potrzeby chronienia lokalnych zasobów.
• Sandbox systemu operacyjnego z udziałem człowieka (Claude Code). Wzorzec opisany w powyższym akapicie o sandboxie, ujęty jako polityka: Seatbelt w systemie macOS i bubblewrap w systemie Linux, z dozwolonym odczytem, zapisem ograniczonym do obszaru roboczego i domyślnie zablokowaną siecią — człowiek zatwierdza to, czego granica nie obejmuje. Organizacja Anthropic udostępniła środowisko uruchomieniowe na zasadach open source (sandbox-runtime), dzięki czemu granicę można audytować. Wpis otwarcie wskazuje słabe ogniwo: zatwierdzanych jest około 93% próśb o uprawnienia, a klasyfikator trybu automatycznego — wykrywający przed wykonaniem około 83% nadmiernie gorliwych działań i jednocześnie ograniczający liczbę próśb o zatwierdzenie o 84% — istnieje właśnie dlatego, że zmęczenie zatwierdzaniem jest właściwością bezpieczeństwa, a nie skargą dotyczącą UX. Jest to podejście warstwy kontrolnej, które ten przewodnik śledzi od wersji v2.1.193.
• Zapieczętowane maszyny wirtualne (Claude Cowork). Pełne maszyny wirtualne działające na hiperwizorach platformowych — Apple Virtualization framework w systemie macOS i HCS w systemie Windows — z zamontowanym wyłącznie wybranym obszarem roboczym i folderem .claude; żadne inne zasoby hosta nie są widoczne. Dane uwierzytelniające nigdy nie trafiają do maszyny wirtualnej: pozostają w pęku kluczy hosta, a każda sesja otrzymuje token o ograniczonym zakresie, który można niezależnie unieważnić. Egzekwuje to obronny serwer proxy MITM wewnątrz maszyny wirtualnej, przepuszczający wyłącznie żądania zawierające token sesji przydzielony tej maszynie — klucz osadzony przez atakującego zostaje odrzucony na granicy, ponieważ tylko maszyna wirtualna zna jego pochodzenie.

Najbardziej uniwersalne są zasady projektowe leżące u podstaw tej klasyfikacji. Najpierw izolować na poziomie środowiska, a dopiero potem sterować na poziomie modelu: każda probabilistyczna ochrona ma niezerowy współczynnik przeoczeń, dlatego deterministyczne granice muszą wychwytywać to, co umknie sterowaniu na poziomie promptu — jest to przedstawiony w tym przewodniku argument, że hooks gwarantują wykonanie, powtórzony przez dostawcę. Dopasować siłę izolacji do zdolności użytkownika do sprawowania nadzoru: programista może ocenić polecenie bash przed jego zatwierdzeniem; pracownik wiedzy nie może — dlatego Code wyświetla okno uprawnień, a Cowork otrzymuje zapieczętowaną maszynę wirtualną. Preferować sprawdzone mechanizmy zamiast niestandardowego kodu izolującego: hiperwizory, seccomp i środowiska uruchomieniowe kontenerów lepiej przetrwały wrogą analizę niż własne serwery proxy z listami dozwolonych elementów i parsery konfiguracji organizacji Anthropic. Traktować lokalną konfigurację projektu i dane wyjściowe narzędzi jako niezaufane: wpis zaleca traktowanie otwarcia projektu i wczytania konfiguracji jak każdego przychodzącego żądania z internetu, a danych wyjściowych narzędzia jako powierzchni ataku nawet wtedy, gdy samo narzędzie jest zaufane — to samo podejście niniejszy przewodnik stosuje do komunikatów między agentami, treści odczytanych przez subagents oraz samodzielnie deklarowanej tożsamości MCP. Przechowywać dane uwierzytelniające poza sandboxem: stosować tokeny ograniczonego zakresu, odwoływalne i przypisane do sesji zamiast ogólnych kluczy, które agent mógłby ujawnić.

Powierzchnia ustawień zaczyna realizować pierwszą zasadę (v2.1.219). Łatwo zgodzić się z zasadą „najpierw izolować na poziomie środowiska”, lecz dotychczas trudno było ją rzeczywiście skonfigurować, ponieważ sandbox Claude Code rozstrzygał kwestie nieobjęte regułami, zadając pytanie — a prośba o uprawnienia to probabilistyczna ochrona przebrana za deterministyczną, co potwierdza przytoczony wyżej wskaźnik 93% zatwierdzeń. sandbox.network.strictAllowlist eliminuje pytanie w przypadku ruchu wychodzącego: po ustawieniu tej opcji żądanie polecenia działającego w sandboxie skierowane do hosta spoza listy dozwolonych jest bezwarunkowo odrzucane zamiast wywoływać monit.⁸⁴ W połączeniu z wprowadzonym w v2.1.216 ustawieniem sandbox.filesystem.disabled oba ustawienia tworzą spójną postawę bezpieczeństwa, a nie zbiór przełączników — izolację systemu plików i sieci można wybierać niezależnie, a izolacja sieci może być teraz deterministyczna. W przypadku nienadzorowanego harness jest to ważniejsze z tych dwóch ustawień, ponieważ przez ruch wychodzący wstrzyknięta instrukcja prowadzi do eksfiltracji, a krańcowym przypadkiem zmęczenia zatwierdzaniem jest sytuacja, w której przy klawiaturze nie ma nikogo, kto mógłby się zmęczyć. Ceną jest zwykły koszt deterministycznej granicy: lista dozwolonych elementów musi być poprawna, a pominięty host kończy się niejasną odmową zamiast pytaniem. Należy wyliczyć hosty, których agenci rzeczywiście potrzebują, a następnie usunąć monit.

Żaden z tych mechanizmów nie zastępuje warstwy hook; znajduje się pod nią. Wzorce izolacji stanowią deterministyczną podstawę, a historia egzekwowania worktree opisana w tym przewodniku przekazuje tę samą lekcję w mniejszej skali: granica liczy się tylko wtedy, gdy wytrzymuje celowe przekierowanie, a największe szanse mają mechanizmy, których nie napisano specjalnie na tę okazję.

Granice uprawnień

System uprawnień kontroluje operacje na wielu poziomach:

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

W Claude Code v2.1.178 rozszerzono reguły uprawnień z poziomu narzędzia na poziom parametrów: Tool(param:value) dopasowuje parametry wejściowe narzędzia, a * pełni funkcję symbolu wieloznacznego. Kanonicznym przykładem jest Agent(model:opus) — reguła blokująca uruchamianie subagents na określonym poziomie modelu.⁶³ Z perspektywy architektury zamyka to lukę, której powyższa czteropoziomowa tabela nie potrafiła opisać: wcześniej można było zezwolić na całe narzędzie lub go zabronić, ale nie dało się ograniczyć sposobu jego wywołania. Polityka zarządzania może teraz deterministycznie określać, że „subagents mogą być uruchamiane, lecz nie na poziomie Fable 5” albo „Bash jest dozwolony, ale nie z tą flagą”, zamiast polegać na prośbie w prompcie.

Uzupełniające ustawienie zarządzane enforceAvailableModels (v2.1.175) ogranicza wybór modelu odgórnie: przypina model Default i uniemożliwia ustawieniom użytkownika lub projektu rozszerzenie zarządzanej listy dozwolonych modeli availableModels.⁶³ Oba mechanizmy współdziałają — lista dozwolonych określa, które poziomy w ogóle są dostępne w sesji, natomiast reguły na poziomie parametrów ograniczają sposób, w jaki subagents z nich korzystają. Od wersji v2.1.196 administratorzy mogą również ustawić domyślny model dla całej organizacji w konsoli organizacji; jest on wyświetlany jako „Org default” w /model, dzięki czemu wszystkie środowiska dziedziczą zarządzany model domyślny bez konieczności przypinania go przez każdego operatora — jest to dolna granica uzupełniająca górną granicę listy dozwolonych.

Reguły zezwalające ograniczone do ścieżek są zakotwiczone w katalogu roboczym (lipiec 2026)

W Claude Code v2.1.214 usunięto ciche, nadmiernie szerokie dopasowanie w regułach uprawnień ograniczonych do ścieżek: reguła zezwalająca z jednosegmentowym wzorcem dir/** — na przykład Edit(src/**) — automatycznie zatwierdzała edycje w każdym katalogu o nazwie src na dowolnej głębokości, w tym w vendor/some-package/src/ i wszystkich innych zagnieżdżonych katalogach src/, których autor reguły nie zamierzał obejmować. Takie reguły są teraz zakotwiczone wyłącznie w <cwd>/dir; jeśli rzeczywiście potrzebne jest dopasowanie na dowolnej głębokości, należy zadeklarować je jako **/dir/**.⁷⁴ Reguły odmowy i pytania celowo zachowują wcześniejsze dopasowanie na dowolnej głębokości. Ta asymetria jest prawidłowym projektem bezpiecznym w razie awarii: zbyt wąsko dopasowana reguła zezwalająca zachowuje bezpieczeństwo (pojawia się monit), natomiast zbyt wąsko dopasowana reguła odmowy otwiera dostęp (zablokowana ścieżka przechodzi) — dlatego zezwolenia zaostrzono, a odmowy pozostawiono szerokie. Jeśli ustawienia wykorzystują jednosegmentowe wzorce zezwalające do obejmowania zagnieżdżonych ścieżek, od wersji v2.1.214 po cichu przestały to robić; oznacza to, że poprawka działa zgodnie z zamierzeniem, lecz warto przejrzeć listy dozwolonych elementów i ponownie zadeklarować rzeczywiście potrzebny zakres.

Zabezpieczenia trybu automatycznego przed destrukcyjnymi poleceniami (czerwiec 2026)

W Claude Code v2.1.183 ograniczono zasięg szkód trybu automatycznego w przypadku operacji, które mogą po cichu spowodować utratę pracy lub zniszczyć środowiska. Tryb automatyczny bezwarunkowo blokuje teraz następujące działania, chyba że zostały jawnie zlecone podczas sesji: destrukcyjne operacje git (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend, jeśli commit nie został utworzony przez agenta w tej sesji; oraz likwidację infrastruktury (terraform destroy, pulumi destroy, cdk destroy), o ile nie wskazano konkretnego stosu.⁶⁵ Z perspektywy architektury uzupełnia to opisaną powyżej weryfikację uruchamiania i reguły na poziomie parametrów: zamiast kontrolować, którego narzędzia można użyć lub jak jest uruchamiane, mechanizm kontroluje niewielki zbiór konkretnych nieodwracalnych poleceń na podstawie intencji — agent nadal może je wykonać, ale tylko na jawne polecenie, nigdy z własnej inicjatywy. W autonomicznym harness należy zakodować tę samą zasadę we własnych hooks PreToolUse: polecenia niszczące stan wymagają domyślnej reguły odmowy, którą może uchylić wyłącznie jawny sygnał operatora.

Lipiec 2026: tryb automatyczny trafia do przedsiębiorstw, a jednego monitu nie można już pominąć. Tryb automatyczny osiągnął status GA na platformach Amazon Bedrock, Google Vertex AI i Microsoft Foundry w wersji v2.1.207, wraz z zarządzanym ustawieniem disableAutoMode umożliwiającym rezygnację na poziomie przedsiębiorstwa — podejście wykorzystujące klasyfikator jako warstwę kontrolną jest obecnie dostępne na każdej własnej platformie korporacyjnej, a jego wyłączenie stanowi jawną decyzję dotyczącą zarządzania, nie zaś lukę platformy.⁶⁸ Następnie w v2.1.208 zabezpieczenie przed katastrofalnym usuwaniem stało się bezwarunkowe: monity o potwierdzenie katastrofalnego usunięcia przebijają się teraz zarówno przez --dangerously-skip-permissions, jak i tryb automatyczny.⁶⁸ To istotny precedens — pierwsze potwierdzenie w Claude Code, którego nie może pominąć żaden tryb uprawnień, łącznie z jawną flagą obejścia. Projekty autonomicznych harnesses, które zakładały, że --dangerously-skip-permissions oznacza dosłownie brak monitów, powinny uwzględnić ten jeden wyjątek; jest uruchamiany dokładnie tam, gdzie nienadzorowana pętla może spowodować najbardziej nieodwracalne szkody.

Zabezpieczenia przed fabrykowaniem danych (lipiec 2026)

Wydania v2.1.203–v2.1.206 zamknęły dwie drogi, którymi agent mógł sfabrykować własną ścieżkę audytową.⁶⁸ Po pierwsze, reguła trybu automatycznego blokuje teraz ingerowanie w pliki transkrypcji — wywołania narzędzi należące do sesji nie mogą już przepisywać zapisu tej samej sesji. Po drugie, powiadomienia o zadaniach w tle wyraźnie informują teraz, że podczas wykonywania zadania nie nastąpiło żadne działanie człowieka. Druga zmiana rozwiązuje subtelny problem: model podsumowujący zadanie w tle mógł wcześniej przedstawić (lub wymyślić) zapisane w transkrypcji „zatwierdzenie”, którego nigdy nie udzielono, a powiadomienie temu nie przeczyło. Teraz samo powiadomienie stanowi kontrdowód.

Wniosek architektoniczny dotyczy ogólnie evidence gate: transkrypcje, powiadomienia i logi są powierzchniami audytowymi, a rzecz podlegająca audytowi nie może mieć możliwości zapisu do powierzchni, która ją audytuje. Platforma egzekwuje obecnie tę zasadę dla własnej transkrypcji; należy zastosować ją również do własnego harness — raporty dowodowe, wyniki testów i zapisy deliberacji powinny znajdować się poza ścieżką zapisywalną przez model.

Ochrona przed prompt injection

Skills i hooks zapewniają wielowarstwową ochronę 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 weryfikują każde wywołanie narzędzia niezależnie od sposobu sformułowania promptu dla modelu:

# 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 zasięg szkód. Subagent z permissionMode: plan nie może wprowadzać zmian, nawet jeśli jego prompt został przejęty.

Minimalny poziom bezpieczeństwa platformy wzrósł w lipcu 2026. W Claude Code v2.1.210 wzmocniono Agent tool przeciwko pośredniemu prompt injection przenoszonemu w treści odczytanej przez subagent — zatruty plik, strona internetowa lub wynik narzędzia pobrany przez subagent ma mniejszą zdolność sterowania samą powierzchnią delegowania.⁶⁹ Z kolei w v2.1.211 wzmocniono ludzkie ogniwo łańcucha: podglądy uprawnień neutralizują teraz znaki Unicode dwukierunkowego nadpisywania, znaki o zerowej szerokości oraz znaki podobne wizualnie, dzięki czemu polecenie nie może już zostać skonstruowane tak, aby w oknie zatwierdzenia wyglądało niewinnie, a wykonywało coś innego.⁶⁹ Druga poprawka ma największe znaczenie w harnesses, w których człowiek zatwierdza wyrenderowane podglądy pod presją czasu — wyświetlany tekst również stanowił powierzchnię prompt injection. Żadna z tych zmian nie zastępuje opisanych powyżej zabezpieczeń na poziomie hook; podnoszą one poziom podstawowej ochrony pod nimi.

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

Dwa komunikaty z maja 2026 potwierdzają pewien wzorzec: infrastruktura agentów tworzy nowe miejsca, z których poufne treści i wykonywalne polityki mogą wyciekać lub wydostawać się poza wyznaczone granice. Komunikat GitHub GHSA-f3jg-756w-gm35 opisuje problem z filtrem ładunków Gryph Agents, przez który poufna zawartość ładunków narzędzi mogła pozostawać w lokalnych logach SQLite przy domyślnym sposobie rejestrowania.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p opisuje ucieczkę z sandboxa niestandardowego kodu guardrail LiteLLM w punkcie końcowym proxy chronionym przez administratora.⁴⁶

Zasada produkcyjna: transkrypcje agentów, ładunki narzędzi, logi SQLite oraz wykonywanie guardrails należy traktować jako poufną infrastrukturę. Dane należy redagować przed ich utrwaleniem, stosować limity przechowywania oraz utrzymywać niestandardowy kod guardrail w sandboxie i w formie możliwej do przeglądu. Reguła „nie rejestruj sekretów” na poziomie promptu nie wystarcza; ścieżka rejestrowania i guardrail wymaga deterministycznych testów.

Bezpieczeństwo hooks

Hooks HTTP, które interpolują 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 architektur agentów wymaga wyraźnego podziału odpowiedzialności między człowieka i agenta:¹⁷

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

Rekurencyjne egzekwowanie hooks

Hooks są uruchamiane również dla działań subagent.¹³ Jeśli Claude uruchamia subagent za pośrednictwem Agent tool, hooks PreToolUse i PostToolUse wykonują się dla każdego narzędzia używanego przez subagent. Bez rekurencyjnego egzekwowania hooks subagent mógłby ominąć bramki bezpieczeństwa. Zdarzenie SubagentStop umożliwia wykonanie czyszczenia lub walidacji po zakończeniu działania subagent.

Nie jest to opcjonalne. Agent uruchamiający subagent bez hooks bezpieczeństwa może wymusić push do main, odczytać pliki z danymi uwierzytelniającymi lub uruchomić destrukcyjne polecenia, podczas gdy bramki bezczynnie obserwują główną konwersację.

Koszt jako element architektury

Koszt jest decyzją architektoniczną, a nie późniejszą kwestią operacyjną.² Trzy poziomy:

Poziom tokenów. Kompresja promptu systemowego. Należy usunąć przykłady kodu instruktażowego (model zna APIs), scalić powielone reguły znajdujące się w różnych plikach i zastąpić wyjaśnienia ograniczeniami. „Odrzucaj wywołania narzędzi pasujące do poufnych ścieżek” wykonuje tę samą pracę co 15-wierszowe wyjaśnienie, dlaczego nie należy odczytywać danych uwierzytelniających.

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

Poziom architektury. Najpierw CLI, a nie MCP, gdy operacja jest bezstanowa. Wywołanie claude --print służące do jednorazowej oceny kosztuje mniej i nie powoduje narzutu związanego z połączeniem. MCP ma sens, gdy narzędzie wymaga trwałego stanu lub przesyłania strumieniowego.

Struktura decyzyjna

Kiedy używać poszczególnych mechanizmów:

Skills vs Hooks vs Subagents

FAQ

Ile hooks to za dużo?

Ograniczeniem jest wydajność, a nie liczba. Każdy hook działa synchronicznie, więc łączny czas wykonywania hooks dodaje się do każdego dopasowanego wywołania narzędzia. 95 hooks w ustawieniach na poziomie użytkownika i projektu działa bez zauważalnych opóźnień, jeśli każdy hook kończy się w czasie poniżej 200 ms. Próg, który warto obserwować: jeśli PostToolUse hook dodaje ponad 500 ms do każdej edycji pliku, sesja zaczyna sprawiać wrażenie ociężałej. Przed wdrożeniem hooks należy je profilować za pomocą time.¹⁴

Czy hooks mogą zablokować Claude Code przed uruchomieniem polecenia?

Tak. PreToolUse hooks blokują dowolną akcję narzędzia przez zakończenie z kodem 2. Claude Code anuluje oczekującą akcję i pokazuje modelowi wyjście stderr z hook. Claude widzi powód odrzucenia i proponuje bezpieczniejszą alternatywę. Kod wyjścia 1 oznacza nieblokujące ostrzeżenie, przy którym akcja nadal jest wykonywana.³

Gdzie umieścić pliki konfiguracji hooks?

Konfiguracje hooks trafiają do .claude/settings.json dla hooks na poziomie projektu (commitowane do repozytorium, współdzielone z zespołem) albo do ~/.claude/settings.json dla hooks na poziomie użytkownika (osobiste, stosowane w każdym projekcie). Hooks na poziomie projektu mają pierwszeństwo, gdy istnieją oba warianty. Dla plików skryptów należy używać ścieżek bezwzględnych, aby uniknąć problemów z katalogiem roboczym.¹⁴

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 wyzwalają tylko decyzje z łączną pewnością poniżej 0,70, czyli 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 wyzwalają ją konsekwentnie.⁷

Jak testować system zaprojektowany do generowania niezgody?

Należy testować zarówno ścieżki sukcesu, jak i ścieżki błędów. Sukces: agenci produktywnie się nie zgadzają i dochodzą do konsensusu. Błąd: agenci zbyt szybko osiągają zgodność, nigdy jej nie osiągają albo przekraczają budżety spawn. Testy end-to-end symulują każdy scenariusz z deterministycznymi odpowiedziami agentów, weryfikując, że obie bramki walidacji wychwytują każdy udokumentowany tryb awarii. Produkcyjny system deliberation uruchamia 141 testów na trzech warstwach: 48 testów integracyjnych bash, 81 testów jednostkowych Python i 12 symulacji pipeline end-to-end.⁷

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

Deliberation z 3 agentami dodaje 30-60 sekund czasu zegarowego (agenci działają sekwencyjnie przez Agent tool). Deliberation z 10 agentami dodaje 2-4 minuty. Hooks consensus i pride check działają każdy poniżej 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 kontekstu, więc najważniejsze instrukcje warto umieścić na początku: polecenia i definicje zamknięcia przed preferencjami stylu.²¹

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

Zasady architektoniczne (hooks jako deterministyczne bramki, skills jako wiedza domenowa, subagents jako izolowane konteksty, system plików jako pamięć) koncepcyjnie stosują się do każdego systemu agentowego. Konkretna implementacja używa zdarzeń cyklu życia Claude Code, wzorców matcher 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 danego narzędzia.

Ściąga

Konfiguracja hook

{
  "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 subagent

---
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