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

TL;DR: Claude Code nie jest oknem czatu z dostępem do plików. To programowalne środowisko uruchomieniowe z 29 udokumentowanymi zdarzeniami cyklu życia, z których każde można podpiąć pod hooks za pomocą skryptów shell, których model nie może pominąć. Łącz hooks w dispatchers, dispatchers w skills, skills w agents, agents w workflows, a powstaje autonomiczny harness deweloperski, który egzekwuje ograniczenia, deleguje pracę, utrwala pamięć między sesjami i orkiestruje wieloagentową deliberację. Claude Code v2.1.147 dodał domyślnie wyłączone narzędzie Workflow (CLAUDE_CODE_WORKFLOWS=1), przesuwając deterministyczną wieloagentową orkiestrację z czysto użytkowych skryptów w stronę natywnego prymitywu środowiska uruchomieniowego; v2.1.149 wzmacnia tę samą lekcję od strony bezpieczeństwa dzięki poprawkom obchodzenia uprawnień w PowerShell i poprawce allowlisty sandboxa git-worktree. Hooks i evidence gates nadal odpowiadają za poprawność.⁵²⁵³ Ten przewodnik omawia każdą warstwę tego stosu: od pojedynczego hook po system konsensusu 10 agents. Bez frameworków. Tylko bash i JSON.

Andrej Karpathy ukuł termin na to, co wyrasta wokół agenta LLM: claws. To hooks, skrypty i orkiestracja, które pozwalają agentowi uchwycić świat poza jego oknem kontekstu.¹ Większość programistów traktuje agentów kodujących AI jak interaktywnych asystentów. Wpisują prompt, patrzą, jak agent edytuje plik, i przechodzą dalej. Takie ujęcie ogranicza produktywność do tego, co można osobiście nadzorować.

Model mentalny infrastruktury jest inny: agent kodujący AI to programowalne środowisko uruchomieniowe z jądrem LLM. Każde działanie modelu przechodzi przez hooks, które Pan/Pani kontroluje. Definiuje się polityki, nie prompty. Model działa w obrębie infrastruktury tak samo, jak serwer WWW działa w ramach reguł nginx. Nie siedzi się przy nginx i nie wpisuje żądań. Konfiguruje się go, wdraża i monitoruje.

To rozróżnienie ma znaczenie, ponieważ infrastruktura kumuluje korzyści. Hook, który blokuje dane uwierzytelniające w poleceniach bash, chroni każdą sesję, każdego agenta i każde autonomiczne uruchomienie. Skill, który koduje rubrykę oceny, stosuje się konsekwentnie niezależnie od tego, czy wywołuje go Pan/Pani, czy agent. Agent, który sprawdza kod pod kątem bezpieczeństwa, wykonuje te same kontrole niezależnie od tego, czy ktoś obserwuje jego pracę.²

Najważniejsze wnioski

• Hooks gwarantują wykonanie; prompty nie. Hooks należy stosować do lintingu, formatowania, kontroli bezpieczeństwa i 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 tylko ostrzega.³
• Skills kodują wiedzę domenową, która aktywuje się automatycznie. Pole description decyduje o wszystkim. Claude używa rozumowania LLM (a nie dopasowywania słów kluczowych), aby zdecydować, kiedy zastosować skill.⁴
• Subagents zapobiegają puchnięciu kontekstu. Izolowane okna kontekstu do eksploracji i analizy utrzymują główną sesję w lekkiej formie. Niezależne subagents można uruchamiać równolegle, a zespołów agents używać wtedy, gdy pracownicy potrzebują trwałej koordynacji.⁵
• Pamięć żyje w systemie plików. Pliki utrzymują się między oknami kontekstu. CLAUDE.md, MEMORY.md, katalogi rules i dokumenty handoff tworzą uporządkowany zewnętrzny system pamięci.⁶
• Wieloagentowa deliberacja wychwytuje martwe pola. Pojedynczy agents nie potrafi podważać własnych założeń. Dwóch niezależnych agents z różnymi priorytetami oceny wychwytuje błędy strukturalne, których quality gates nie potrafią obsłużyć.⁷
• Wzorzec harness jest systemem. CLAUDE.md, hooks, skills, agents i pamięć nie są niezależnymi funkcjami. Składają się w deterministyczną warstwę między Panem/Panią a modelem, która skaluje się wraz z automatyzacją.

Jak korzystać z tego przewodnika

Każda sekcja opiera się na poprzedniej. Ramy decyzyjne na końcu zawierają tabelę pomocniczą do wyboru właściwego mechanizmu dla każdego typu problemu.

Pięciominutowa ścieżka złota

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

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

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

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

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

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

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

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

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

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

Krok 3: Uruchomienie subagenta (30 sekund)

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

Co zostało uzyskane

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

Dlaczego architektura agentów ma znaczenie

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

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

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

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

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

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

Wzorzec harness

Harness to nie framework. To wzorzec: kompozycyjny zestaw plików, skryptów i konwencji, który otacza agenta kodującego AI deterministyczną infrastrukturą. Komponenty:

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

Warstwa instrukcji: Pliki CLAUDE.md i katalogi rules definiują, co agent wie o projekcie. Ładują się automatycznie na początku sesji oraz po każdej kompakcji. Jest to długoterminowa pamięć architektoniczna agenta.

Warstwa rozszerzeń: Skills dostarczają wiedzę dziedzinową, która aktywuje się automatycznie w zależności od kontekstu. Hooks zapewniają deterministyczne bramki uruchamiane przy każdym pasującym wywołaniu narzędzia. Pliki pamięci utrwalają stan między sesjami. Niestandardowe agenty zapewniają wyspecjalizowane konfiguracje subagents.

Warstwa orkiestracji: Wzorce wieloagentowe koordynują niezależne agenty w celu badań, recenzji i deliberacji. Budżety spawn zapobiegają niekontrolowanej rekurencji. Walidacja konsensusu zapewnia jakość.

Kluczowy wniosek: większość użytkowników pracuje wyłącznie w warstwie Core, obserwując pęczniejący kontekst i rosnące koszty. Zaawansowani użytkownicy konfigurują warstwy Instruction i Extension, a warstwy Core używają wyłącznie do orkiestracji i końcowych decyzji.²

Harness zarządzany vs. self-hosted (kwiecień 2026)

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

Głębsza powierzchnia SDK po stronie OpenAI pojawiła się w openai-agents Python v0.14.0 (wydanie 15 kwietnia 2026; ogłoszenie 16 kwietnia): podklasa SandboxAgent klasy Agent z default_manifest, instrukcjami sandbox i capabilities; Manifest opisujący kontrakt świeżego workspace (pliki, katalogi, pliki lokalne, repozytoria Git, env, użytkownicy, montowania); SandboxRunConfig dla okablowania per-run klienta sandbox, wstrzykiwania sesji live, nadpisań manifestu, snapshotów oraz limitów współbieżności materializacji. Wbudowane capabilities obejmują dostęp do shella, edycję filesystem, inspekcję obrazów, skills, pamięć sandbox oraz kompakcję. Pamięć sandbox utrwala wyekstrahowane lekcje pomiędzy uruchomieniami i ujawnia je progresywnie; workspaces obsługują pliki lokalne, wpisy repozytoriów Git oraz zdalne montowania (S3, R2, GCS, Azure Blob, S3 Files); snapshoty są przenośne między dostawcami. Backendy: UnixLocalSandboxClient, DockerSandboxClient oraz klienci hostowani dla Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop i Vercel poprzez opcjonalne dodatki.²⁴

Dla projektów Python, które chcą osadzić runtime Claude Code jako bibliotekę — pomiędzy „wywołaniem powłoki do claude” a „REST API do Managed Agents” — claude-agent-sdk-python stanowi trzecią opcję. Seria z 28-29 kwietnia (v0.1.69 → v0.1.71) podniosła dołączony CLI do v2.1.123, podniosła minimalną wersję zależności mcp do >=1.19.0 (starsze wersje po cichu odrzucały zwroty CallToolResult z narzędzi MCP in-process, pozostawiając model z blobem błędu walidacji) oraz doprowadziła SandboxNetworkConfig do parytetu schematów z TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

Jeśli harness obejmuje warstwę głosową lub realtime, openai-agents-python v0.17.0 (8 maja 2026) zaktualizował RealtimeAgent, aby domyślnie używał gpt-realtime-2.⁴¹ Istniejące sesje realtime pobierają nową wartość domyślną automatycznie; należy jawnie przypiąć poprzedni model, aby utrzymać stare zachowanie do celów ewaluacji.

Architektoniczne rozwidlenie jest teraz realne:

Kiedy wybrać które: self-hosted pozostaje właściwy dla zespołów, które dysponują już infrastrukturalnymi kompetencjami, chcą mieć skills/hooks pod własną kontrolą lub głęboko optymalizują konkretny workflow. Zarządzany jest właściwy dla zespołów bez dedykowanych platform engineers, gdy czas wartości liczy się bardziej niż dostosowywanie, lub gdy uruchomienia agentów muszą niezawodnie przetrwać zamknięcie laptopa, bez konieczności samodzielnego budowania warstwy persystencji. Oba podejścia są kompatybilne — można uruchomić self-hosted harness, który deleguje konkretne długo trwające zadania do Managed Agents poprzez ich 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 służy określonemu celowi. Drzewo ~/.claude/ to osobista infrastruktura, która ma zastosowanie do wszystkich projektów. Drzewo .claude/ w każdym repozytorium jest specyficzne dla projektu i współdzielone poprzez git. Razem tworzą kompletny harness.

