Architektura Agent Harness 2026: Przewodnik po diagramach

TL;DR: Claude Code to nie jest okno czatu z dostępem do plików. To programowalny runtime z 22 zdarzeniami cyklu życia, z których każde można podpiąć za pomocą skryptów powłoki, których model nie może pominąć. Złóż hooks w dispatchery, dispatchery w skills, skills w agents, agents w workflows — i otrzymasz autonomiczny harness deweloperski, który wymusza ograniczenia, deleguje pracę, przechowuje pamięć między sesjami i orkiestruje wieloagentową deliberację. Ten przewodnik obejmuje każdą warstwę tego stosu: od pojedynczego hooka po system konsensusu 10 agentów. Zero frameworków. Wyłącznie bash i JSON.

Andrej Karpathy ukuł termin na to, co narasta wokół agenta LLM: claws (pazury). Hooks, skrypty i orkiestracja, które pozwalają agentowi chwycić świat poza jego oknem kontekstu.¹ Większość deweloperów traktuje agentów AI do kodowania jako interaktywnych asystentów. Wpisują prompt, obserwują edycję pliku i idą dalej. Takie podejście ogranicza produktywność do tego, co można osobiście nadzorować.

Model mentalny oparty na infrastrukturze jest inny: agent AI do kodowania to programowalny runtime z jądrem LLM. Każda akcja modelu przechodzi przez hooks, które kontrolujesz. Definiujesz polityki, nie prompty. Model działa w ramach Twojej infrastruktury tak samo, jak serwer WWW działa w ramach reguł nginx. Nie siadasz przy nginx i nie wpisujesz żądań. Konfigurujesz go, wdrażasz i monitorujesz.

To rozróżnienie ma znaczenie, ponieważ infrastruktura się kumuluje. Hook blokujący dane uwierzytelniające w poleceniach bash chroni każdą sesję, każdego agenta, każde autonomiczne uruchomienie. Skill kodujący kryteria ewaluacji stosuje się konsekwentnie — niezależnie od tego, czy wywołujesz go Ty, czy agent. Agent przeglądający kod pod kątem bezpieczeństwa uruchamia te same kontrole bez względu na to, czy obserwujesz, czy nie.²

Kluczowe wnioski

• Hooks gwarantują wykonanie; prompty — nie. Hooks należy stosować do lintowania, formatowania, kontroli bezpieczeństwa i wszystkiego, co musi się uruchomić za każdym razem, niezależnie od zachowania modelu. Kod wyjścia 2 blokuje akcje. Kod wyjścia 1 jedynie ostrzega.³
• Skills kodują wiedzę domenową, która aktywuje się automatycznie. Pole description decyduje o wszystkim. Claude wykorzystuje rozumowanie LLM (nie dopasowanie słów kluczowych), aby zdecydować, kiedy zastosować dany skill.⁴
• Subagents zapobiegają rozdęciu kontekstu. Izolowane okna kontekstu do eksploracji i analizy utrzymują główną sesję w zwartej formie. Równolegle może działać do 10.⁵
• Pamięć rezyduje w systemie plików. Pliki przetrwają między oknami kontekstu. CLAUDE.md, MEMORY.md, katalogi rules i dokumenty handoff tworzą ustrukturyzowany system pamięci zewnętrznej.⁶
• Wieloagentowa deliberacja wychwytuje martwe punkty. Pojedynczy agent nie jest w stanie zakwestionować własnych założeń. Dwóch niezależnych agentów o różnych priorytetach ewaluacji wychwytuje błędy strukturalne, których quality gates nie są w stanie wykryć.⁷
• Wzorzec harness to cały system. CLAUDE.md, hooks, skills, agents i pamięć to nie niezależne funkcje. Składają się w deterministyczną warstwę między Tobą a modelem, która skaluje się wraz z automatyzacją.

Jak korzystać z tego przewodnika

Każda sekcja bazuje na poprzedniej. Framework decyzyjny na końcu stanowi tabelę referencyjną do wyboru odpowiedniego mechanizmu dla danego typu problemu.

Pięciominutowa ścieżka złota

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

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

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

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

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

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

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

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

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

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

Krok 3: Uruchomienie subagenta (30 sekund)

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

Co zostało uzyskane

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

Dlaczego architektura agentów ma znaczenie

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

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

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

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

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

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

Wzorzec harness

Harness nie jest frameworkiem. To wzorzec: kompozycyjny zestaw plików, skryptów i konwencji, który opakowuje agenta AI do kodowania w 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 z regułami definiują to, co agent wie o Pana/Pani projekcie. Wczytują się automatycznie na początku sesji oraz po każdej kompakcji. Jest to długoterminowa pamięć architektoniczna agenta.

Warstwa rozszerzeń: Skills dostarczają wiedzy dziedzinowej, która uaktywnia 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. Niestandardowi agenci dostarczają wyspecjalizowane konfiguracje subagentów.

Warstwa orkiestracji: Wzorce wieloagentowe koordynują niezależnych agentów na potrzeby badań, przeglądów i deliberacji. Limity spawnowania zapobiegają niekontrolowanej rekurencji. Walidacja przez konsensus zapewnia jakość.

Kluczowa obserwacja: większość użytkowników pracuje wyłącznie w warstwie podstawowej (Core Layer), obserwując puchnący kontekst i rosnące koszty. Zaawansowani użytkownicy konfigurują warstwy instrukcji i rozszerzeń, a warstwę podstawową wykorzystują wyłącznie do orkiestracji i podejmowania finalnych decyzji.²

Harness zarządzany a samodzielnie hostowany (kwiecień 2026)

Przez większą część wczesnego 2026 roku ścieżka „zbuduj własny harness” była jedyną realną opcją. W kwietniu 2026 sytuacja uległa zmianie. 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 OpenAI Agents SDK (16 kwietnia) sformalizowała ten sam podział — harness i compute jako osobne warstwy, z natywnymi dostawcami sandboxów (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) oraz mechanizmem snapshot/rehydrate umożliwiającym przetrwanie utraty kontenera.²³²⁴