System Skills

Skills to rozszerzenia wywoływane przez model. Claude wykrywa je i stosuje automatycznie na podstawie kontekstu, bez konieczności jawnego ich wywoływania.⁴ Moment, w którym trzeba ponownie wyjaśniać ten sam kontekst w kolejnych sesjach, jest momentem, w którym warto zbudować skill.

Kiedy zbudować skill

Skills służą do wiedzy, którą Claude ma zawsze dostępną. Slash commands służą do akcji wyzwalanych jawnie. Przy wyborze między nimi warto zapytać: „Czy Claude powinien stosować to automatycznie, czy to ja powinienem zdecydować, kiedy to uruchomić?”

Tworzenie skill

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

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

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

# Code Review Expertise

## Security Checks
When reviewing code, verify:

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

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

Dokumentacja frontmatter

Pole description jest kluczowe

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

Słaby 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 obejmuje: co robi (przegląda kod pod kątem konkretnych typów problemów), kiedy go używać (analiza zmian, PR-ów, jakości) oraz frazy wyzwalające (review, audit, check), które użytkownicy wpisują naturalnie.

Budżet kontekstu

Wszystkie opisy skills współdzielą budżet kontekstu skalowany dynamicznie na poziomie 1% okna kontekstu, z fallbackiem 8 000 znaków.⁴ Jeśli skills jest dużo, każdy opis powinien być zwięzły, a kluczowy przypadek użycia powinien znaleźć się na początku. Budżet można nadpisać przez zmienną środowiskową SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ ale lepszym rozwiązaniem są krótsze i bardziej precyzyjne opisy. Podczas sesji warto uruchomić /context, aby sprawdzić, czy jakieś skills nie zostały wykluczone.

Pliki pomocnicze i organizacja

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

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

Należy odwoływać się do nich z SKILL.md za pomocą linków względnych. Claude czyta te pliki na żądanie, gdy skill się aktywuje. SKILL.md powinien mieć mniej niż 500 wierszy, a szczegółowe materiały referencyjne warto przenieść do plików pomocniczych.¹²

Udostępnianie skills przez Git

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

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

Gdy członkowie zespołu wykonują pull, automatycznie otrzymują skill. Bez instalacji, bez konfiguracji. To najskuteczniejszy sposób standaryzacji wiedzy eksperckiej w zespole.

Skills jako biblioteka promptów

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

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

Każdy skill koduje inny aspekt Pana/Pani wiedzy eksperckiej. Razem tworzą bazę wiedzy, z której Claude korzysta automatycznie na podstawie kontekstu. Młodszy developer otrzymuje wskazówki na poziomie seniora bez konieczności proszenia o nie.

Skills łączą się z hooks

Skills mogą definiować we frontmatter własne hooks, aktywowane tylko podczas działania danego skill. Pozwala to tworzyć zachowania specyficzne dla domeny, które nie zanieczyszczają innych sesji:²

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

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

Typowe błędy przy skills

Zbyt szerokie opisy. Skill git-rebase-helper, który aktywuje się przy każdym prompcie związanym z git (rebases, merges, cherry-picks, nawet git status), zanieczyszcza 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ęcej skills oznacza więcej opisów konkurujących o 1% budżetu kontekstu. Jeśli skills się nie aktywują, należy sprawdzić /context pod kątem wykluczonych pozycji. Lepiej stawiać na mniejszą liczbę dobrze opisanych skills niż na wiele niejasnych.

Krytyczne informacje ukryte w plikach pomocniczych. Claude czyta SKILL.md natychmiast, ale do plików pomocniczych sięga tylko wtedy, gdy jest to potrzebne. Jeśli krytyczna informacja znajduje się w pliku pomocniczym, Claude może jej nie znaleźć. Kluczowe informacje należy umieszczać bezpośrednio w SKILL.md.⁴

Powierzchnia skill SDK (8 maja 2026)

Self-hosted harnesses na claude-agent-sdk-python v0.1.77+ powinny używać opcji skills w ClaudeAgentOptions do deklarowania dostępnych skills, a nie starszej wartości "Skill" w allowed_tools.³⁷ Skrót "Skill" jest przestarzały, a dedykowana opcja daje Claude Code bardziej ustrukturyzowane informacje o tym, które skills są dostępne. Dołączony CLI w v0.1.77 to v2.1.133.

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

Skills zawsze ładowały się z katalogu projektu .claude/skills/. Claude Code v2.1.157 rozszerza ten katalog na plugins: plugin umieszczony w .claude/skills/ ładuje się teraz automatycznie bez rejestracji w marketplace, a claude plugin init <name> tworzy tam nowy szkielet z manifestem i SKILL.md już połączonymi.⁵⁸ To zamyka lukę między dwoma kształtami narzędzi projektowych, które wcześniej znajdowały się w różnych miejscach — prostym skill zapisanym bezpośrednio w repozytorium oraz plugin, który łączy skill, hooks i serwer MCP, ale wcześniej wymagał marketplace do instalacji. Praktyczny efekt dla projektowania harness: narzędzia scoped do projektu nie muszą już przechodzić przez registry, aby zostać dostarczone — wystarczy je napisać, commitować, a członkowie zespołu otrzymają tę samą powierzchnię po git pull. Plugins nadal obsługują przypadek pakietu instalacyjnego (hooks + skills + serwery MCP + agents w jednym ZIP); zmiana polega na tym, że projekt nie musi już uruchamiać marketplace tylko po to, aby załadować jeden z własnego drzewa.

Ukrywanie wbudowanej powierzchni jako governance (8 czerwca 2026)

Skills są możliwościami, a możliwości są 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, workflows i wbudowane slash commands.⁶⁰ Dla utwardzonego lub regulowanego harness jest to celowe ograniczenie powierzchni ataku: operator, który przeprowadził audyt i zatwierdził konkretny zestaw project i personal skills, może wyłączyć wszystko, co Anthropic dostarcza w pakiecie, dzięki czemu model zawsze rozumuje wyłącznie na podstawie powierzchni sprawdzonej przez operatora. Należy traktować to tak samo jak tool allowlist — domyślnie dostępna jest szeroka funkcjonalność, a jej wyłączenie jest decyzją governance, nie wygodnym przełącznikiem.

Zagnieżdżone .claude/skills i rozstrzyganie closest-wins (16 czerwca 2026)

Claude Code v2.1.178 sprawił, że narzędzia projektowe stały się świadome lokalizacji. Skills w zagnieżdżonych katalogach .claude/skills ładują się teraz podczas pracy na plikach znajdujących się pod tym katalogiem, a nie tylko z katalogu głównego repozytorium; przy konflikcie nazw zagnieżdżony skill pojawia się jako <dir>:<name>, dzięki czemu oba pozostają dostępne.⁶³ Ta sama wersja sprawiła, że reszta powierzchni projektu rozstrzyga się według katalogu najbliższego katalogowi roboczemu: gdy nazwa agent, workflow lub output-style koliduje między zagnieżdżonymi katalogami .claude/, wygrywa ta znajdująca się najbliżej katalogu roboczego, a zapis workflow w zakresie projektu trafia do najbliższego istniejącego .claude/workflows/, a nie zawsze do katalogu głównego.⁶³ Dla monorepo lub repo-of-repos to różnica między jedną płaską globalną powierzchnią a narzędziami per-package aktywującymi się w kontekście — services/api/.claude/skills/ może zawierać skills specyficzne dla API, które pojawiają się tylko podczas pracy w tym drzewie, bez konfliktu ze skill services/web/ o tej samej nazwie.

Architektura hooków

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

Dostępne zdarzenia

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

Semantyka kodów wyjścia

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

Krytyczne: Każdy hook bezpieczeństwa musi używać exit 2, nie exit 1. Exit 1 jest nieblokującym ostrzeżeniem. Niebezpieczne polecenie nadal się wykona. To najczęstszy błąd związany z hookami w zespołach.¹⁴

Konfiguracja hooków

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

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

Pole matcher filtruje wartość specyficzną dla zdarzenia. W przypadku zdarzeń narzędzi dopasowuje wartości tool_name, takie jak Bash, Edit, Write, Read, Glob, Grep, nazwy narzędzi MCP w rodzaju mcp__server__tool albo * dla wszystkich narzędzi. Proste nazwy i listy rozdzielone znakiem | są dopasowaniami dokładnymi; wartości z innymi znakami są wyrażeniami regularnymi JavaScript. Niektóre zdarzenia nie obsługują matcherów i uruchamiają się zawsze, gdy są skonfigurowane.¹³

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

Hooks otrzymują JSON na stdin z pełnym kontekstem:

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

W celu bardziej zaawansowanej kontroli hooks PreToolUse mogą zwracać JSON, aby zmodyfikować wejście narzędzia, wstrzyknąć kontekst albo podjąć decyzje o uprawnieniach. Należy używać wrappera hookSpecificOutput — starszy format najwyższego poziomu decision/reason jest przestarzały dla PreToolUse:

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

Trzy typy gwarancji

Przed napisaniem dowolnego hooka należy zapytać: jakiego rodzaju gwarancji potrzebuję?¹⁴

Gwarancje formatowania zapewniają spójność po fakcie. Hooks PostToolUse na Write/Edit uruchamiają formatter po każdej zmianie pliku. Wynik modelu nie ma znaczenia, ponieważ formatter normalizuje wszystko.

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

Gwarancje bezpieczeństwa zapobiegają niebezpiecznym działaniom, zanim zostaną wykonane. Hooks PreToolUse na Bash sprawdzają polecenia i blokują destrukcyjne wzorce kodem wyjścia 2:

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

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

Gwarancje jakości walidują stan w punktach decyzyjnych. Hooks PreToolUse na poleceniach git commit uruchamiają linter lub zestaw testów i blokują commit, jeśli kontrole jakości się nie powiodą:

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

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

Typy hooków poza poleceniami powłoki

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

Command hooks (type: "command") uruchamiają skrypty powłoki. Są szybkie, deterministyczne i bez kosztu tokenów.

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

Prompt hooks (type: "prompt") wysyłają jednoturowy prompt do szybkiego modelu Claude. Model zwraca { "ok": true }, aby zezwolić, albo { "ok": false, "reason": "..." }, aby zablokować. Należy ich używać do niuansowanej oceny, której regex nie potrafi wyrazić.

Agent hooks (type: "agent") uruchamiają subagent z dostępem do narzędzi (Read, Grep, Glob) na potrzeby wieloturowej weryfikacji. Są eksperymentalne; w bramkach produkcyjnych lepiej preferować command hooks, a agent hooks zostawić dla kontroli, które rzeczywiście wymagają sprawdzania realnych 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 Claude Code v2.1.140 wejście agent hook zawiera subagent_type, co pozwala współdzielonemu hookowi odróżnić uruchomienie security-reviewer od explorera lub ogólnego workera bez zgadywania na podstawie treści promptu.⁴⁹

HTTP hooks (type: "http") wysyłają wejście JSON danego zdarzenia jako żądanie POST pod URL i otrzymują JSON z powrotem. 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
          }
        ]
      }
    ]
  }
}

Hooks asynchroniczne

Hooks mogą działać w tle bez blokowania wykonania. Należy dodać async: true dla operacji niekrytycznych, takich jak powiadomienia i logowanie:¹³

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

Async należy używać do powiadomień, telemetrii i kopii zapasowych. Nigdy nie należy używać async do formatowania, walidacji ani czegokolwiek, co musi się zakończyć przed następnym działaniem.

Dispatchers zamiast niezależnych hooków

Uruchamianie siedmiu hooków na tym samym zdarzeniu, z których każdy niezależnie czyta stdin, tworzy warunki wyścigu. Dwa hooks zapisujące jednocześnie do tego samego pliku stanu JSON obetną JSON. Każdy downstream hook, który parsuje ten plik, przestanie działać.²

Rozwiązanie: jeden dispatcher na zdarzenie, który uruchamia hooks sekwencyjnie z buforowanego stdin:

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

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

Debugowanie hooków

Pięć technik debugowania hooków, które zawodzą po cichu:¹⁴

1. Testować skrypty niezależnie. Przekazać przykładowy JSON przez pipe: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Używać stderr do danych debugowania. Stderr przy kodzie wyjścia 2 jest przekazywany z powrotem do Claude jako komunikat błędu. Nieblokujący stderr (exit 1, 3 itd.) pojawia się tylko w trybie szczegółowym (Ctrl+O).
3. Uważać na awarie jq. Błędne ścieżki JSON zwracają po cichu null. Wyrażenia jq należy testować względem rzeczywistego wejścia narzędzia.
4. Weryfikować kody wyjścia. Hook PreToolUse używający exit 1 nie zapewnia żadnego egzekwowania, choć wygląda, jakby działał.
5. Utrzymywać hooks szybkie. Hooks działają synchronicznie. Wszystkie hooks powinny mieścić się poniżej 2 sekund, najlepiej poniżej 500 ms.

Strumieniowanie zdarzeń hooków po stronie SDK

Self-hosted harnesses zbudowane na claude-agent-sdk-python (v0.1.74+, 6 maja 2026) mogą subskrybować zdarzenia hooków bezpośrednio ze strumienia wiadomości, zamiast przechodzić przez callbacki 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 wiadomości asystenta i wyniki narzędzi. Odzwierciedla to opcję includeHookEvents z TypeScript SDK; dołączony CLI podniesiono w tym samym wydaniu do v2.1.129.

Wzorzec strumienia zdarzeń pasuje wtedy, gdy harness już działa w Python i sygnały hooków mają znaleźć się w tym samym przepływie sterowania co wynik modelu. Kontrakt hooków skryptów powłoki (kody wyjścia, stdin JSON, dispatchers) pozostaje właściwą odpowiedzią dla harnesses, które komponują wiele narzędzi, współdzielą hooks między Claude Code i Codex albo potrzebują semantyki kodów wyjścia do blokowania.

Wysiłek i pochodzenie sesji (7-8 maja 2026)

Dwa dodatki w Claude Code v2.1.132 i v2.1.133 dają hookom i podprocesom lepszy sygnał o kontekście wykonania:³⁸³⁹

• effort.level w wejściu hooka. Hooks otrzymują teraz pole JSON effort.level w tym samym wejściu, które zawiera tool_input i session_id. Ta sama wartość jest eksportowana jako zmienna środowiskowa $CLAUDE_EFFORT, więc polecenia Bash mogą ją odczytać bez parsowania JSON. Warto używać tego do skalowania kosztu hooka według poziomu wysiłku: pominąć kosztowną walidację przy low, uruchomić pełną bramkę bezpieczeństwa przy xhigh lub max.
• Zmienna środowiskowa CLAUDE_CODE_SESSION_ID w podprocesach Bash. Podprocesy narzędzia Bash widzą teraz tę samą wartość session_id, którą widzą hooks, udostępnioną jako CLAUDE_CODE_SESSION_ID. Zamyka to lukę pochodzenia dla narzędzi, które logują stan per sesja i wcześniej nie mogły korelować zdarzeń podprocesów ze zdarzeniami hooków.

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

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

Claude Code v2.1.136 dodał nowy poziom hard-deny do trybu auto i naprawił grupę problemów z pluginami oraz MCP, które wpływały na długotrwałe harnesses:⁴⁰

• settings.autoMode.hard_deny. Reguły klasyfikatora trybu auto, które blokują bezwarunkowo, niezależnie od intencji użytkownika lub wyjątków allow. Znajduje się to nad istniejącymi matcherami allow/deny jako nienegocjowalna dźwignia governance. Należy używać tego dla reguł, których nigdy nie wolno nadpisać (force-push do main, pliki zawierające sekrety, dostęp do produkcyjnej bazy danych), nawet gdy operator zatwierdził szerszą kategorię w swoich ustawieniach osobistych.
• Serwery MCP nie znikają już po /clear. Serwery skonfigurowane w .mcp.json, pluginach i connectorach claude.ai po /clear w rozszerzeniu VS Code, pluginie JetBrains i Agent SDK po cichu wypadały z aktywnego zestawu. Poprawka trafia do v2.1.136. Jeśli widoczny był komunikat „serwer MCP X zniknął w środku sesji”, to była przyczyna.
• Utrata refresh-tokenów OAuth MCP przy równoczesnym odświeżaniu. Użytkownicy z kilkoma zdalnymi serwerami MCP nie powinni już potrzebować codziennego ponownego uwierzytelniania. Równoczesne zapisy odświeżania nadpisywały się nawzajem.
• Plan mode blokuje teraz zapisy plików poprawnie. Pasująca reguła allow Edit(...) obchodziła ochronę zapisu w plan-mode. Plan mode jest teraz egzekwowany niezależnie od reguł allow.
• Hooks pluginów Stop i UserPromptSubmit nie zawodzą już w środku sesji. Czyszczenie cache usuwało pliki wersji pluginów nadal używane przez uruchomioną sesję, psując konkretnie te dwa zdarzenia hooków. Poprawka utrzymuje używane wersje przypięte.
• Wpis skills w plugin.json. Ustawienie skills ukrywało domyślny katalog skills/ pluginu. Teraz wpis komponuje się poprawnie, a wskazanie go na ścieżkę pliku zgłasza jawny błąd zamiast cichej awarii.
• Starzejące się zmienne środowiskowe hooka SessionStart CLAUDE_ENV_FILE. Zmienne eksportowane przez hooks SessionStart przez CLAUDE_ENV_FILE stawały się nieaktualne po /resume lub /clear. Naprawiono w v2.1.136. Sesje teraz ponownie wczytują plik env przy tych zdarzeniach.

Dla governance harnesses operacyjnie najciekawsze pozycje to autoMode.hard_deny (nowa dźwignia) i poprawka znikania MCP (cicha awaria psująca długie sesje). Cała reszta to poprawki jakości życia.

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

Claude Code v2.1.139 dodał dwa szczegóły hooków ważne dla harnesses produkcyjnych: formę exec args: string[] dla command hooks oraz continueOnBlock dla hooks PostToolUse.⁴²⁴⁴ Należy preferować args, gdy hook potrzebuje dynamicznych wartości lub placeholderów ścieżek. Uruchamia to polecenie bezpośrednio bez powłoki, co usuwa całą klasę błędów cytowania i injection.

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