Rozwidlenie architektoniczne stało się faktem:

Kiedy wybrać które rozwiązanie: samodzielny hosting pozostaje właściwym wyborem dla zespołów, które dysponują już zapleczem infrastrukturalnym, chcą mieć kontrolę nad skills i hooks lub optymalizują konkretny przepływ pracy w głąb. Rozwiązanie zarządzane jest odpowiednie dla zespołów bez dedykowanych inżynierów platformowych, gdy czas do wartości liczy się bardziej niż możliwości dostosowania, lub gdy uruchomienia agentów muszą niezawodnie przetrwać zamknięcie laptopa, bez konieczności samodzielnego budowania warstwy trwałości. Oba podejścia są kompatybilne — można uruchomić samodzielnie hostowany harness, który deleguje konkretne długotrwałe 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 pełni konkretną funkcję. Drzewo ~/.claude/ to osobista infrastruktura, która obowiązuje we wszystkich projektach. Drzewo .claude/ w każdym repozytorium jest specyficzne dla projektu i współdzielone przez git. Razem tworzą kompletny harness.

System skills

Skills są rozszerzeniami wywoływanymi przez model. Claude odkrywa je i stosuje automatycznie na podstawie kontekstu, bez konieczności ich jawnego wywoływania.⁴ Moment, w którym zauważa Pan/Pani, że raz po raz ponownie wyjaśnia ten sam kontekst między sesjami, to moment, w którym warto zbudować skill.

Kiedy zbudować skill

Skills służą wiedzy, którą Claude ma zawsze do dyspozycji. Slash commands służą akcjom jawnie wyzwalanym przez użytkownika. Wybierając między nimi, warto zadać pytanie: „Czy Claude ma to stosować automatycznie, czy to ja mam decydować, kiedy to uruchomić?”

Tworzenie skill

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

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

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

# Code Review Expertise

## Kontrole bezpieczeństwa
Podczas przeglądu kodu należy zweryfikować:

### Walidacja danych wejściowych
- Wszystkie dane wejściowe użytkownika sanityzowane przed operacjami na bazie danych
- Zapytania sparametryzowane (brak interpolacji ciągów znaków w SQL)
- Kodowanie danych wyjściowych dla renderowanej zawartości HTML

### Uwierzytelnianie
- Tokeny sesji walidowane przy każdym chronionym punkcie końcowym
- Kontrole uprawnień przed mutacjami danych
- Brak zakodowanych na stałe poświadczeń lub kluczy API w kodzie źródłowym

Dokumentacja frontmatter

Pole description to podstawa

Na początku sesji Claude Code wyodrębnia name i description każdego skill i wprowadza je do kontekstu Claude. Gdy użytkownik wysyła wiadomość, Claude wykorzystuje rozumowanie modelu językowego, aby ustalić, czy któryś ze skills jest istotny. Niezależna analiza źródła Claude Code potwierdza ten mechanizm: opisy skills są wprowadzane do sekcji available_skills promptu systemowego, a model używa standardowego rozumienia języka do wyboru odpowiednich skills.¹⁰

Zły opis:

description: Helps with code

Skuteczny opis:

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

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

Budżet kontekstu

Wszystkie opisy skills dzielą wspólny budżet kontekstu, który skaluje się dynamicznie na poziomie 2% okna kontekstowego, z wartością zapasową 16 000 znaków.⁴ Przy wielu skills warto utrzymywać każdy opis zwięzłym. Można nadpisać budżet za pomocą zmiennej środowiskowej SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ ale lepszym rozwiązaniem są krótsze, bardziej precyzyjne opisy. Polecenie /context podczas sesji pozwala sprawdzić, czy jakieś skills zostały wykluczone.

Pliki wspierające 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

Odwołania do nich z poziomu SKILL.md realizuje się za pomocą linków względnych. Claude odczytuje te pliki na żądanie, gdy skill się aktywuje. Warto utrzymywać SKILL.md poniżej 500 linii i przenosić szczegółowe materiały referencyjne do plików wspierających.¹²

Udostępnianie skills przez Git

Skills projektowe (.claude/skills/ w katalogu głównym repozytorium) są udostępniane za pośrednictwem kontroli wersji:⁴

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

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

Skills jako biblioteka promptów

Poza skills o pojedynczym przeznaczeniu, struktura katalogu działa jako zorganizowana 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 wiedzy eksperckiej. Razem tworzą bazę wiedzy, z której Claude czerpie automatycznie w zależności od kontekstu. Młodszy programista otrzymuje wskazówki na poziomie seniora, nawet o nie nie prosząc.

Skills łączą się z hooks

Skills mogą definiować własne hooks we frontmatter, które aktywują się tylko podczas działania danego skill. Tworzy to zachowanie specyficzne dla domeny, które nie zanieczyszcza 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 poprzez hooks SessionStart, wprowadzając ograniczenia jakościowe do każdej sesji bez jawnego wywołania. Sam skill to wiedza. Hook to egzekwowanie. Razem tworzą warstwę polityki.

Typowe błędy w skills

Zbyt szerokie opisy. Skill git-rebase-helper aktywujący się na każdy prompt związany z git (rebase, merge, cherry-pick, nawet git status) zanieczyszcza kontekst w 80% sesji. Rozwiązaniem jest zawężenie opisu lub dodanie disable-model-invocation: true i wymaganie jawnego wywołania /skill-name.⁴

Zbyt wiele skills konkurujących o budżet. Większa liczba skills oznacza więcej opisów konkurujących o 2% budżetu kontekstu. Jeśli zauważy się, że skills się nie aktywują, warto sprawdzić /context pod kątem wykluczonych. Lepiej postawić na mniejszą liczbę dobrze opisanych skills niż wiele niejasnych.

Krytyczne informacje ukryte w plikach wspierających. Claude natychmiast odczytuje SKILL.md, ale do plików wspierających sięga dopiero w razie potrzeby. Jeśli krytyczne informacje znajdują się w pliku wspierającym, Claude może ich nie znaleźć. Istotne informacje należy umieszczać bezpośrednio w SKILL.md.⁴