To samo wydanie przekazuje CLAUDE_PROJECT_DIR do serwerów stdio MCP i pozwala konfiguracjom pluginów odwoływać się do ${CLAUDE_PROJECT_DIR} w poleceniach.⁴² Narzędzia MCP powinny rozwiązywać ścieżki względem projektu z tej wartości, a nie z dowolnego katalogu roboczego procesu, który przypadkiem uruchomił serwer.

Claude Code v2.1.140 to głównie wydanie niezawodnościowe dla operatorów harnesses: naprawia hooks ConfigChange, które nie uruchamiały się przy zmianach ustawień, zamyka przypadki brzegowe, w których disableAllHooks i allowManagedHooksOnly nie komponowały się poprawnie między poziomami ustawień, oraz zatrzymuje okna dialogowe uprawnień przed ujawnianiem niezamierzonych zmiennych środowiskowych zwróconych przez wyniki hooków.⁴⁹ Dzięki temu istniejące wzorce governance w tej sekcji stają się bardziej niezawodne; nie wymaga to nowej architektury hooków.

Claude Code v2.1.141 dodaje pole wyjścia hooka terminalSequence dla powiadomień desktopowych, tytułów okien i dzwonków bez terminala sterującego.⁵⁰ Należy traktować to jako sygnalizację operatorską, nie egzekwowanie. Bramki bezpieczeństwa i jakości nadal powinny komunikować awarie przez normalny kontrakt blokowania: ustrukturyzowane wyjście hooka plus zachowanie wyjścia, które zapobiega niebezpiecznemu działaniu. To samo wydanie dodaje claude agents --cwd <path> do ograniczania Agent View do jednego katalogu, CLAUDE_CODE_PLUGIN_PREFER_HTTPS dla instalacji pluginów w środowiskach bez kluczy GitHub SSH oraz ANTHROPIC_WORKSPACE_ID dla reguł federacji workload-identity obejmujących więcej niż jeden workspace.⁵⁰ To szczegóły architektoniczne dla zespołowych harnesses: węższe widoki operacyjne, mniej założeń dotyczących instalacji pluginów i jawne zakresowanie tokenów enterprise.

Claude Code v2.1.142 jest ważniejszy dla orkiestracji sesji w tle niż dla semantyki hooków.⁵¹ claude agents może teraz wysyłać sesje w tle z jawnymi flagami katalogu, ustawień, MCP, pluginu, uprawnień, modelu i wysiłku, zamiast zależeć od stanu wrappera. Fast mode domyślnie używa teraz Opus 4.7; należy przypiąć CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 tylko wtedy, gdy harness zmierzył zależność od zachowania Opus 4.6. Wykrywanie root-level plugin SKILL.md i widoczność LSP dostarczana przez pluginy zmniejszają niejednoznaczność pakowania. Poprawki MCP_TOOL_TIMEOUT, wcześniej istniejących worktrees sesji w tle, usypiania/wybudzania daemona i czyszczenia po aktualizacji oraz czyszczenia cache pluginów zamykają luki niezawodnościowe, które w przeciwnym razie wyglądają jak błędy orkiestracji.

Sterowanie stop-hook, autorytet między sesjami i multi-agent v2 (czerwiec 2026)

Cztery zmiany z początku czerwca są ważne dla projektowania harness i multi-agent.⁵⁹

Hooks Stop/SubagentStop otrzymały kanał sterowania. Od Claude Code v2.1.163 hook Stop lub SubagentStop może zwrócić hookSpecificOutput.additionalContext, aby przekazać Claude informację zwrotną i utrzymać turę w toku, bez oznaczania odpowiedzi jako błędu hooka. Wcześniej jedyną realną dźwignią Stop hooka była blokada exit-2, która wygląda jak błąd i liczy się do limitu kolejnych blokad. Dla quality-gate harness to czystszy prymityw: Stop hook, który wykryje „powiedziano done, ale testy są czerwone”, może teraz wstrzyknąć „oto co nadal nie działa, kontynuuj” zamiast twardo blokować. Blokady należy używać dla rzeczywistych warunków zatrzymania, a additionalContext dla „jeszcze nie gotowe, oto dlaczego”.

Komunikacja między sesjami nie przenosi już pożyczonego autorytetu. v2.1.166 utwardził przypadek wielu sesji: wiadomości przekazywane przez SendMessage z innej sesji Claude nie przenoszą już autorytetu użytkownika źródłowego, więc sesja odbierająca odmawia przekazanych żądań uprawnień, a tryb auto je blokuje. Jeśli orkiestracja pozwala agentom wysyłać do siebie wiadomości, wiadomość przychodzącą należy traktować jako niezaufane dane, nie jako uwierzytelnioną instrukcję. To ta sama zasada, którą sekcja bezpieczeństwa stosuje do wyniku narzędzi, rozszerzona na komunikację między agentami.

Odporność modelu stała się ustawieniem pierwszej klasy. Ustawienie fallbackModel łączy teraz do trzech modeli zapasowych, próbowanych po kolei, gdy model główny jest przeciążony lub niedostępny, a tura automatycznie ponawia się raz na fallbacku przy nieoczekiwanych nieponawialnych błędach API. Dla długotrwałego autonomicznego harness zmienia to przejściową awarię modelu głównego w łagodną degradację zamiast przerwanego uruchomienia. claude agents --json dodał też pole waitingFor (v2.1.162), które ujawnia, na co czeka zablokowana sesja w tle, na przykład prompt uprawnień — to wygrana obserwowalności dla każdego koordynatora odpytującego flotę agentów.

Safe mode do clean-room governance i rozwiązywania problemów. Claude Code v2.1.169 dodaje flagę --safe-mode (oraz odpowiadającą jej zmienną środowiskową CLAUDE_CODE_SAFE_MODE), która uruchamia sesję z wyłączonymi naraz wszystkimi personalizacjami: CLAUDE.md, plugins, skills, hooks i serwerami MCP.⁶⁰ To odwrotność harness — celowy clean-room. Należy używać tego do odpowiedzi na pytanie, które w końcu zada każdy operator: „czy to zachowanie pochodzi z modelu, czy z czegoś, co skonfigurowano?” Gdy hook uruchamia się błędnie, skill aktywuje się, gdy nie powinien, albo serwer MCP zatruwa kontekst, --safe-mode daje znany pusty punkt odniesienia do porównania. To także prymityw governance: sposób na uruchomienie gołego modelu bez żadnego trwałego autorytetu, który zwykle nadaje harness, co ma znaczenie, gdy trzeba odtworzyć wynik bez wpływu jakiegokolwiek scaffolding zdefiniowanego przez operatora.

Uwaga o poziomach modeli. Ten przewodnik traktuje Opus 4.8 jako agentic default Claude Code — model, który uruchamia autonomiczne harnesses, chyba że wybrano inaczej. Według stanu na 9 czerwca 2026 Anthropic uruchomił Claude Fable 5 (claude-fable-5), nowy poziom powyżej Opus, opisany jako jego najpotężniejszy model — system klasy „Mythos” uczyniony bezpiecznym do ogólnego użytku — wybieralny w Claude Code v2.1.170 przez /model claude-fable-5.⁶⁰ Opus 4.8 pozostaje agentic default; po wyższy poziom należy sięgać celowo, przy decyzjach, gdzie surowa głębia rozumowania uzasadnia koszt, a nie jako ogólne ustawienie dla floty.

Codex dostarczył multi-agent v2. Codex CLI v0.137.0 zachowuje wybór runtime przy każdym wątku, udostępnia czystsze domyślne follow-upy i metadane dla uruchamianych agentów (hide_spawn_agent_metadata ma teraz domyślnie true) oraz propaguje surowe zdarzenia rodzica do listenerów dziecka. Jego model subagent pozostaje jawny: wbudowane typy agentów default/worker/explorer, agenci niestandardowi definiowani w TOML i kontrola współbieżności (agents.max_threads domyślnie 6, agents.max_depth domyślnie 1). To samo wydanie dodaje rozszerzenie skills v1 z rozwiązywaniem katalogu skills per tura i nowymi zdarzeniami lifecycle contributor dla startu wątku/błędu tury, zmniejszając dystans do powierzchni hook/skill Claude Code, przy jednoczesnym utrzymaniu postawy kernel-sandbox jako domyślnej granicy. Codex v0.138.0–v0.139.0 następnie utwardziły multi-agent v2 do produkcji: payloady wiadomości między agentami są teraz szyfrowane, katalog konfiguracji agentów v2 plus LRU rezydencji agentów zarządzają tym, którzy agenci pozostają rezydentni, a współbieżność jest liczona według aktywnego wykonania, nie według uruchomionych wątków, więc bezczynni agenci nie zużywają już slotu.⁶¹ Lifecycle API także dojrzał — close_agent przemianowano na interrupt_agent (v0.139.0), aby odzwierciedlić, że przerywa działającego agenta, a nie tylko zamyka uchwyt — a ostrzeżenia startowe MCP zgłoszone przez subagent pozostają teraz ograniczone do właścicielskiego wątku zamiast duplikować się w transkrypcie rodzica.⁶¹ Dla każdego, kto buduje orkiestrację po stronie Codex, to różnica między demo a flotą: szyfrowany transport wiadomości, ograniczona rezydencja, współbieżność liczona wykonaniem i ostrzeżenia, które nie wyciekają przez granicę wątku. Codex v0.140.0 otworzył następnie przejście między narzędziami: /import selektywnie pobiera setup, konfigurację projektu i ostatnie czaty z Claude Code do Codex, a sesje stały się trwale usuwalne (codex delete / /delete, z zabezpieczeniami potwierdzenia).⁶⁴ /import to pierwsze oficjalne uznanie, że operatorzy przechodzą między harnesses — konfiguracja budowana dla jednego nie jest już w nim uwięziona.

Pamięć i kontekst

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

Trzy mechanizmy załamania w wielu turach

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

Strategia 1: system plików jako pamięć

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

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

Plik MEMORY.md przechowuje błędy, decyzje i wzorce między sesjami. Gdy okaże się, że ((VAR++)) kończy się niepowodzeniem przy set -e w bash, kiedy VAR ma wartość 0, należy to zapisać. Trzy sesje później, gdy pojawi się podobny przypadek brzegowy dotyczący liczb całkowitych w Python, wpis w MEMORY.md ujawni ten wzorzec.¹⁵

Auto Memory (v2.1.32+): Claude Code automatycznie zapisuje i przywołuje kontekst projektu. Podczas pracy Claude zapisuje obserwacje do ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory ładuje pierwsze 200 wierszy do promptu systemowego na początku sesji. Należy zachować zwięzłość i linkować do osobnych plików tematycznych z bardziej szczegółowymi notatkami.⁶

Kuracja pamięci zamiast jej objętości (maj 2026): Niedawny preprint arXiv dotyczący współpracy agentów LLM przedstawia rozszerzone przywoływanie jako możliwy tryb awarii: w eksperymentach autorów dłuższa widoczna historia pogarszała współpracę w 18 z 28 konfiguracji model-gra.⁴⁸ Należy traktować to jako ostrzeżenie projektowe, a nie ostateczne prawo. Reguła produkcyjna jest już wystarczająco jasna: MEMORY.md powinien być krótki, odsyłać do szczegółów i zawierać gotowe do decyzji podsumowania w handoffach. Surowe zrzuty transkrypcji, logi narzędzi i długie strumienie przywołań należą do przeszukiwalnego magazynu, a nie automatycznie do aktywnego promptu.

Strategia 2: proaktywna kompakcja

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

Kiedy wykonywać kompakcję: - Po ukończeniu odrębnego podzadania (wdrożona funkcja, naprawiony błąd) - Przed rozpoczęciem pracy nad nowym obszarem codebase - Gdy Claude zaczyna się powtarzać lub zapominać wcześniejszy kontekst - Mniej więcej co 25-30 minut podczas intensywnych sesji

Niestandardowe instrukcje kompakcji w CLAUDE.md:

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

Kompakcja chroni rozmowę; polecenie /cd (Claude Code v2.1.169) chroni prompt cache. Przenosi sesję do nowego katalogu roboczego w trakcie pracy bez naruszania cache, który nagromadził się w danej turze.⁶⁰ Wcześniej zmiana katalogów oznaczała świeżą sesję i zimny cache. W długiej sesji, która przechodzi z jednego repozytorium do sąsiedniego — co jest typowe w pracy z monorepo i wieloma usługami — /cd utrzymuje kosztowny, buforowany prefiks, jednocześnie przestawiając kontekst systemu plików.

Strategia 3: handoffy sesji

W przypadku zadań rozciągających się na wiele sesji należy tworzyć dokumenty handoff, które przechwytują pełny stan:

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

Struktura Status/Files/Decision/Blocked/Next zapewnia kolejnej sesji pełny kontekst przy minimalnym koszcie tokenów. Rozpoczęcie nowej sesji za pomocą claude -c (continue) albo odczytanie dokumentu handoff prowadzi bezpośrednio do implementacji.¹⁵

Strategia 4: iteracja w świeżym kontekście (Ralph loop)

W przypadku sesji trwających ponad 60-90 minut należy uruchamiać świeżą instancję Claude dla każdej iteracji. Stan utrzymuje się przez system plików, a nie przez pamięć konwersacyjną. 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

Porównanie z pojedynczą długą sesją:

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 ze świeżym kontekstem na każdą iterację wymienia 15-20% narzutu na etap orientacji (odczyt plików stanu, skanowanie historii git) na pełne zasoby poznawcze w każdej iteracji.¹⁶ Rachunek kosztów i korzyści jest następujący: dla sesji krótszych niż 60 minut pojedyncza rozmowa jest bardziej efektywna. Po przekroczeniu 90 minut świeży kontekst daje wynik wyższej jakości mimo narzutu.

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

Managed Agents Claude od Anthropic dodały Dreaming jako Research Preview 6 maja 2026.³⁵ Według Anthropic: „Dreaming is a scheduled process that reviews your agent sessions and memory stores, extracts patterns, and curates memories so your agents improve over time.”³⁵

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 powierzchnią nośną; Dreaming zapisuje wyselekcjonowane wpisy pamięci w magazynie pamięci Managed Agents, który agent odczytuje na początku sesji. Te dwa wzorce współistnieją w harnessach łączących samodzielnie hostowany stan w systemie plików z kuracją po stronie zarządzanej.

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

Antywzorce

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

Trzymanie rozwlekłego outputu błędów w kontekście. Po debugowaniu błędu kontekst zawiera ponad 40 stack trace’ów z nieudanych iteracji. Jedno /compact po naprawieniu błędu usuwa ten zbędny ciężar.

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

Wzorce subagents

Subagents to wyspecjalizowane instancje Claude, które niezależnie obsługują złożone zadania. Zaczynają od czystego kontekstu (bez zanieczyszczeń z głównej rozmowy), działają z określonymi narzędziami i zwracają wyniki jako podsumowania. Wyniki eksploracji nie rozrastają głównej rozmowy; wracają tylko wnioski.⁵

Wbudowane typy subagents

Tworzenie niestandardowych subagents

Subagents definiuje się w .claude/agents/ (projekt) albo ~/.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, zapewniając kompletną izolowaną 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 pracy eksperymentalnej, która mogłaby uszkodzić codebase.

Równoległe subagents

Równoległych subagents warto używać do niezależnych zadań badawczych, które nie muszą ze sobą koordynować pracy:⁵

> 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 agents delegują do agents, które delegują do kolejnych agents, a każdy z nich traci kontekst i zużywa tokeny. Wzorzec recursion guard wymusza 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"

Kluczowa lekcja: należy używać budżetów uruchomień, a nie tylko limitów głębokości. Limity oparte na głębokości śledzą łańcuchy rodzic-dziecko (blokowane na głębokości 3), ale pomijają szerokość: 23 agents na głębokości 1 to nadal „głębokość 1”. Budżet uruchomień śledzi łączną liczbę aktywnych dzieci na rodzica, ograniczoną konfigurowalnym maksimum. Model budżetu odpowiada rzeczywistemu trybowi awarii (zbyt wiele łącznych agents), a nie metryce zastępczej (zbyt wiele poziomów zagnieżdżenia).⁷

Rekurencyjna delegacja jest teraz natywną głębokością. Od Claude Code v2.1.172 (10 czerwca 2026) sub-agents mogą uruchamiać własne sub-agents, zagnieżdżając się do 5 poziomów głębokości — wcześniej delegacja była faktycznie ograniczona do jednego poziomu.⁶² To sprawia, że powyższy recursion guard jest ważniejszy, nie mniej ważny: platforma dopuszcza teraz dokładnie te łańcuchy agents-delegating-to-agents, które zużywają kontekst i tokeny, więc budżet uruchomień oraz limit głębokości powstrzymują 5-poziomowe drzewo przed rozrośnięciem się do setek aktywnych agents. 5 poziomów należy traktować jako pułap dopuszczany przez platformę, nie jako domyślny cel.

Auto mode weryfikuje teraz uruchomienia przed startem. Claude Code v2.1.178 zamknęło lukę w zarządzaniu dopasowaniem: w auto mode uruchomienia subagent są oceniane przez klasyfikator uprawnień przed uruchomieniem subagent, a nie dopiero wtedy, gdy zaczyna wykonywać działania.⁶³ Wcześniej można było uruchomić subagent, aby zażądał działania, którego sesja nadrzędna nie mogłaby wykonać — samo uruchomienie było obejściem. Weryfikacja w momencie uruchomienia oznacza, że recursion guard i model uprawnień wreszcie się spotykają: dziecko nie może służyć jako etap „prania” działania zabronionego przez politykę.

Agent Teams (Research Preview)

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

Włącz za pomocą: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Kiedy używać agent teams zamiast subagents:

Agent View i pętle celu (maj 2026)

Claude Code v2.1.139 dodało Agent View, interfejs w wersji research-preview uruchamiany poleceniem claude agents, który pokazuje z jednego ekranu działające, zablokowane i ukończone sesje Claude Code.⁴²⁴³ Oficjalna dokumentacja przedstawia go jako sposób na wysyłanie i zarządzanie wieloma sesjami, sprawdzanie, co robi każda sesja, oraz identyfikowanie tych, które wymagają działania operatora.⁴³ Daje to pracy multi-agent widok operacyjny, którego końcowe podsumowania nie są w stanie zapewnić.