Architektura hooków

Hooki to polecenia powłoki wyzwalane przez zdarzenia cyklu życia Claude Code.³ Działają poza LLM jako zwykłe skrypty, a nie prompty interpretowane przez model. Model chce uruchomić rm -rf /? 10-liniowy skrypt bash sprawdza polecenie pod kątem 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 ponad 26 zdarzeń cyklu życia w siedmiu kategoriach (lista zdarzeń rośnie z każdym wydaniem — pełna aktualna tabela znajduje się w ściądze):¹³

Semantyka kodów wyjścia

Kody wyjścia określają, czy hooki blokują akcje:³

Kluczowe: Każdy hook bezpieczeństwa musi używać exit 2, a nie exit 1. Exit 1 to ostrzeżenie nieblokujące. Niebezpieczne polecenie nadal się wykona. Jest to najczęstszy błąd związany z hookami w zespołach.¹⁴

Konfiguracja hooków

Hooki znajdują się w plikach ustawień. Poziom projektu (.claude/settings.json) dla hooków współdzielonych. Poziom użytkownika (~/.claude/settings.json) dla 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 to wyrażenie regularne dopasowujące nazwy narzędzi: Bash, Write, Edit, Read, Glob, Grep, Agent lub * dla wszystkich narzędzi. Należy używać "" (pustego ciągu) dla zdarzeń bez narzędzi, takich jak UserPromptSubmit.

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

Hooki 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"
}

Dla zaawansowanej kontroli hooki PreToolUse mogą zwracać JSON w celu modyfikacji wejścia narzędzia, wstrzykiwania kontekstu lub podejmowania decyzji o uprawnieniach. Należy używać opakowania 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 rodzaje gwarancji

Przed napisaniem jakiegokolwiek hooka warto zadać pytanie: jakiego rodzaju gwarancji potrzebuję?¹⁴

Gwarancje formatowania zapewniają spójność po fakcie. Hooki PostToolUse dla Write/Edit uruchamiają formater po każdej zmianie pliku. Wyjście modelu nie ma znaczenia, ponieważ formater 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 akcjom przed ich wykonaniem. Hooki PreToolUse dla Bash badają polecenia i blokują destrukcyjne wzorce z 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 weryfikują stan w punktach decyzyjnych. Hooki PreToolUse dla poleceń git commit uruchamiają linter lub zestaw testów i blokują commit, jeśli kontrole jakości zawodzą:

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

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

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

Claude Code obsługuje cztery typy hooków:¹³

Hooki poleceń (type: "command") uruchamiają skrypty powłoki. Szybkie, deterministyczne, bez kosztu tokenów.

Hooki promptów (type: "prompt") wysyłają jednoturowy prompt do szybkiego modelu Claude. Model zwraca { "ok": true }, aby zezwolić, lub { "ok": false, "reason": "..." }, aby zablokować. Stosuje się je do niuansowej oceny, której nie da się wyrazić wyrażeniem regularnym.

Hooki agentów (type: "agent") uruchamiają subagenta z dostępem do narzędzi (Read, Grep, Glob) do wieloturowej weryfikacji. Stosuje się je, gdy sprawdzanie wymaga inspekcji rzeczywistych plików lub wyjścia testów:

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

Hooki HTTP (type: "http") wysyłają wejście JSON zdarzenia jako żądanie POST na adres URL i otrzymują z powrotem JSON. Stosuje się je 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
          }
        ]
      }
    ]
  }
}

Hooki asynchroniczne

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

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

Tryb asynchroniczny stosuje się do powiadomień, telemetrii i kopii zapasowych. Nigdy nie należy używać trybu asynchronicznego do formatowania, walidacji ani niczego, co musi się zakończyć przed kolejną akcją.

Dispatchery zamiast niezależnych hooków

Uruchamianie siedmiu hooków wyzwalanych jednocześnie przy tym samym zdarzeniu, z których każdy niezależnie odczytuje stdin, tworzy warunki wyścigu. Dwa hooki zapisujące jednocześnie do tego samego pliku stanu JSON obetną JSON. Każdy kolejny hook parsujący ten plik zostanie uszkodzony.²

Rozwiązanie: jeden dispatcher na zdarzenie, który uruchamia hooki 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. Testowanie skryptów niezależnie. Należy przekazać przykładowy JSON przez potok: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Wykorzystanie stderr dla danych debugowania. Stderr z kodu wyjścia 2 jest przekazywany z powrotem do Claude jako komunikat błędu. Nieblokujący stderr (exit 1, 3, itp.) pojawia się tylko w trybie verbose (Ctrl+O).
3. Uważanie na błędy jq. Nieprawidłowe ścieżki JSON zwracają null po cichu. Wyrażenia jq warto testować na rzeczywistym wejściu narzędzia.
4. Weryfikacja kodów wyjścia. Hook PreToolUse używający exit 1 zapewnia zerowe egzekwowanie, jednocześnie pozornie działając.
5. Utrzymywanie szybkości hooków. Hooki działają synchronicznie. Wszystkie hooki powinny działać poniżej 2 sekund, najlepiej poniżej 500ms.

Pamięć i kontekst

Każda rozmowa z AI odbywa się w ramach skończonego okna kontekstu. W miarę rozrastania się rozmowy system kompresuje wcześniejsze tury, aby zrobić miejsce na nową treść. Kompresja jest stratna. Decyzje architektoniczne udokumentowane w turze 3 mogą nie przetrwać do tury 15.⁹

Trzy mechanizmy załamania wieloturowego

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

Strategia 1: System plików jako pamięć

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

~/.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 rejestruje błędy, decyzje i wzorce z wielu sesji. Gdy odkryje się, że ((VAR++)) zawodzi z set -e w bashu, kiedy VAR wynosi 0, należy to zapisać. Trzy sesje później, napotykając podobny przypadek brzegowy dla liczb całkowitych w Python, wpis z MEMORY.md ujawnia ten wzorzec.¹⁵