Agent View warto używać przy promowaniu wzorca subagent lub zespołu: należy sprawdzić, które sesje są zablokowane, które nadal działają i czy rozkład pracy odpowiada zamierzonej architekturze. Nie należy traktować go jako dowodu jakości. To obserwowalność; o tym, czy praca jest solidna, nadal decydują testy, bramki review i raporty dowodowe.

Ta sama wersja dodała /goal, które ustawia warunek ukończenia i pozwala Claude kontynuować pracę przez kolejne tury, aż warunek zostanie spełniony, także w trybach interaktywnym, -p i Remote Control.⁴² /goal należy traktować jako pętlę ukończenia ograniczoną do sesji, a nie jako zamiennik deterministycznych bramek. Przydaje się do utrzymania skupienia agent na celu, ale testy, kontrole cytowań, kontrole wdrożenia i security hooks powinny pozostać oparte na poleceniach lub skryptach tam, gdzie awaria musi blokować dalszy przebieg.

Workflow Tool (v2.1.147+)

Claude Code v2.1.147 dodaje domyślnie wyłączone narzędzie Workflow do deterministycznej orkiestracji multi-agent. Włącza się je przez CLAUDE_CODE_WORKFLOWS=1.⁵² Architektonicznie jest to ważne, ponieważ daje Claude Code natywną prymitywną funkcję orkiestracji dla przepływów, które wcześniej wymagały niestandardowych skryptów dispatcher, stanu mailbox i konwencji koordynacji subagent.

Nie należy usuwać otaczającego go harness. Workflow może strukturyzować wykonanie, ale nie zastępuje modelu bezpieczeństwa. PreToolUse i PostToolUse hooks należy zachować jako warstwę blokującą, budżety uruchomień lub budżety kroków workflow należy zachować, aby zapobiegać niekontrolowanemu rozrostowi szerokości, stan systemu plików powinien pozostać audytowalny, a końcowe raporty dowodowe powinny pozostawać poza samooceną modelu. W praktyce: Workflow służy do kształtu orkiestracji; hooks, testy i bramki review służą do ustalania prawdy.

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ć

Projekt CLAUDE.md

CLAUDE.md to polityka operacyjna dla agenta AI, a nie README dla ludzi.²¹ Agent nie musi rozumieć, dlaczego używa się conventional commits. Musi znać dokładne polecenie do uruchomienia i wiedzieć, jak wygląda stan „gotowe”.

Hierarchia pierwszeństwa

Pliki reguł ładują się automatycznie i zapewniają uporządkowany kontekst bez zaśmiecania CLAUDE.md.⁶

Co jest ignorowane

Te wzorce niezawodnie nie powodują żadnej obserwowalnej zmiany w zachowaniu agenta:²¹

Akapity prozy bez poleceń. „Cenimy czysty, dobrze przetestowany kod” to dokumentacja, nie operacje. Agent to czyta, po czym przechodzi do pisania kodu bez testów, ponieważ nie ma tam wykonalnej instrukcji.

Niejednoznaczne dyrektywy. „Zachowaj ostrożność przy migracjach bazy danych” nie jest ograniczeniem. „Uruchom alembic check przed zastosowaniem migracji. Przerwij, jeśli brakuje ścieżki downgrade.” już nim jest.

Sprzeczne priorytety. „Działaj szybko i szybko dostarczaj” plus „Zapewnij kompleksowe pokrycie testami” plus „Utrzymaj czas działania poniżej 5 minut” plus „Uruchamiaj pełne testy integracyjne przed każdym commitem”. Agent nie może spełnić wszystkich czterech warunków jednocześnie i domyślnie pomija weryfikację.²¹

Przewodniki stylu bez egzekwowania. „Przestrzegaj Google Python Style Guide” bez ruff check --select D nie daje agentowi żadnego mechanizmu weryfikacji 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 domknięcia:

## 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 zorganizowane 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ść pisania

Jeśli zaczyna się od zera, należy dodać sekcje w tej kolejności priorytetów:²¹

1. Polecenia budowania i testowania (agent potrzebuje ich, zanim będzie mógł zrobić cokolwiek użytecznego)
2. Definicja stanu gotowe (zapobiega fałszywym zakończeniom)
3. Reguły eskalacji (zapobiegają destrukcyjnym obejściom)
4. Sekcje zorganizowane według zadań (ograniczają parsowanie nieistotnych instrukcji)
5. Zakresowanie katalogów (monorepo: utrzymuje instrukcje usług w izolacji)

Preferencje stylu warto pominąć, dopóki pierwsze cztery elementy nie działają.

Importy plików

Odwołanie do innych plików w 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: względna (@docs/file.md), bezwzględna (@/absolute/path.md) lub z katalogu domowego (@~/.claude/file.md). Maksymalna głębokość: 5 poziomów importów.⁶

Zgodność instrukcji między narzędziami

AGENTS.md to otwarty standard rozpoznawany przez każde główne narzędzie do kodowania AI.²¹ Jeśli zespół używa wielu narzędzi, należy traktować AGENTS.md jako źródło kanoniczne i odzwierciedlać odpowiednie sekcje w plikach specyficznych dla narzędzi:

Wzorce w AGENTS.md (najpierw polecenia, zdefiniowane domknięcie, organizacja według zadań) działają w dowolnym pliku instrukcji niezależnie od narzędzia. Nie należy utrzymywać równoległych zestawów instrukcji, które rozjeżdżają się z czasem. Warto napisać jedno autorytatywne źródło i je odzwierciedlać.

Uwagi o równoważności Codex

Codex ma już pierwszorzędne odpowiedniki dla głównych warstw harness, ale migracja jest tłumaczeniem wzorców, a nie kopiowaniem plików. Codex czyta AGENTS.md przed rozpoczęciem pracy, nakładając globalne wskazówki z ~/.codex na instrukcje projektu i zagnieżdżonych repozytoriów.³¹ Codex skills używają tego samego modelu myślowego SKILL.md z progresywnym ujawnianiem: Codex zaczyna od nazwy skill, opisu i ścieżki pliku, a pełny skill ładuje dopiero wtedy, gdy zdecyduje się go użyć.³² Codex ma też natywne hooks, hooks dostarczane w pluginach, zarządzane hooks, obsługę MCP oraz jawne przepływy pracy subagents.³³³⁴

Codex v0.138.0–v0.139.0 wzmocnił wykrywanie AGENTS.md dla nietrywialnych przestrzeni roboczych: ładowanie przechodzi teraz przez abstrakcję systemu plików środowiska i zachowuje ścieżki logiczne podczas przechodzenia wykrywania, dzięki czemu wybierany jest właściwy plik nawet wtedy, gdy przestrzeń robocza jest zdalnym systemem plików albo drzewem z dowiązaniami symbolicznymi.⁶¹ Ma to znaczenie zawsze wtedy, gdy kanoniczny AGENTS.md jest autorytatywnym źródłem, a agent działa na zamontowanym, zmaterializowanym w kontenerze albo dowiązanym symbolicznie checkoutcie — czyli w przypadkach, w których naiwne przejście po ścieżkach po cichu wybiera niewłaściwy plik instrukcji albo nie wybiera żadnego. Jeśli jedno autorytatywne AGENTS.md jest odzwierciedlane między usługami, należy traktować to jako minimum do zaufania, że plik faktycznie załadowany przez agenta jest tym, który został napisany.

Codex v0.141.0 wzmocnił następnie samą ścieżkę zdalnego wykonywania: zdalni executorzy łączą się teraz przez uwierzytelnione, szyfrowane end-to-end kanały Noise-relay (płaszczyzna sterowania i executor nie ufają już przekaźnikowi między nimi), zdalne wykonywanie międzyplatformowe zachowuje natywny katalog roboczy i powłokę executora, a TLS akceptuje podpisy certyfikatów P-521 dla proxy enterprise.⁶⁵ Jeśli orkiestracja uruchamia executory Codex przez granicę sieciową, to różnica między założeniem zaufanego przekaźnika a założeniem szyfrowania end-to-end — należy traktować to jako punkt odniesienia dla każdej topologii remote-executor.

Mapowanie praktyczne:

Ważna różnica: subagents Claude mogą być wybierani automatycznie na podstawie opisów, natomiast Codex obecnie dokumentuje przepływy pracy subagentów jako jawne. To sprawia, że skills i hooks są właściwym domyślnym wyborem dla stale aktywnego zachowania harness w Codex; subagents służą do celowej pracy równoległej, review i eksploracji.

Testowanie instrukcji

Należy sprawdzić, czy agent rzeczywiście czyta instrukcje i się do nich stosuje:

# 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?"

Test kwasowy: Poprosić agenta o wyjaśnienie poleceń budowania. Jeśli nie potrafi odtworzyć ich dosłownie, instrukcje są albo zbyt obszerne (treść wypchnięta poza kontekst), zbyt niejasne (agent nie potrafi wydobyć instrukcji możliwych do wykonania), albo nie są wykrywane. Analiza 2 500 repozytoriów przeprowadzona przez GitHub wykazała, że niejasność powoduje większość awarii.²¹

Wzorce produkcyjne

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

Claude Opus 4.7 (16 kwietnia 2026) wprowadzono konkretne możliwości, które zmieniają to, przed czym harness musi się bronić:²⁹

• Odporność na awarie narzędzi: Opus 4.7 kontynuuje działanie mimo awarii narzędzi, które zatrzymywały sesje Opus 4.6. Można ograniczyć — ale nie wyeliminować — defensywne wrappery ponawiania prób w kodzie subagent. Należy zachować zabezpieczenia na poziomie hooks; warto przyciąć scaffolding w promptach w stylu „jeśli narzędzie zawiedzie, spróbuj ponownie trzy razy”.
• Poziom wysiłku xhigh (tylko Opus-4.7): Znajduje się między high a max. Zalecany domyślnie dla obciążeń związanych z kodowaniem i agentic. W długotrwałych subagents xhigh znacząco przewyższa high przy subproporcjonalnym koszcie tokenów. max nadal jest właściwym wyborem dla jednorazowego trudnego rozumowania; xhigh lepiej sprawdza się w zadaniach ciągłych.
• Limit budżetu tokenów: Konfigurowalny dla każdego uruchomienia agenta przez output_config.task_budget (nagłówek beta task-budgets-2026-03-13). Model widzi bieżące odliczanie i płynnie dopasowuje zakres pracy do budżetu, zamiast niespodziewanie go wyczerpać. Warto stosować w pętlach agentic, gdy potrzebny jest przewidywalny koszt tokenów bez obniżania jakości przy krótkich promptach.
• Świadomość potrzeb domyślnych: Pierwszy model Claude, który przechodzi testy „implicit-need” — rozpoznaje, kiedy dosłowne żądanie użytkownika nie doprecyzowuje tego, czego faktycznie potrzebuje. Dzięki temu sekcja „clarifying rules” w CLAUDE.md staje się mniej potrzebna. Jeśli CLAUDE.md zawiera 200 wierszy zabezpieczeń typu „rozważ też X, gdy użytkownik prosi o Y”, należy usunąć te, które model obsługuje już natywnie.

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

Claude Code v2.1.133 dodaje cztery ustawienia poziomu administratorskiego, które warto znać przy produkcyjnych harnesses:³⁹

Przywrócenie zachowania worktree.baseRef warto wyraźnie oznaczyć użytkownikom: agenci, którzy polegali na zachowaniu z wersji v2.1.128-v2.1.132 (worktrees tworzone od lokalnego HEAD), tracą dostęp do niewypchniętej pracy w świeżych worktrees, jeśli nie włączą tego ponownie.

Ankieta zwrotna OTel dla obserwowalności enterprise (8 maja 2026)

Claude Code v2.1.136 dodał CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL, aby ponownie włączyć ankietę jakości w sesji dla organizacji enterprise przechwytujących odpowiedzi przez OpenTelemetry.⁴⁰ Jeśli organizacja wysyła zdarzenia OTel do centralnego stosu obserwowalności, ta zmienna środowiskowa przywraca ankietę do ścieżki danych, dzięki czemu sygnał jakości płynie tym samym pipeline’em co metryki opóźnień i błędów. Należy traktować to jako opt-in: domyślnie ankieta pozostaje wyciszona, co jest właściwe dla wdrożeń bez OTel.

Quality Loop

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

1. Implementacja - Napisać kod
2. Review - Ponownie przeczytać każdy wiersz. Wyłapać literówki, błędy logiczne i niejasne sekcje
3. Ocena - Uruchomić evidence gate. Sprawdzić wzorce, przypadki brzegowe i pokrycie testami
4. Dopracowanie - Naprawić każdy problem. Nigdy nie odkładać na „później”
5. Oddalenie perspektywy - Sprawdzić punkty integracji, importy i sąsiedni kod pod kątem regresji
6. Powtórzenie - Jeśli którekolwiek kryterium evidence gate nie przechodzi, wrócić do kroku 4
7. Raport - Wymienić, co się zmieniło, jak zostało zweryfikowane, i przytoczyć konkretne dowody

Evidence Gate

„Wierzę” i „powinno działać” nie są dowodem. Należy cytować ścieżki plików, wynik testów albo konkretny kod.

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

Ludzka kontrola nad merge

Badanie arXiv z maja 2026 roku dotyczące 29 585 cykli życia pull requestów tworzonych przez agentów AI rozdziela sprawczość operacyjną od nadzoru nad merge.⁴⁷ Lekcja architektoniczna jest prosta: agenci mogą rozpoczynać pracę, prowadzić gałęzie, otwierać PR-y, recenzować pracę i podsumowywać ryzyko, podczas gdy uprawnienie do merge pozostaje osobną granicą governance.

Tę granicę należy wyraźnie zapisać w harness. Agenci mogą przygotowywać PR-y i zbierać dowody; dla merge, wydań i destrukcyjnych operacji na repozytorium należy wymagać zatwierdzenia człowieka, chyba że organizacja ma osobno audytowaną politykę automatyzacji. Gdy automatyzacja wykonuje merge, trzeba zachować logi rozróżniające wykonawcę od człowieka lub polityki, która go autoryzowała.

Wzorce obsługi błędów

Atomowe zapisy plików. Jednoczesny zapis wielu agentów do tego samego pliku stanu uszkadza JSON. Należy zapisywać do plików .tmp, a następnie wykonywać atomowe mv. System operacyjny gwarantuje, że mv jest atomowe w obrębie tego samego systemu plików.¹⁷

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

Odzyskiwanie po uszkodzeniu stanu. Jeśli stan zostanie uszkodzony, wzorzec odzyskiwania odtwarza go z bezpiecznych wartości domyślnych zamiast kończyć działanie błędem:¹⁶

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

Pułapka bash ((VAR++)). ((VAR++)) zwraca kod wyjścia 1, gdy VAR wynosi 0, ponieważ 0++ ewaluje się do 0, co bash traktuje jako fałsz. Przy włączonym set -e zabija to skrypt. Zamiast tego należy używać VAR=$((VAR + 1)).¹⁶

Klasyfikacja zasięgu skutków

Każdą akcję agenta należy sklasyfikować według zasięgu skutków i odpowiednio bramkować:²

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

Specyfikacja zadań dla uruchomień autonomicznych

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

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

Kryteria muszą być weryfikowalne maszynowo: wynik testów pass/fail, wynik lintera, kody statusu HTTP, sprawdzenia istnienia plików. Wczesne zadanie, w którym poproszono agenta, aby „napisał testy, które przechodzą”, dało assert True i assert 1 == 1. Technicznie poprawne. Praktycznie bezwartościowe.¹⁶

Tryby awarii, na które trzeba uważać

Konkretny ślad sesji

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

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

2. Agent czyta PRD i planuje pierwszą story. UserPromptSubmit fires. Dispatcher wstrzykuje: aktywny kontekst projektu, bazę session drift.

3. Agent wywołuje Bash, aby uruchomić testy. PreToolUse:Bash fires. Sprawdzenie poświadczeń, walidacja sandbox, wykrycie projektu. 90 ms. Testy się uruchamiają. PostToolUse:Bash fires: zapisano heartbeat aktywności, sprawdzenie drift.

4. Agent wywołuje Write, aby utworzyć plik. PreToolUse:Write fires: sprawdzenie zakresu pliku. PostToolUse:Write fires: sprawdzenie lint, śledzenie commitów.

5. Agent kończy story. Stop fires. Quality gate sprawdza: czy agent przytoczył dowody? Czy użył języka asekuracyjnego? Czy w diffie są komentarze TODO? Jeśli jakiekolwiek sprawdzenie się nie powiedzie, exit 2 i agent kontynuuje.

6. Niezależna weryfikacja: Świeży agent uruchamia zestaw testów bez ufania samoopisowi poprzedniego agenta.

7. Trzech agentów code review uruchamia się równolegle. Każdy niezależnie recenzuje diff. Jeśli którykolwiek recenzent oznaczy CRITICAL, story wraca do kolejki.

8. Story przechodzi. Ładuje się kolejna story. Cykl powtarza się dla wszystkich 5 stories.

Łączna liczba hooks wywołanych w 5 stories: ~340. Łączny czas w hooks: ~12 sekund. Ten narzut zapobiegł trzem wyciekom poświadczeń, jednemu destrukcyjnemu poleceniu i dwóm niekompletnym implementacjom w trakcie jednego nocnego uruchomienia.

Studium przypadku: nocne przetwarzanie PRD

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

Dwa wycieki poświadczeń wymagały rotacji kluczy API i audytu usług downstream: około 4 godzin reakcji na incydent. Narzut harness, który zapobiegł odpowiednikowi tego zdarzenia, wyniósł 2,4 sekundy bash na story. Wskaźnik fałszywego ukończenia spadł z 35% do 4%, ponieważ Stop hook niezależnie uruchamiał testy, zanim pozwolił agentowi zgłosić zakończenie.

Uwagi dotyczące bezpieczeństwa

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

Anthropic opublikowało formalne ramy wiarygodności agentów 9 kwietnia 2026 roku.²⁷ Pięć zasad odpowiada podejściu Evidence Gate opisanemu w tym przewodniku i je rozszerza:

Anthropic przekazało również MCP do Agentic AI Foundation należącej do Linux Foundation, dołączając do AGENTS.md (obecnie współzarządzanego z OpenAI, Google, Cursor, Factory, Sourcegraph). Standardy interoperacyjności agentów są teraz neutralne względem dostawców.²⁷