Auto Memory (v2.1.32+): Claude Code automatycznie rejestruje i przywołuje kontekst projektu. Podczas pracy Claude zapisuje obserwacje do ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory wczytuje pierwsze 200 wierszy do promptu systemowego na początku sesji. Warto zachować zwięzłość i odsyłać do osobnych plików tematycznych w celu uzyskania szczegółowych notatek.⁶

Strategia 2: Proaktywna kompaktacja

Polecenie /compact w Claude Code podsumowuje rozmowę i zwalnia przestrzeń kontekstu, zachowując jednocześnie kluczowe decyzje, zawartość plików i stan zadań.¹⁵

Kiedy wykonywać kompaktację: - Po ukończeniu odrębnego podzadania (wdrożona funkcja, naprawiony błąd) - Przed rozpoczęciem pracy w nowym obszarze bazy kodu - Gdy Claude zaczyna się powtarzać lub zapominać o wcześniejszym kontekście - Mniej więcej co 25–30 minut podczas intensywnych sesji

Niestandardowe instrukcje kompaktacji w CLAUDE.md:

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

Strategia 3: Przekazywanie sesji

W przypadku zadań rozciągających się na wiele sesji warto tworzyć dokumenty przekazania, które ujmują pełen 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 poleceniem claude -c (continue) lub odczytanie dokumentu przekazania pozwala przejść od razu do implementacji.¹⁵

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

Dla sesji przekraczających 60–90 minut należy uruchamiać świeżą instancję Claude na każdą iterację. Stan trwa dzięki systemowi plików, a nie pamięci konwersacyjnej. 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 „świeży kontekst na iterację” wymienia 15–20% narzutu na krok orientacyjny (odczyt plików stanu, skanowanie historii git) w zamian za pełne zasoby poznawcze na iterację.¹⁶ Bilans kosztów i korzyści: dla sesji krótszych niż 60 minut pojedyncza rozmowa jest bardziej wydajna. Powyżej 90 minut świeży kontekst daje wyższej jakości wyniki pomimo narzutu.

Antywzorce

Wczytywanie całych plików, gdy potrzeba 10 wierszy. Pojedynczy odczyt pliku o 2000 wierszach zużywa 15 000–20 000 tokenów. Warto używać przesunięć wierszy: Read file.py offset=100 limit=20 pozwala zaoszczędzić zdecydowaną większość tego kosztu.¹⁵

Utrzymywanie rozwlekłych komunikatów błędów w kontekście. Po debugowaniu błędu kontekst zawiera ponad 40 śladów stosu z nieudanych iteracji. Jedno polecenie /compact po naprawie błędu uwalnia ten martwy balast.

Rozpoczynanie każdej sesji od odczytania wszystkich plików. Lepiej pozwolić narzędziom glob i grep w Claude Code odnajdywać odpowiednie pliki na żądanie, oszczędzając ponad 100 000 tokenów zbędnego wstępnego wczytywania.¹⁵

Wzorce subagentów

Subagenci to wyspecjalizowane instancje Claude, które obsługują złożone zadania niezależnie. Uruchamiają się z czystym kontekstem (bez zanieczyszczeń z głównej rozmowy), działają ze ściśle określonymi narzędziami i zwracają wyniki w formie podsumowań. Wyniki eksploracji nie rozdymają głównej rozmowy; powracają tylko wnioski.⁵

Wbudowane typy subagentów

Tworzenie własnych subagentów

Należy definiować subagentów w .claude/agents/ (projekt) lub ~/.claude/agents/ (osobiste):

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

You are a senior security engineer reviewing code for vulnerabilities.

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

Focus on actionable security findings, not style issues.

Pola konfiguracji subagenta

Izolacja worktree

Subagenci mogą działać w tymczasowych worktree’ach git, zapewniając kompletną, odizolowaną kopię repozytorium:⁵

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

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

Izolacja worktree jest niezbędna przy pracach eksperymentalnych, które mogłyby uszkodzić bazę kodu.

Równoległe subagenty

Claude Code obsługuje do 10 równoległych subagentów.⁵ Warto korzystać z wykonywania równoległego dla niezależnych zadań badawczych:

> 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 kontekstowym, znajduje istotny kod i zwraca podsumowanie. Główny kontekst pozostaje czysty.

Zabezpieczenie przed rekurencją

Bez limitów spawnowania agenci delegują zadania agentom, którzy delegują je kolejnym agentom, przy czym każdy z nich traci kontekst i zużywa tokeny. Wzorzec zabezpieczenia przed rekurencją 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 stosować budżety spawnowania, a nie tylko limity głębokości. Limity oparte na głębokości śledzą łańcuchy rodzic-dziecko (blokowane na głębokości 3), ale pomijają szerokość: 23 agentów na głębokości 1 to wciąż „głębokość 1”. Budżet spawnowania śledzi całkowitą liczbę aktywnych dzieci na rodzica, z limitem ustawianym konfiguracyjnie. Model budżetowy odpowiada faktycznemu trybowi awarii (zbyt wielu agentów ogółem), a nie metryce zastępczej (zbyt wiele poziomów zagnieżdżenia).⁷

Agent Teams (podgląd badawczy)

Agent Teams koordynują wiele instancji Claude Code, które pracują niezależnie, komunikują się za pośrednictwem wspólnej skrzynki odbiorczej i listy zadań oraz mogą kwestionować swoje ustalenia:⁵

Włączenie: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Kiedy stosować agent teams zamiast subagentów:

Orkiestracja wieloagentowa

Systemy AI jednoagentowe mają strukturalną ślepą plamkę: 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ł 7 kwietnia otwarty kod Scion — wieloagentowy hipernadzorca, który uruchamia Claude Code, Gemini CLI oraz inne „głębokie agenty” jako współbieżne procesy, każdy z izolowanym kontenerem, git worktree i poświadczeniami. Działa lokalnie, jako hub lub na Kubernetes. Jawna filozofia: „izolacja zamiast ograniczeń” — agenty działają z wysoką autonomią wewnątrz granic egzekwowanych na warstwie infrastrukturalnej, a nie w promptach.²⁵ Rozszerza to bezpośrednio argument izolacji subagents na różnych dostawców narzędzi. Jeśli pracuje Pan/Pani w workflow obejmującym Claude oraz modele OpenAI, Scion jest pierwszą rzeczywistą referencyjną implementacją międzynarzędziowych subagents z izolacją worktree + poświadczeń na agenta.

Debata nie jest srebrną kulą: Klaster badawczy M3MAD-Bench (początek 2026) wykazał, że wieloagentowa debata osiąga plateau i może zostać zaburzona przez wprowadzający w błąd konsensus — trafne argumenty przegrywają, gdy inni agenci pewnie twierdzą błędną odpowiedź.²⁶ Tool-MAD poprawia ten mechanizm, dając każdemu agentowi heterogeniczny dostęp do narzędzi i stosując wyniki Faithfulness/Relevance w fazie oceny sędziowskiej. Budując orkiestrację typu debata, warto zainwestować w (a) heterogeniczność narzędzi na agenta oraz (b) ilościową ocenę sędziowską, zamiast zakładać, że więcej agentów = lepsze odpowiedzi.

Minimalna opłacalna deliberacja

Należy zacząć od 2 agentów i 1 reguły: agenci muszą dokonać oceny niezależnie, zanim zobaczą swoje prace nawzajem.⁷

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 wnosi już tylko przyrostową poprawę.

Wyzwalacz pewności

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

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

Wynik mapuje się na trzy poziomy:

Próg adaptuje się do typu zadania. Decyzje dotyczące bezpieczeństwa wymagają konsensusu 0,85. Zmiany w dokumentacji potrzebują tylko 0,50. Zapobiega to przeinżynierowaniu prostych zadań, jednocześnie zapewniając, że ryzykowne decyzje podlegają wnikliwej analizie.⁷

Maszyna stanów

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

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

RESEARCH: Niezależni agenci badają temat. Każdy agent otrzymuje inną personę (Technical Architect, Security Analyst, Performance Engineer i inne). Izolacja kontekstu zapewnia, że agenci nie mogą widzieć wzajemnych ustaleń podczas badań.

DELIBERATION: Agenci widzą wszystkie ustalenia badawcze i generują alternatywy. Agent Debate identyfikuje konflikty. Agent Synthesis łączy niesprzeczne ustalenia.

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

Architektura walidacji 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 deliberacyjnego: 1. Faza musi osiągnąć co najmniej RANKING 2. Minimum 2 agentów ukończyło pracę (konfigurowalne) 3. Wynik konsensusu spełnia próg adaptowany do zadania 4. Jeśli którykolwiek agent wyraził sprzeciw, obawy muszą zostać udokumentowane

Bramka 2: Pride Check (hook Stop). Uruchamia się przed zamknięciem sesji: 1. Różnorodne metody: reprezentacja wielu unikalnych person 2. Przejrzystość sprzeczności: sprzeciwy mają udokumentowane uzasadnienie 3. Obsługa złożoności: wygenerowane 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 początkową

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

Dlaczego zgoda jest niebezpieczna

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

Wu i in. przetestowali, czy agenci LLM potrafią prawdziwie debatować, i odkryli, że bez strukturalnych zachęt do niezgody agenci zbiegają się w stronę odpowiedzi brzmiącej najpewniej, niezależnie od jej poprawności.¹⁹ Liang i in. zidentyfikowali pierwotną przyczynę jako „Degeneration-of-Thought”: gdy LLM ustanowi pewność co do stanowiska, autorefleksja nie potrafi wygenerować nowych kontrargumentów, co czyni ocenę wieloagentową strukturalnie niezbędną.²⁰

Niezależność jest krytycznym ograniczeniem projektowym. Dwaj agenci oceniający tę samą strategię wdrożeniową z wglądem we wzajemne ustalenia uzyskali wyniki 0,45 i 0,48. Ci sami agenci bez wglądu: 0,45 i 0,72. Różnica między 0,48 a 0,72 to koszt zjawiska stadnego.⁷

Wykrywanie fałszywej zgody

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

Klastrowanie wyników: Każdy agent oceniający w zakresie 0,3 punktu w skali 10-punktowej sygnalizuje skażenie wspólnym kontekstem, a nie niezależną ocenę. Gdy pięciu agentów oceniających refaktor uwierzytelniania oceniło ryzyko bezpieczeństwa w przedziale 7,1-7,4, ponowne uruchomienie ze świeżą izolacją kontekstu rozproszyło wyniki do 5,8-8,9.

Szablonowy sprzeciw: Agenci kopiujący język obaw innych zamiast generować niezależne zastrzeżenia.

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

Detektor konformizmu wychwytuje oczywiste przypadki (około 10-15% deliberacji, w których agenci zbyt szybko się zbiegają). Dla pozostałych 85-90% bramki consensus i pride check zapewniają wystarczającą walidację.

Co nie zadziałało w deliberacji

Swobodne rundy debat. Trzy rundy tam i z powrotem w formie tekstowej dla dyskusji o indeksowaniu bazy danych wyprodukowały 7500 tokenów debaty. Runda 1: prawdziwa niezgoda. Runda 2: powtórzenie stanowisk. Runda 3: identyczne argumenty innymi słowami. Ustrukturyzowana ocena wymiarowa zastąpiła swobodną debatę, obniżając koszt o 60% przy jednoczesnej poprawie jakości rankingu.⁷

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

Koszt deliberacji

Każdy agent badawczy przetwarza około 5000 tokenów kontekstu i generuje 2000-3000 tokenów ustaleń. Przy 3 agentach daje to 15 000-24 000 dodatkowych tokenów na decyzję. Przy 10 agentach — około 50 000-80 000 tokenów.⁷

W aktualnej cenie Opus 3-agentowa deliberacja kosztuje około 0,68-0,90 USD. 10-agentowa deliberacja kosztuje 2,25-3,00 USD. System wyzwala deliberację dla około 10% decyzji, więc zamortyzowany koszt we wszystkich decyzjach wynosi 0,23-0,30 USD na sesję. To, czy jest to tego warte, zależy od tego, ile kosztuje zła decyzja.