Narzędzia sandbox dla skills: W przypadku zespołów, które traktują skills jako powierzchnię ataku, SandyClaw firmy Permiso (uruchomione 2 kwietnia 2026 roku) uruchamia skills w dedykowanym sandbox i dostarcza werdykty oparte na dowodach z detekcji Sigma/YARA/Nova/Snort. To pierwszy produkt w kategorii skill-sandbox.²⁸

Sandbox

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

Minimalny poziom bezpieczeństwa z maja 2026 roku. Claude Code v2.1.149 naprawił obejście uprawnień katalogu roboczego w PowerShell, kilka luk w regułach allow-rule PowerShell i analizie uprawnień ze starymi zmiennymi, a także błąd listy dozwolonych zapisów w sandbox dla git-worktree, który obejmował cały główny katalog repozytorium zamiast tylko współdzielonych wewnętrznych elementów git.⁵³ Jeśli harness dopuszcza PowerShell lub agentów izolowanych przez worktree, należy traktować v2.1.149+ jako minimum i utrzymywać wąskie reguły shell. Szerokie PowerShell(*) oraz wyjątki zapisu dla całego repozytorium są skrótami orkiestracyjnymi, a nie granicami bezpieczeństwa.

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

Kolejny minimalny poziom OpenAI Agents SDK (v0.17.3). Linia 0.17.1-0.17.3 dodała kolejne wzmocnienia sandbox i sesji: limity ekstrakcji archiwów, walidację podścieżek GitRepo, jaśniejsze błędy dostawców sandbox, dane uwierzytelniające punktów montowania poza poleceniami sandbox, odrzucanie względnych katalogów głównych przestrzeni roboczej sandbox oraz obsługę stanu terminala Vercel-sandbox.⁵⁴ Jeśli używane są sandboxy hostowane przez OpenAI lub wspierane przez dostawców, a nie tylko hooks Claude Code, należy traktować 0.17.3 jako bieżące minimum dla wzorców z tej sekcji.

Granice uprawnień

System uprawnień kontroluje operacje na wielu poziomach:

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

Claude Code v2.1.178 rozszerzył reguły uprawnień z poziomu narzędzia na poziom parametru: Tool(param:value) dopasowuje się do parametrów wejściowych narzędzia, a * działa jako symbol wieloznaczny. Kanonicznym przykładem jest Agent(model:opus — reguła blokująca tworzenie subagents na określonym poziomie modelu.⁶³ Architektonicznie zamyka to lukę, której powyższa tabela czterech poziomów nie potrafiła wyrazić: wcześniej można było dopuścić albo odrzucić narzędzie w całości, ale nie dało się ograniczyć sposobu jego wywołania. Polityka governance może teraz powiedzieć „subagents mogą być tworzone, ale nie na poziomie Fable 5” albo „Bash jest dozwolony, ale nie z tą flagą” jako deterministyczną regułę, a nie prośbę na poziomie promptu.

Towarzyszące ustawienie zarządzane, enforceAvailableModels (v2.1.175), ogranicza wybór modelu od góry: przypina model Default i uniemożliwia ustawieniom użytkownika lub projektu rozszerzanie zarządzanej listy dozwolonych availableModels.⁶³ Te dwa mechanizmy się składają — lista dozwolonych określa, które poziomy w ogóle istnieją dla sesji, a reguły na poziomie parametrów ograniczają, jak subagents z nich korzystają.

Zabezpieczenia Auto-Mode przed destrukcyjnymi poleceniami (czerwiec 2026)

Claude Code v2.1.183 zawęził zasięg szkód auto mode dla operacji, które po cichu tracą pracę lub rozbierają środowiska. Auto mode teraz twardo blokuje, o ile nie poproszono o nie jawnie w sesji: destrukcyjne operacje git (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend, gdy commit nie został wykonany przez agenta w tej sesji; oraz demontaż infrastruktury (terraform destroy, pulumi destroy, cdk destroy), chyba że wskazano konkretny stack.⁶⁵ Architektonicznie jest to uzupełnienie powyższej weryfikacji spawn i reguł na poziomie parametrów: zamiast kontrolować, które narzędzie lub jak jest tworzone, mechanizm kontroluje niewielki zestaw konkretnych nieodwracalnych poleceń według intencji — agent nadal może je uruchomić, ale tylko na wyraźne polecenie, a nie z własnej inicjatywy. W autonomicznym harness tę samą zasadę należy zakodować we własnych hooks PreToolUse: polecenia niszczące stan zasługują na regułę domyślnej odmowy, którą znosi tylko jawny sygnał operatora.

Obrona przed prompt injection

Skills i hooks zapewniają wielowarstwową obronę przed prompt injection:

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

allowed-tools: Read, Grep, Glob

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

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

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

Dwa ostrzeżenia z maja 2026 roku wzmacniają ten wzorzec: infrastruktura agentów tworzy nowe miejsca, z których wrażliwe treści i wykonywalna polityka mogą wyciec albo się wydostać. GitHub Advisory GHSA-f3jg-756w-gm35 obejmuje problem filtra payloadów Gryph Agents, w którym wrażliwa zawartość payloadów narzędzi mogła pozostawać w lokalnych logach SQLite przy domyślnym zachowaniu logowania.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p obejmuje ucieczkę z sandbox niestandardowego guardrail kodu LiteLLM w chronionym administracyjnie punkcie końcowym proxy.⁴⁶

Reguła produkcyjna: transkrypty agentów, payloady narzędzi, logi SQLite i wykonywanie guardrail należy traktować jako wrażliwą infrastrukturę. Przed utrwaleniem należy redagować dane, stosować limity retencji i utrzymywać niestandardowy kod guardrail w sandbox oraz w stanie możliwym do przeglądu. Reguła na poziomie promptu „nie loguj sekretów” nie wystarczy; ścieżka logowania i guardrail potrzebuje deterministycznych testów.

Bezpieczeństwo hooks

HTTP hooks, 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łowiekiem a agentem

Bezpieczeństwo w architekturach agentowych wymaga jasnego podziału odpowiedzialności między człowiekiem a agentem:¹⁷

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 hook

Hooks uruchamiają się również dla działań subagent.¹³ Jeśli Claude tworzy subagent przez Agent tool, hooks PreToolUse i PostToolUse wykonują się dla każdego narzędzia używanego przez subagent. Bez rekurencyjnego egzekwowania hook subagent mógłby ominąć bramki bezpieczeństwa. Zdarzenie SubagentStop pozwala uruchomić sprzątanie lub walidację po zakończeniu działania subagent.

To nie jest opcjonalne. Agent, który tworzy subagent bez Państwa hooks bezpieczeństwa, jest agentem zdolnym wykonać force-push do main, odczytać pliki z danymi uwierzytelniającymi albo uruchomić destrukcyjne polecenia, podczas gdy bramki obserwują, jak główna rozmowa nic nie robi.

Koszt jako architektura

Koszt jest decyzją architektoniczną, a nie operacyjną refleksją po fakcie.² Trzy poziomy:

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

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

Poziom architektury. CLI-first zamiast MCP, gdy operacja jest bezstanowa. Wywołanie claude --print dla jednorazowej oceny kosztuje mniej i nie dodaje narzutu połączenia. MCP ma sens, gdy narzędzie potrzebuje trwałego stanu lub streamingu.

Ramy decyzyjne

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

Skills vs Hooks vs Subagents

FAQ

Ile hooks to za dużo?

Ograniczeniem jest wydajność, nie liczba. Każdy hook działa synchronicznie, więc łączny czas wykonania hooks dolicza się do każdego pasującego 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 mniej niż 200 ms. Próg, który warto obserwować: jeśli PostToolUse hook dodaje ponad 500 ms do każdej edycji pliku, sesja zaczyna działać ospale. Przed wdrożeniem hooks należy profilować je 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 hook. Claude widzi powód odrzucenia i proponuje bezpieczniejszą alternatywę. Kod wyjścia 1 jest nieblokującym ostrzeżeniem, przy którym akcja nadal jest wykonywana.³

Gdzie umieszczać 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 typy. 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 wynikiem poniżej 0,70 ogólnej pewności, 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 porażki. Sukces: agenci nie zgadzają się produktywnie i osiągają konsensus. Porażka: agenci dochodzą do zgody zbyt szybko, 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 w 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 rzeczywistego (agenci działają sekwencyjnie przez Agent tool). Deliberation z 10 agentami dodaje 2-4 minuty. Hooks consensus i pride check działają każdy w mniej niż 200 ms. Głównym wąskim gardłem jest czas inferencji LLM na agenta, nie narzut orkiestracji.⁷

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

Każdą sekcję należy utrzymać poniżej 50 linii, a cały plik poniżej 150 linii. Długie pliki są obcinane przez okna kontekstu, dlatego na początku należy umieścić najważniejsze instrukcje: polecenia i definicje domknięcia przed preferencjami stylu.²¹

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

Zasady architektoniczne (hooks jako deterministyczne bramki, skills jako ekspertyza domenowa, subagents jako izolowane konteksty, system plików jako pamięć) koncepcyjnie odnoszą się do każdego systemu agentowego. Konkretna implementacja wykorzystuje zdarzenia cyklu życia Claude Code, wzorce 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 narzędzia.

Szybka karta referencyjna

Konfiguracja hooks

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