Kiedy deliberować

Projektowanie pliku CLAUDE.md

CLAUDE.md to polityka operacyjna dla agenta AI, a nie README dla ludzi.²¹ Agent nie musi rozumieć, dlaczego stosuje się konwencjonalne commity. Musi natomiast znać dokładne polecenie do uruchomienia oraz wiedzieć, jak wygląda stan „ukończone”.

Hierarchia pierwszeństwa

Pliki z regułami ładują się automatycznie i dostarczają ustrukturyzowanego kontekstu bez zaśmiecania pliku CLAUDE.md.⁶

Co jest ignorowane

Poniższe wzorce w sposób przewidywalny nie powodują żadnej obserwowalnej zmiany w zachowaniu agenta:²¹

Akapity tekstu pozbawione poleceń. „Cenimy czysty, dobrze przetestowany kod” to dokumentacja, a nie operacje. Agent przeczyta to i przejdzie do pisania kodu bez testów, ponieważ nie ma tu żadnej instrukcji nadającej się do wykonania.

Niejednoznaczne dyrektywy. „Zachowuj ostrożność przy migracjach bazy danych” to nie ograniczenie. Natomiast „Uruchomić alembic check przed zastosowaniem migracji. Przerwać, jeśli brakuje ścieżki downgrade” — owszem.

Sprzeczne priorytety. „Działać szybko i szybko dostarczać” plus „Zapewniać kompleksowe pokrycie testami” plus „Utrzymać czas wykonania poniżej 5 minut” plus „Uruchamiać pełne testy integracyjne przed każdym commitem”. Agent nie jest w stanie spełnić wszystkich czterech jednocześnie i domyślnie pomija weryfikację.²¹

Przewodniki stylu bez egzekwowania. „Stosować się do Google Python Style Guide” bez ruff check --select D nie daje agentowi żadnego mechanizmu weryfikacji zgodności.

Co działa

Instrukcje oparte na poleceniach:

## 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 uporządkowane według zadań:

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

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

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

Reguły eskalacji:

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

Kolejność pisania

Rozpoczynając od zera, warto dodawać sekcje w następującej kolejności priorytetów:²¹

1. Polecenia budowania i testowania (agent potrzebuje ich, zanim będzie mógł zrobić cokolwiek użytecznego)
2. Definicja ukończenia (zapobiega fałszywym deklaracjom zakończenia)
3. Reguły eskalacji (zapobiegają destrukcyjnym obejściom)
4. Sekcje uporządkowane według zadań (redukują przetwarzanie nieistotnych instrukcji)
5. Zakres katalogowy (monorepo: utrzymuje izolację instrukcji poszczególnych usług)

Preferencje stylistyczne należy pominąć do momentu, aż pierwsze cztery będą działać.

Importowanie plików

Odwołania do innych plików w obrębie 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 katalog domowy (@~/.claude/file.md). Maksymalna głębokość: 5 poziomów importów.⁶

Kompatybilność instrukcji między narzędziami

AGENTS.md to otwarty standard rozpoznawany przez wszystkie główne narzędzia AI do programowania.²¹ Jeśli zespół korzysta z wielu narzędzi, warto napisać AGENTS.md jako źródło kanoniczne i przenosić odpowiednie sekcje do plików specyficznych dla danego narzędzia:

Wzorce zawarte w AGENTS.md (oparte na poleceniach, definiujące domknięcie, uporządkowane 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ę w czasie. Należy napisać jedno autorytatywne źródło i je powielać.

Testowanie własnych instrukcji

Należy zweryfikować, czy agent rzeczywiście czyta i stosuje się do podanych instrukcji:

# 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 ostateczny: Proszę poprosić agenta o wyjaśnienie poleceń budowania. Jeśli nie potrafi ich odtworzyć dosłownie, instrukcje są albo zbyt rozwlekłe (treść została wypchnięta z kontekstu), albo zbyt ogólnikowe (agent nie potrafi wyodrębnić instrukcji do wykonania), albo nie zostały odnalezione. Analiza 2500 repozytoriów przeprowadzona przez GitHub wykazała, że to właśnie ogólnikowość jest przyczyną większości niepowodzeń.²¹

Wzorce produkcyjne

Wzorce długoterminowe Opus 4.7 (kwiecień 2026)

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

• Odporność na awarie narzędzi: Opus 4.7 kontynuuje pracę pomimo awarii narzędzi, które zatrzymywały sesje Opus 4.6. Można zredukować — ale nie wyeliminować — defensywne opakowania ponawiające próby w kodzie subagentów. Warto zachować zabezpieczenia na poziomie hooków; należy przyciąć rusztowanie w promptach typu „jeśli narzędzie zawiedzie, spróbuj trzy razy”.
• Poziom wysiłku xhigh (tylko Opus-4.7): Znajduje się między high a max. Rekomendowane ustawienie domyślne dla obciążeń związanych z kodowaniem i pracą agentową. W długo działających subagentach xhigh znacząco przewyższa high przy sub-proporcjonalnym koszcie tokenów. max pozostaje właściwym wyborem dla pojedynczego, trudnego rozumowania; xhigh jest lepszy dla zadań długotrwałych.
• Limit budżetu tokenów: Konfigurowalny dla każdego uruchomienia agenta poprzez output_config.task_budget (nagłówek beta task-budgets-2026-03-13). Model widzi odliczanie i elegancko dostosowuje zakres pracy do budżetu, zamiast niespodziewanie się kończyć. Warto używać tego w pętlach agentowych, gdy potrzebne jest przewidywalne zużycie tokenów bez poświęcania jakości w krótkich promptach.
• Świadomość niejawnych potrzeb: Pierwszy model Claude, który przechodzi testy „niejawnych potrzeb” — rozpoznając, kiedy dosłowne żądanie użytkownika niedostatecznie precyzuje to, czego faktycznie potrzebuje. Sprawia to, że sekcja „reguł doprecyzowujących” w CLAUDE.md jest mniej potrzebna. Jeśli CLAUDE.md ma 200 linii zabezpieczeń typu „rozważ również X, gdy użytkownik prosi o Y”, należy przyciąć te, które są teraz obsługiwane natywnie.

Pętla jakości

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

1. Implementacja - Napisanie kodu
2. Przegląd - Ponowne przeczytanie każdej linii. Wychwytywanie literówek, błędów logicznych, niejasnych fragmentów
3. Ocena - Uruchomienie evidence gate. Sprawdzenie wzorców, przypadków brzegowych, pokrycia testami
4. Dopracowanie - Naprawienie każdego problemu. Nigdy nie odkładać na „później”
5. Spojrzenie z szerszej perspektywy - Sprawdzenie punktów integracji, importów, sąsiadującego kodu pod kątem regresji
6. Powtórzenie - Jeśli jakiekolwiek kryterium evidence gate zawiedzie, powrót do kroku 4
7. Raport - Wylistowanie tego, co się zmieniło, jak zostało zweryfikowane, cytowanie konkretnych dowodów

Evidence gate

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

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

Wzorce obsługi błędów

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

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

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

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

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

Klasyfikacja blast radius

Każde działanie agenta należy klasyfikować według blast radius i odpowiednio je bramkować:²

Remote Control (łączenie się z lokalnym Claude Code z dowolnej przeglądarki lub aplikacji mobilnej) zmienia bramę „Zewnętrzne” z blokującego oczekiwania w asynchroniczne powiadomienie. Agent kontynuuje pracę nad następnym zadaniem, podczas gdy Pan/Pani przegląda poprzednie z telefonu.²

Specyfikacja zadań dla uruchomień autonomicznych

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

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

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

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

Konkretny ślad sesji

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

1. SessionStart się uruchamia. Dispatcher wstrzykuje: aktualną datę, wykrywanie projektu, ograniczenia filozoficzne, inicjalizację śledzenia kosztów. Pięć hooków, łącznie 180ms.

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

3. Agent wywołuje Bash, aby uruchomić testy. Uruchamia się PreToolUse:Bash. Sprawdzenie poświadczeń, walidacja sandboxa, wykrywanie projektu. 90ms. Testy się uruchamiają. Uruchamia się PostToolUse:Bash: zalogowany heartbeat aktywności, sprawdzenie dryfu.

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

5. Agent kończy historię. Uruchamia się Stop. Brama jakości sprawdza: czy agent zacytował dowody? Język asekuracyjny? Komentarze TODO w diffie? Jeśli jakiekolwiek sprawdzenie zawiedzie, exit 2 i agent kontynuuje.

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

7. Trzech agentów przeglądu kodu uruchamia się równolegle. Każdy przegląda diff niezależnie. Jeśli jakikolwiek recenzent oznaczy CRITICAL, historia wraca do kolejki.

8. Historia przechodzi. Ładuje się następna historia. Cykl powtarza się dla wszystkich 5 historii.

Łącznie hooki uruchomione w 5 historiach: ~340. Łączny czas w hookach: ~12 sekund. Ten narzut zapobiegł trzem wyciekom poświadczeń, jednemu destrukcyjnemu poleceniu i dwóm niekompletnym implementacjom w ciągu jednego nocnego uruchomienia.

Studium przypadku: Nocne przetwarzanie PRD

Produkcyjny harness przetworzył 12 PRD (47 historii) w ciągu 8 nocnych sesji. Metryki porównują pierwsze 4 PRD (minimalny harness: tylko CLAUDE.md) z ostatnimi 8 (pełny harness: hooki, skille, bramy jakości, multi-agent review).

Dwa wycieki poświadczeń wymagały rotacji kluczy API i audytu usług zależnych: około 4 godzin reakcji na incydent. Narzut harnessu, który temu zapobiegł, wynosił 2,4 sekundy basha na historię. Wskaźnik fałszywych ukończeń spadł z 35% do 4%, ponieważ Stop hook niezależnie uruchamiał testy przed pozwoleniem agentowi na zaraportowanie zakończenia.

Kwestie bezpieczeństwa

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

Anthropic opublikował formalne ramy oceny wiarygodności agentów 9 kwietnia 2026.²⁷ Pięć zasad pokrywa się — i rozszerza — myślenie Evidence Gate przedstawione w tym przewodniku:

Anthropic przekazał także MCP Linux Foundation w ramach Agentic AI Foundation, dołączając do AGENTS.md (nad którym nadzór sprawują wspólnie OpenAI, Google, Cursor, Factory oraz Sourcegraph). Standardy interoperacyjności agentów są teraz niezależne od dostawcy.²⁷

Narzędzia sandboxowe dla skills: Dla zespołów traktujących skills jako powierzchnię ataku, produkt SandyClaw firmy Permiso (wypuszczony 2 kwietnia 2026) uruchamia skills w dedykowanym sandboxie i dostarcza werdykty poparte dowodami z detekcji Sigma/YARA/Nova/Snort. 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 oraz operacje na systemie plików poprzez izolację na poziomie systemu operacyjnego (seatbelt w macOS, bubblewrap w Linux). Po włączeniu sandbox uniemożliwia modelowi wysyłanie dowolnych żądań sieciowych lub dostęp do plików poza katalogiem projektu. Bez sandboxa Claude Code korzysta z modelu opartego na uprawnieniach, w którym użytkownik zatwierdza lub odrzuca poszczególne wywołania narzędzi.¹³

Granice uprawnień

System uprawnień bramkuje operacje na wielu poziomach:

Obrona przed prompt injection

Skills oraz hooks zapewniają obronę w głąb przed prompt injection:

Skills z ograniczeniami narzędzi zapobiegają uzyskaniu dostępu do zapisu przez skompromitowany prompt:

allowed-tools: Read, Grep, Glob

Hooks PreToolUse walidują każde wywołanie narzędzia niezależnie od tego, w jaki sposób model został wypromptowany:

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

Bezpieczeństwo hook

Hooks HTTP, które interpolują zmienne środowiskowe do nagłówków, wymagają jawnej listy allowedEnvVars, aby zapobiec wyciekowi 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 między odpowiedzialnościami człowieka i agenta:¹⁷

Wzorzec: człowiek posiada decyzje wymagające kontekstu organizacyjnego, osądu etycznego lub strategicznego kierunku. Agent posiada decyzje wymagające obliczeniowego przeszukiwania dużych przestrzeni możliwości. Hooks egzekwują tę granicę.

Rekurencyjne egzekwowanie hook

Hooks uruchamiają się również dla działań subagentów.¹³ Jeśli Claude wytworzy subagenta przez Agent tool, hooks PreToolUse oraz PostToolUse zostaną wykonane dla każdego narzędzia używanego przez subagenta. Bez rekurencyjnego egzekwowania hook subagent mógłby obejść bramki bezpieczeństwa. Zdarzenie SubagentStop umożliwia uruchomienie czyszczenia lub walidacji, gdy subagent kończy pracę.

Nie jest to opcjonalne. Agent, który wytwarza subagenta bez hooks bezpieczeństwa, to agent, który może wykonać force push do main, odczytać pliki z poświadczeniami lub uruchomić destrukcyjne polecenia, podczas gdy bramki obserwują bezczynnie główną konwersację.

Koszt jako architektura

Koszt jest decyzją architektoniczną, a nie operacyjnym dodatkiem na końcu.² Trzy poziomy:

Poziom tokenów. Kompresja system prompt. Warto usuwać przykłady kodu o charakterze tutorialowym (model zna APIs), zwijać duplikujące się reguły w różnych plikach oraz zastępować wyjaśnienia ograniczeniami. „Odrzucaj wywołania narzędzi pasujące do wrażliwych ścieżek” wykonuje tę samą pracę, co 15-liniowe wyjaśnienie, dlaczego poświadczenia nie powinny być odczytywane.

Poziom agenta. Świeże wywołania zamiast długich konwersacji. Każda historia w autonomicznym uruchomieniu otrzymuje nowego agenta z czystym kontekstem. Kontekst nigdy się nie rozrasta, ponieważ każdy agent startuje od nowa. Briefing zamiast pamięci: modele lepiej wykonują jasny briefing niż nawigują przez 30 kroków narosłego kontekstu.

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

Ramy decyzyjne

Kiedy używać każdego mechanizmu:

Skills vs hooks vs subagenty

FAQ

Ile hooków to za dużo?

Ograniczeniem jest wydajność, a nie liczba. Każdy hook działa synchronicznie, więc łączny czas wykonania hooków dolicza się do każdego dopasowanego wywołania narzędzia. 95 hooków w ustawieniach na poziomie użytkownika i projektu działa bez zauważalnych opóźnień, gdy każdy z nich kończy się w czasie poniżej 200 ms. Próg, na który warto zwrócić uwagę: jeśli hook PostToolUse dodaje więcej niż 500 ms do każdej edycji pliku, sesja sprawia wrażenie ociężałej. Należy profilować hooki za pomocą time przed ich wdrożeniem.¹⁴

Czy hooki mogą blokować Claude Code przed wykonaniem polecenia?

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

Gdzie umieszczać pliki konfiguracyjne hooków?

Konfiguracje hooków trafiają do .claude/settings.json dla hooków na poziomie projektu (zapisywanych w repozytorium i dzielonych z zespołem) lub do ~/.claude/settings.json dla hooków na poziomie użytkownika (osobistych, stosowanych w każdym projekcie). Hooki na poziomie projektu mają pierwszeństwo, gdy istnieją oba warianty. Warto używać ścieżek bezwzględnych do plików skryptowych, aby uniknąć problemów z katalogiem roboczym.¹⁴

Czy każda decyzja wymaga deliberacji?

Nie. Moduł pewności ocenia decyzje w czterech wymiarach (niejednoznaczność, złożoność, stawka, zależność od kontekstu). Tylko decyzje, których łączny wynik pewności wypada poniżej 0,70, uruchamiają deliberację — mniej więcej 10% wszystkich decyzji. Poprawki w dokumentacji, zmiany nazw zmiennych i rutynowe edycje całkowicie pomijają deliberację. Architektura bezpieczeństwa, zmiany schematu bazy danych oraz nieodwracalne wdrożenia konsekwentnie ją uruchamiają.⁷

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

Należy testować zarówno ścieżki sukcesu, jak i porażki. Sukces: agenci produktywnie się nie zgadzają i osiągają konsensus. Porażka: agenci zbiegają się zbyt szybko, nigdy nie osiągają zgody lub przekraczają budżety uruchomień. Testy end-to-end symulują każdy scenariusz z deterministycznymi odpowiedziami agentów, weryfikując, czy oba mechanizmy walidacji wychwytują każdy udokumentowany tryb awarii. Produkcyjny system deliberacji uruchamia 141 testów w trzech warstwach: 48 testów integracyjnych w bash, 81 testów jednostkowych Python oraz 12 symulacji pipeline’u end-to-end.⁷

Jaki jest wpływ deliberacji na opóźnienie?

Deliberacja z 3 agentami dodaje 30–60 sekund czasu zegarowego (agenci działają sekwencyjnie przez Agent tool). Deliberacja z 10 agentami dodaje 2–4 minuty. Hooki konsensusu i pride check działają każdy w czasie poniżej 200 ms. Głównym wąskim gardłem jest czas inferencji LLM na agenta, a nie narzut orkiestracji.⁷

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

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

Czy można to zastosować z narzędziami innymi niż Claude Code?

Zasady architektoniczne (hooki jako deterministyczne bramki, skills jako wiedza domenowa, subagents jako izolowane konteksty, system plików jako pamięć) mają zastosowanie koncepcyjne w każdym systemie agentowym. Konkretna implementacja wykorzystuje zdarzenia cyklu życia Claude Code, wzorce dopasowywania oraz 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ą dla danego narzędzia specyficzne.

Karta szybkiego odniesienia

Konfiguracja hooków

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

Frontmatter skills

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

Definicja subagenta

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

Instructions for the subagent.

Kody wyjścia

Kluczowe polecenia

Lokalizacje plików

Changelog

Bibliografia