Architektura agentów: budowanie szkieletów programistycznych opartych na AI

TL;DR: Claude Code to nie okno czatu z dostępem do plików. To programowalne środowisko uruchomieniowe z 29 udokumentowanymi zdarzeniami cyklu życia, z których każde można obsłużyć skryptami powłoki, których model nie jest w stanie pominąć. Można składać hooks w dispatchers, dispatchers w skills, skills w agents, a agents w przepływy pracy — w rezultacie powstaje autonomiczny harness deweloperski, który egzekwuje ograniczenia, deleguje pracę, utrzymuje pamięć między sesjami i koordynuje deliberację wieloagentową. Niniejszy przewodnik omawia każdą warstwę tego stosu: od pojedynczego hooka po system konsensusu złożony z 10 agentów. Bez konieczności stosowania jakichkolwiek frameworków. Wyłącznie bash oraz JSON.

Andrej Karpathy ukuł termin opisujący to, co narasta wokół agenta LLM: claws. Hooks, skrypty i orkiestracja, które pozwalają agentowi uchwycić świat poza jego oknem kontekstu.¹ Większość deweloperów traktuje agentów programistycznych AI jako interaktywnych asystentów. Wpisują polecenie, obserwują, jak edytuje plik, i przechodzą dalej. Takie podejście ogranicza produktywność do tego, co można osobiście nadzorować.

Model mentalny oparty na infrastrukturze jest odmienny: agent programistyczny AI to programowalne środowisko uruchomieniowe z jądrem LLM. Każde działanie podejmowane przez model przechodzi przez hooks, nad którymi sprawuje się kontrolę. Definiuje się zasady, nie polecenia. Model działa w obrębie danej infrastruktury w taki sam sposób, w jaki serwer WWW działa w obrębie reguł nginx. Nie siada się przy nginx, by wpisywać żądania. Konfiguruje się go, wdraża i monitoruje.

To rozróżnienie ma znaczenie, ponieważ infrastruktura się kumuluje. Hook blokujący poświadczenia w poleceniach bash chroni każdą sesję, każdego agenta, każde autonomiczne uruchomienie. Skill kodujący kryteria oceny stosuje się spójnie, niezależnie od tego, czy zostanie wywołany przez użytkownika, czy przez agenta. Agent recenzujący kod pod kątem bezpieczeństwa wykonuje te same kontrole, niezależnie od tego, czy jest się obserwatorem, czy nie.²

Najważniejsze wnioski

• Hooks gwarantują wykonanie; polecenia nie. Warto stosować hooks do lintowania, formatowania, kontroli bezpieczeństwa i wszystkiego, co musi być wykonywane za każdym razem, niezależnie od zachowania modelu. Kod wyjścia 2 blokuje działania. Kod wyjścia 1 jedynie ostrzega.³
• Skills kodują wiedzę dziedzinową, która aktywuje się automatycznie. Pole description decyduje o wszystkim. Claude wykorzystuje rozumowanie LLM (nie dopasowywanie słów kluczowych), aby zdecydować, kiedy zastosować dany skill.⁴
• Subagents zapobiegają rozrostowi kontekstu. Izolowane okna kontekstu do eksploracji i analizy utrzymują główną sesję w zwięzłej formie. Niezależne subagents można uruchamiać równolegle, natomiast zespołów agentów należy używać wtedy, gdy pracownicy wymagają trwałej koordynacji.⁵
• Pamięć rezyduje w systemie plików. Pliki są zachowywane między oknami kontekstu. CLAUDE.md, MEMORY.md, katalogi reguł oraz dokumenty handoff tworzą uporządkowany system pamięci zewnętrznej.⁶
• Deliberacja wieloagentowa wykrywa martwe punkty. Pojedynczy agenci nie są w stanie kwestionować własnych założeń. Dwóch niezależnych agentów o różnych priorytetach oceny wychwytuje błędy strukturalne, których nie są w stanie wyeliminować bramki jakości.⁷
• Wzorzec harness to cały system. CLAUDE.md, hooks, skills, agents oraz pamięć nie są niezależnymi funkcjami. Łączą się one w deterministyczną warstwę pomiędzy użytkownikiem a modelem, która skaluje się wraz z automatyzacją.

Jak korzystać z niniejszego przewodnika

Każda sekcja opiera się na poprzedniej. Sekcja Decision Framework na końcu zawiera tabelę odniesień, która pozwala dobrać właściwy mechanizm do każdego rodzaju problemu.

Pięciominutowa ścieżka złota

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

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

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

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

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

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

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

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

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

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

Krok 3: Uruchomienie subagenta (30 sekund)

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

Co zostało uzyskane

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

Dlaczego architektura agentów ma znaczenie

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

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

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

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

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

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

Wzorzec harness

Harness 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 Pana/Pani projekcie. Ładują się automatycznie przy starcie sesji oraz po każdej kompakcji. Jest to długoterminowa pamięć architektoniczna agenta.

Warstwa rozszerzeń: Skills dostarczają wiedzy domenowej, 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. Niestandardowi agenci dostarczają wyspecjalizowanych konfiguracji subagents.

Warstwa orkiestracji: Wzorce wieloagentowe koordynują niezależnych agentów do badań, przeglądu i deliberacji. Budżety spawnowania zapobiegają niekontrolowanej rekursji. Walidacja konsensusu zapewnia jakość.

Kluczowe spostrzeżenie: większość użytkowników pracuje wyłącznie w warstwie Core, obserwując rozrastający się kontekst i rosnące koszty. Zaawansowani użytkownicy konfigurują warstwy Instruction i Extension, a warstwy Core używają wyłącznie do orkiestracji i ostatecznych decyzji.²

Managed vs. self-hosted harness (kwiecień 2026)

Przez większość początku 2026 ścieżka „zbuduj własny harness” była jedyną realną opcją. W kwietniu 2026 to się zmieniło. Anthropic wypuścił Claude Managed Agents w publicznej wersji beta (8 kwietnia): pętla harness + wykonywanie narzędzi + kontener sandbox + persistencja stanu jako REST API, rozliczane według standardowych tokenów plus $0,08 za godzinę-sesji. Aktualizacja OpenAI Agents SDK (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 dla przetrwania utraty kontenera.²³²⁴

Głębsza powierzchnia SDK po stronie OpenAI pojawiła się w openai-agents Python v0.14.0 (wydany 15 kwietnia 2026; ogłoszony 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, mounts); SandboxRunConfig do wiązania 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 powłoki, edycję filesystemu, inspekcję obrazów, skills, pamięć sandbox oraz kompakcję. Pamięć sandbox utrwala wyodrębnione lekcje między uruchomieniami i progresywnie je ujawnia; workspace’y obsługują pliki lokalne, wpisy repo Git oraz zdalne mounts (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 extras.²⁴

Dla projektów Python, które chcą osadzić runtime Claude Code jako bibliotekę — pomiędzy „wywołaniem claude przez shell” a „REST API do Managed Agents” — claude-agent-sdk-python jest trzecią opcją. Seria z 28-29 kwietnia (v0.1.69 → v0.1.71) podniosła wbudowany CLI do v2.1.123, podniosła próg zależności mcp do >=1.19.0 (starsze wersje cicho odrzucały zwroty CallToolResult z narzędzi MCP in-process, pozostawiając modelowi blob błędu walidacji) oraz dostosowała SandboxNetworkConfig do parytetu schematu z TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

Rozwidlenie architektoniczne jest teraz realne:

Kiedy wybrać które: self-hosted pozostaje słuszny dla zespołów, które już mają siłę infrastrukturalną, chcą skills/hooks pod własną kontrolą lub głęboko optymalizują konkretny workflow. Managed jest słuszny dla zespołów bez dedykowanych inżynierów platformy, gdy czas do wartości jest ważniejszy niż personalizacja, lub gdy uruchomienia agentów muszą niezawodnie przetrwać zamknięcie laptopa bez konieczności samodzielnego budowania warstwy persistencji. Oba podejścia są kompatybilne — można uruchomić self-hosted harness, który deleguje konkretne długo działają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 przez git. Razem tworzą kompletny harness.

System umiejętności

Umiejętności to rozszerzenia wywoływane przez model. Claude wykrywa je i stosuje automatycznie na podstawie kontekstu, bez konieczności jawnego wywoływania.⁴ W momencie, gdy zauważa Pan/Pani, że ponownie tłumaczy ten sam kontekst w kolejnych sesjach, należy zbudować umiejętność.

Kiedy budować umiejętność

Umiejętności służą wiedzy, którą Claude ma zawsze dostępną. Polecenia ukośnikowe służą akcjom, które uruchamia Pan/Pani jawnie. Decydując między nimi, warto zadać pytanie: „Czy Claude powinien stosować to automatycznie, czy też ja decyduję, kiedy to uruchomić?”

Tworzenie umiejętności

Umiejętności znajdują się w czterech możliwych lokalizacjach, od najszerszego do najwęższego zakresu:⁴

Każda umiejętność wymaga pliku SKILL.md z nagłówkiem 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

Referencja pól nagłówka frontmatter

Pole opisu jest wszystkim

Na początku sesji Claude Code wyodrębnia pola name i description każdej umiejętności i wstrzykuje je do kontekstu Claude. Gdy wysyła Pan/Pani wiadomość, Claude używa rozumowania modelu językowego, aby zdecydować, czy któraś z umiejętności jest istotna. Niezależna analiza kodu źródłowego Claude Code potwierdza ten mechanizm: opisy umiejętności są wstrzykiwane do sekcji available_skills promptu systemowego, a model używa standardowego rozumienia języka do wyboru istotnych umiejętności.¹⁰

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 zawiera: co robi (przegląda kod pod kątem konkretnych typów problemów), kiedy go użyć (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 umiejętności współdzielą budżet kontekstu, który skaluje się dynamicznie do 1% okna kontekstu, z wartością zapasową 8000 znaków.⁴ Przy wielu umiejętnościach należy utrzymywać każdy opis zwięzły i umieszczać kluczowy przypadek użycia na początku. Można nadpisać budżet poprzez zmienną środowiskową SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ lecz lepszym rozwiązaniem są krótsze, precyzyjniejsze opisy. Polecenie /context w trakcie sesji pozwala sprawdzić, czy jakieś umiejętności są wykluczane.

Pliki pomocnicze i organizacja

Umiejętności mogą odwoływać się do dodatkowych plików w tym samym folderze:

~/.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 umiejętność się aktywuje. Plik SKILL.md warto utrzymywać poniżej 500 linii, a szczegółowy materiał referencyjny przenosić do plików pomocniczych.¹²

Współdzielenie umiejętności przez Git

Umiejętności projektowe (.claude/skills/ w katalogu głównym repozytorium) są współdzielone poprzez 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 współpracownicy zaktualizują repozytorium, otrzymują umiejętność automatycznie. Bez instalacji, bez konfiguracji. To najskuteczniejszy sposób ujednolicenia wiedzy w zespole.

Umiejętności jako biblioteka promptów

Poza umiejętnościami jednofunkcyjnymi struktura folderów działa jak 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żda umiejętność koduje inny aspekt Pana/Pani wiedzy specjalistycznej. Razem tworzą bazę wiedzy, z której Claude czerpie automatycznie na podstawie kontekstu. Mniej doświadczony programista otrzymuje wskazówki na poziomie seniora bez konieczności pytania.

Umiejętności komponują się z hookami

Umiejętności mogą definiować własne hooki w nagłówku frontmatter, które aktywują się tylko podczas działania umiejętności. Tworzy to zachowanie specyficzne dla dziedziny, 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'"
---

Umiejętności filozoficzne aktywują się automatycznie poprzez hooki SessionStart, wstrzykując ograniczenia jakościowe do każdej sesji bez jawnego wywołania. Sama umiejętność stanowi wiedzę. Hook stanowi egzekwowanie. Razem tworzą warstwę polityki.

Częste błędy w umiejętnościach

Zbyt szerokie opisy. Umiejętność git-rebase-helper, która aktywuje się przy dowolnym promptcie związanym z gitem (rebase’y, merge’e, cherry-picki, a nawet git status), zanieczyszcza kontekst w 80% sesji. Rozwiązaniem jest albo zawężenie opisu, albo dodanie disable-model-invocation: true i wymaganie jawnego wywołania /skill-name.⁴

Zbyt wiele umiejętności konkurujących o budżet. Więcej umiejętności oznacza więcej opisów konkurujących o 1% budżetu kontekstu. Jeśli zauważa Pan/Pani, że umiejętności się nie aktywują, należy sprawdzić /context w poszukiwaniu wykluczonych. Lepiej priorytetowo traktować mniej, dobrze opisanych umiejętności niż wiele niejasnych.

Krytyczne informacje ukryte w plikach pomocniczych. Claude czyta SKILL.md natychmiast, lecz pliki pomocnicze otwiera dopiero w razie potrzeby. Jeśli krytyczna informacja znajduje się w pliku pomocniczym, Claude może jej nie znaleźć. Niezbędne informacje należy umieszczać bezpośrednio w SKILL.md.⁴

Powierzchnia umiejętności SDK (8 maja 2026)

Samodzielnie hostowane harness’y na claude-agent-sdk-python w wersji v0.1.77+ powinny używać opcji skills w ClaudeAgentOptions, aby deklarować dostępne umiejętności, a nie starszej wartości "Skill" w allowed_tools.³⁷ Skrót "Skill" jest przestarzały, a dedykowana opcja dostarcza Claude Code bardziej ustrukturyzowanych informacji o tym, które umiejętności są dostępne. Dołączony CLI w wersji v0.1.77 to v2.1.133.

Architektura hooków

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

Dostępne zdarzenia

Claude Code udostępnia 29 udokumentowanych zdarzeń cyklu życia w ośmiu kategoriach na moment aktualizacji niniejszego przewodnika. Lista zdarzeń rośnie wraz z kolejnymi wydaniami, więc dokumentację referencyjną należy traktować jako źródło prawdy i przed podłączeniem produkcyjnych hooków warto sprawdzić aktualną pełną tabelę w ściądze:¹³

Semantyka kodów wyjścia

Kody wyjścia decydują o tym, czy hooki blokują akcje:³

Krytyczna uwaga: Każdy hook bezpieczeństwa musi używać exit 2, a nie exit 1. Exit 1 to nieblokujące ostrzeżenie. Niebezpieczne polecenie i tak zostanie wykonane. Jest to najczęstszy błąd przy hookach w różnych 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 filtruje wartość specyficzną dla zdarzenia. Dla zdarzeń narzędziowych dopasowuje wartości tool_name takie jak Bash, Edit, Write, Read, Glob, Grep, nazwy narzędzi MCP w stylu mcp__server__tool lub * dla wszystkich narzędzi. Proste nazwy oraz listy rozdzielone znakiem | to dopasowania dokładne; wartości z innymi znakami są traktowane jako wyrażenia regularne JavaScript. Niektóre zdarzenia nie obsługują matcherów i zawsze uruchamiają się, gdy są skonfigurowane.¹³

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

W celu zaawansowanej kontroli hooki PreToolUse mogą zwracać JSON, aby modyfikować dane wejściowe narzędzia, wstrzykiwać kontekst lub podejmować decyzje uprawnień. 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: jakiej gwarancji potrzebuję?¹⁴

Gwarancje formatowania zapewniają spójność po fakcie. Hooki PostToolUse na Write/Edit uruchamiają formater po każdej zmianie pliku. Wynik 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 na Bash sprawdzają 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 na poleceniach git commit uruchamiają linter lub zestaw testów i blokują commit, jeśli kontrole jakości nie przejdą:

#!/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:¹³

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

Hooki narzędzi MCP (type: "mcp_tool") wywołują narzędzie na już połączonym serwerze MCP. Warto z nich korzystać, gdy logika walidacji jest już dostępna za granicą MCP i nie potrzebuje osobnego skryptu powłoki.

Hooki promptowe (type: "prompt") wysyłają jednoturową wiadomość do szybkiego modelu Claude. Model zwraca { "ok": true }, aby zezwolić, lub { "ok": false, "reason": "..." }, aby zablokować. Stosować do zniuansowanej oceny, której nie da się wyrazić wyrażeniami regularnymi.

Hooki agentowe (type: "agent") tworzą subagenta z dostępem do narzędzi (Read, Grep, Glob) w celu wieloturowej weryfikacji. Są eksperymentalne; do produkcyjnych bramek jakościowych lepiej preferować hooki poleceniowe, a hooki agentowe rezerwować dla kontroli, które naprawdę wymagają inspekcji rzeczywistych 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
          }
        ]
      }
    ]
  }
}

Hooki HTTP (type: "http") wysyłają JSON wejściowe zdarzenia jako żądanie POST na adres URL i odbierają JSON z powrotem. Stosować do webhooków, zewnętrznych usług powiadomień lub walidacji opartej na API (v2.1.63+). Niewspierane 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 wykonywania. Należy dodać async: true dla niekrytycznych operacji, takich jak powiadomienia i logowanie:¹³

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

Używać async dla powiadomień, telemetrii i kopii zapasowych. Nigdy nie używać async dla formatowania, walidacji ani niczego, co musi się zakończyć przed kolejną akcją.

Dispatchery zamiast niezależnych hooków

Uruchamianie siedmiu hooków jednocześnie wyzwalanych przez to samo zdarzenie, z których każdy odczytuje stdin niezależnie, tworzy sytuacje wyścigu. Dwa hooki zapisujące jednocześnie do tego samego pliku stanu JSON obetną JSON. Każdy kolejny hook parsujący ten plik się popsuje.²

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

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

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

Debugowanie hooków

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

1. Testowanie skryptów niezależnie. Przekazać przykładowy JSON: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Używanie stderr do wyjścia debugowego. Stderr przy kodzie wyjścia 2 jest przekazywane z powrotem do Claude jako komunikat błędu. Nieblokujące stderr (exit 1, 3, itp.) pojawia się tylko w trybie verbose (Ctrl+O).
3. Uważać na błędy jq. Niewłaściwe ścieżki JSON zwracają po cichu null. Wyrażenia jq warto testować na rzeczywistym wejściu narzędzia.
4. Weryfikowanie kodów wyjścia. Hook PreToolUse używający exit 1 nie zapewnia żadnego egzekwowania, choć z pozoru działa.
5. Trzymanie hooków szybkimi. Hooki działają synchronicznie. Wszystkie hooki należy utrzymywać poniżej 2 sekund, najlepiej poniżej 500 ms.

Strumieniowanie zdarzeń hooków po stronie SDK

Samodzielnie hostowane harnessy 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 wywołania zwrotne skryptów powłoki.³⁶ Po ustawieniu include_hook_events=True na ClaudeAgentOptions obiekty HookEventMessage (PreToolUse, PostToolUse, Stop i inne) są emitowane przez ten sam iterator co wiadomości asystenta i wyniki narzędzi. Odpowiada to opcji includeHookEvents w SDK TypeScript; dołączony CLI został podniesiony do v2.1.129 w tym samym wydaniu.

Wzorzec strumienia zdarzeń jest właściwy, gdy harness mieści się już w Python i sygnały hooków mają być w tym samym przepływie sterowania, co wyjście modelu. Kontrakt skryptów powłoki dla hooków (kody wyjścia, stdin JSON, dispatchery) pozostaje właściwą odpowiedzią dla harnessów, które łączą wiele narzędzi, współdzielą hooki między Claude Code i Codex lub potrzebują semantyki kodów wyjścia do blokowania.

Pochodzenie nakładu i sesji (7-8 maja 2026)

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

• effort.level w danych wejściowych hooka. Hooki otrzymują teraz pole JSON effort.level w tym samym wejściu, które przenosi tool_input i session_id. Ta sama wartość jest eksportowana jako zmienna środowiskowa $CLAUDE_EFFORT, dzięki czemu polecenia Bash mogą ją odczytać bez parsowania JSON. Można tego użyć do skalowania kosztu hooka według poziomu nakładu: pominąć kosztowną walidację dla low, uruchomić pełną bramkę bezpieczeństwa dla xhigh lub max.
• Zmienna środowiskowa CLAUDE_CODE_SESSION_ID w podprocesach Bash. Podprocesy narzędzia Bash widzą teraz tę samą wartość session_id, którą widzą hooki, udostępnioną jako CLAUDE_CODE_SESSION_ID. Zamyka to lukę proweniencji dla narzędzi, które logują stan na sesję i wcześniej nie mogły skorelować zdarzeń podprocesów ze zdarzeniami hooków.

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

Pamięć i kontekst

Każda rozmowa z AI działa w ramach skończonego okna kontekstu. W miarę jak rozmowa rośnie, system kompresuje wcześniejsze tury, aby zrobić miejsce dla nowej zawartości. Kompresja jest stratna. Decyzje architektoniczne udokumentowane w turze 3 mogą nie przetrwać do tury 15.⁹

Trzy mechanizmy załamania w rozmowach wieloturowych

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

Strategia 1: System plików jako pamięć

Najbardziej niezawodna pamięć przekraczająca granice kontekstu znajduje się w systemie plików. Claude Code czyta CLAUDE.md i pliki pamięci na początku każdej sesji oraz 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 we wszystkich sesjach. Gdy odkryje Pan/Pani, że ((VAR++)) zawodzi z set -e w bash, gdy VAR wynosi 0, należy to zapisać. Trzy sesje później, gdy napotka się podobny przypadek brzegowy z liczbami całkowitymi w Python, wpis w MEMORY.md ujawni ten wzorzec.¹⁵

Auto Memory (v2.1.32+): Claude Code automatycznie zapisuje i przypomina kontekst projektu. Podczas pracy Claude zapisuje obserwacje w ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory ładuje pierwsze 200 linii do podpowiedzi systemowej na początku sesji. Warto utrzymywać ją zwięzłą i odsyłać do osobnych plików tematycznych zawierających szczegółowe notatki.⁶

Strategia 2: Proaktywna kompaktacja

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

Kiedy stosować kompaktację: - Po ukończeniu odrębnego podzadania (zaimplementowana funkcja, naprawiony błąd) - Przed rozpoczęciem pracy w nowym obszarze bazy kodu - Gdy Claude zaczyna się powtarzać lub zapominać wcześniejszy kontekst - 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: Przekazania między sesjami

W przypadku zadań obejmujących wiele sesji warto tworzyć dokumenty przekazania, które rejestrują 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 dostarcza kolejnej sesji pełnego kontekstu przy minimalnym koszcie tokenów. Rozpoczęcie nowej sesji za pomocą claude -c (kontynuacja) lub odczytanie dokumentu przekazania prowadzi prosto do implementacji.¹⁵

Strategia 4: Iteracja w świeżym kontekście (pętla Ralph)

Dla sesji przekraczających 60-90 minut warto uruchamiać świeżą instancję Claude na każdą iterację. Stan jest zachowywany w systemie plików, a nie w 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

Dla porównania pojedyncza długa sesja:

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

Podejście świeżego kontekstu na iterację wymienia 15-20% narzutu na krok orientacji (czytanie plików stanu, skanowanie historii git) w zamian za pełne zasoby poznawcze w każdej iteracji.¹⁶ Kalkulacja kosztów i korzyści: dla sesji poniżej 60 minut pojedyncza rozmowa jest bardziej efektywna. Powyżej 90 minut świeży kontekst daje wyższej jakości wyniki pomimo narzutu.

Strategia 5: Zarządzane kuratorowanie pamięci (Dreaming)

Anthropic’s Claude Managed Agents wprowadziło Dreaming jako Research Preview 6 maja 2026.³⁵ Według Anthropic: „Dreaming to zaplanowany proces, który przegląda sesje agentów oraz magazyny pamięci, wyodrębnia wzorce i kuratoruje pamięć, dzięki czemu agenci doskonalą się w czasie.”³⁵

Dreaming działa w tle pomiędzy sesjami, poza ścieżką krytyczną. Uzupełnia, a nie zastępuje wzorzec systemu plików jako pamięci: plik MEMORY.md pozostaje powierzchnią nośną; Dreaming zapisuje wyselekcjonowane wpisy pamięci do magazynu pamięci Managed Agents, który agent czyta na początku sesji. Oba wzorce współistnieją w przypadku harness’ów łączących stan systemu plików zarządzany samodzielnie z kuratorowaniem po stronie zarządzanej.

Dreaming jest w fazie Research Preview, więc zachowanie może się zmienić. Wzorce session-handoffs i CLAUDE.md udokumentowane powyżej pozostają autorytatywnym mechanizmem pamięci dla harness’ów hostowanych samodzielnie.

Antywzorce

Czytanie całych plików, gdy potrzeba 10 linii. Pojedyncze odczytanie pliku liczącego 2000 linii zużywa 15 000-20 000 tokenów. Warto stosować przesunięcia linii: Read file.py offset=100 limit=20 oszczędza zdecydowaną większość tego kosztu.¹⁵

Trzymanie szczegółowych wyjść błędów w kontekście. Po debugowaniu błędu kontekst zawiera ponad 40 śladów stosu z nieudanych iteracji. Pojedyncze /compact po naprawie błędu uwalnia ten martwy ciężar.

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

Wzorce subagentów

Subagenty to wyspecjalizowane instancje Claude, które niezależnie obsługują złożone zadania. Rozpoczynają pracę z czystym kontekstem (bez zanieczyszczenia z głównej rozmowy), działają z określonymi narzędziami i zwracają wyniki w formie podsumowań. Wyniki eksploracji nie obciążają głównej rozmowy; zwracane są wyłącznie wnioski.⁵

Wbudowane typy subagentów

Tworzenie niestandardowych subagentów

Proszę zdefiniować subagenty 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 konfiguracyjne subagentów

Izolacja worktree

Subagenty 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 w przypadku prac eksperymentalnych, które mogłyby zepsuć bazę kodu.

Równoległe subagenty

Równoległe subagenty warto wykorzystywać do niezależnych zadań badawczych, które nie wymagają wzajemnej koordynacji:⁵

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

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

Ochrona przed rekursją

Bez limitów uruchamiania agenty delegują pracę do agentów, którzy delegują do kolejnych agentów, a każdy z nich traci kontekst i marnuje tokeny. Wzorzec ochrony przed rekursją 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 uruchamiania, 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 uruchamiania śledzi łączną liczbę aktywnych dzieci na rodzica, ograniczoną do konfigurowalnego maksimum. Model budżetu odpowiada rzeczywistemu trybowi awarii (zbyt wiele agentów łącznie), a nie metryce zastępczej (zbyt wiele poziomów zagnieżdżenia).⁷

Zespoły agentów (Research Preview)

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

Włączenie poleceniem: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Kiedy stosować zespoły agentów, a kiedy subagenty:

Orkiestracja wieloagentowa

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

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

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

Zarządzana orkiestracja wieloagentowa i Outcomes (Public Beta)

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

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

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

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

Minimalna sensowna deliberacja

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

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

Ten wzorzec pokrywa 80% wartości. Wszystko inne dodaje stopniową poprawę.

Wyzwalacz pewności

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

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

Wynik mapuje się na trzy poziomy:

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

Maszyna stanów

Siedem faz, każda otwierana przez poprzednią:⁷

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

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

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

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

Architektura walidacji dwubramkowej

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

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

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

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

Dlaczego zgoda jest niebezpieczna

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

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

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

Wykrywanie fałszywej zgody

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

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

Szablonowy sprzeciw: Agenty kopiujące wzajemnie język obaw, zamiast generować niezależne zastrzeżenia.

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

Detektor konformizmu wychwytuje oczywiste przypadki (mniej więcej 10–15% deliberacji, w których agenty zbiegają się zbyt szybko). Dla pozostałych 85–90% bramki konsensusu i pride check zapewniają wystarczającą walidację.

Co nie zadziałało w deliberacji

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

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

Koszt deliberacji

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

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

Kiedy deliberować

Projektowanie 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 wiedzieć, jakie dokładnie polecenie uruchomić i jak wygląda stan „ukończone”.

Hierarchia pierwszeństwa

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

Co zostaje zignorowane

Te wzorce niezawodnie nie wywołują żadnej zauważalnej zmiany w zachowaniu agenta:²¹

Akapity prozy bez poleceń. „Cenimy czysty, dobrze przetestowany kod” to dokumentacja, a nie operacje. Agent czyta to i przystępuje do pisania kodu bez testów, ponieważ brakuje wykonalnej instrukcji.

Niejednoznaczne dyrektywy. „Ostrożnie z migracjami bazy danych” nie stanowi ograniczenia. „Uruchom alembic check przed zastosowaniem migracji. Przerwij, jeśli brakuje ścieżki downgrade.” — owszem.

Sprzeczne priorytety. „Działaj szybko i szybko wdrażaj” plus „Zapewnij kompleksowe pokrycie testami” plus „Utrzymuj czas wykonania poniżej 5 minut” plus „Uruchamiaj 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. „Stosuj Google Python Style Guide” bez ruff check --select D nie daje agentowi żadnego mechanizmu weryfikacji zgodności.

Co działa

Instrukcje zorientowane na polecenia:

## 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 zamknię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, należy dodawać sekcje w następującej kolejności priorytetu:²¹

1. Polecenia build i test (agent potrzebuje ich, zanim cokolwiek pożytecznego wykona)
2. Definicja ukończenia (zapobiega fałszywym deklaracjom zakończenia)
3. Reguły eskalacji (zapobiega destrukcyjnym obejściom)
4. Sekcje uporządkowane według zadań (ogranicza parsowanie nieistotnych instrukcji)
5. Określanie zakresu katalogów (monorepo: izoluje instrukcje poszczególnych usług)

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

Importy 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.⁶

Zgodność instrukcji między narzędziami

AGENTS.md to otwarty standard rozpoznawany przez każde poważniejsze narzędzie do kodowania AI.²¹ Jeżeli zespół korzysta z wielu narzędzi, warto pisać AGENTS.md jako kanoniczne źródło i odzwierciedlać odpowiednie sekcje w plikach specyficznych dla danego narzędzia:

Wzorce z AGENTS.md (zorientowane na polecenia, z określoną definicją zamknięcia, uporządkowane wokół zadań) działają w każdym 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. Trzeba pisać jedno autorytatywne źródło i je odzwierciedlać.

Uwagi dotyczące parytetu Codex

Codex dysponuje obecnie odpowiednikami pierwszej klasy dla głównych warstw harness, lecz migracja polega na tłumaczeniu wzorców, a nie na kopiowaniu plików. Codex czyta AGENTS.md przed rozpoczęciem pracy, nakładając wskazówki globalne z ~/.codex na instrukcje projektowe i instrukcje z zagnieżdżonych repozytoriów.³¹ Skille Codex korzystają z tego samego modelu mentalnego SKILL.md z progresywnym ujawnianiem: Codex zaczyna od nazwy skilla, opisu i ścieżki pliku, a pełen skill ładuje dopiero, gdy zdecyduje się go użyć.³² Codex posiada również natywne hooki, hooki dystrybuowane w pluginach, hooki zarządzane, wsparcie dla MCP oraz jawne przepływy pracy z subagentami.³³³⁴

Praktyczne mapowanie:

Istotna różnica: subagenci Claude mogą być wybierani automatycznie na podstawie opisów, podczas gdy Codex obecnie dokumentuje przepływy z subagentami jako jawne. Z tego powodu skille i hooki są właściwym domyślnym rozwiązaniem dla stałego zachowania harness w Codex; subagenci służą do celowej pracy równoległej, recenzji i eksploracji.

Testowanie własnych instrukcji

Warto zweryfikować, czy agent rzeczywiście czyta i stosuje się do 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: należy poprosić agenta o wyjaśnienie poleceń build. Jeżeli nie potrafi ich odtworzyć dosłownie, instrukcje są albo zbyt rozwlekłe (treść została wypchnięta poza kontekst), albo zbyt ogólne (agent nie potrafi z nich wyłuskać wykonalnych poleceń), albo nie zostały odnalezione. Analiza 2 500 repozytoriów wykonana przez GitHub wykazała, że to właśnie ogólnikowość jest przyczyną większości niepowodzeń.²¹

Wzorce produkcyjne

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

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

• Odporność na awarie narzędzi: Opus 4.7 kontynuuje pracę pomimo awarii narzędzi, które wstrzymywały sesje Opus 4.6. Można ograniczyć — choć nie wyeliminować — defensywne wrappery z mechanizmem ponawiania w kodzie subagentów. Należy zachować zabezpieczenia na poziomie hooków; warto natomiast przyciąć rusztowanie w promptach typu „jeśli narzędzie zawiedzie, spróbuj trzy razy”.
• Poziom wysiłku xhigh (tylko Opus-4.7): Mieści się pomiędzy high a max. Zalecany domyślny wybór dla kodowania i obciążeń agentowych. W długo działających subagentach xhigh znacząco przewyższa high przy podproporcjonalnym koszcie tokenów. max pozostaje właściwym wyborem dla pojedynczych trudnych zadań rozumowania; xhigh lepiej sprawdza się w zadaniach ciągłych.
• Pułap 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 nagle wyczerpywać zasoby. Warto wykorzystać w pętlach agentowych, gdzie pożądane jest przewidywalne zużycie tokenów bez utraty jakości przy krótkich promptach.
• Świadomość niejawnych potrzeb: Pierwszy model Claude, który przeszedł testy „niejawnych potrzeb” — rozpoznawanie, kiedy dosłowne żądanie użytkownika nie precyzuje w pełni tego, czego użytkownik faktycznie potrzebuje. Sprawia to, że sekcja „reguł doprecyzowujących” w CLAUDE.md staje się mniej potrzebna. Jeśli plik CLAUDE.md zawiera 200 wierszy zabezpieczeń typu „rozważ także X, gdy użytkownik prosi o Y”, warto wyciąć te, które są teraz obsługiwane natywnie.

Bazowe worktree, ścieżki sandboksa i ustawienia administracyjne (7 maja 2026)

Claude Code v2.1.133 dodaje cztery ustawienia poziomu administratora warte poznania w produkcyjnych harnessach:³⁹

Zmiana w worktree.baseRef jest tą, którą warto zasygnalizować użytkownikom: agenci, którzy polegali na zachowaniu z v2.1.128-v2.1.132 (worktree rozgałęziające się od lokalnego HEAD), tracą dostęp do niewypchniętej pracy w świeżych worktree, chyba że ponownie się zdeklarują.

Pętla jakości

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

1. Zaimplementuj - Napisz kod
2. Zrecenzuj - Przeczytaj ponownie każdy wiersz. Wyłap literówki, błędy logiczne, niejasne fragmenty
3. Oceń - Uruchom evidence gate. Sprawdź wzorce, przypadki brzegowe, pokrycie testami
4. Dopracuj - Napraw każdy problem. Nigdy nie odkładaj „na później”
5. Spojrzenie z dystansu - Sprawdź punkty integracji, importy, sąsiedni kod pod kątem regresji
6. Powtórz - Jeśli którekolwiek kryterium evidence gate zawiedzie, wróć do kroku 4
7. Raportuj - Wymień, co się zmieniło, jak zostało zweryfikowane, przytocz konkretne dowody

Evidence gate

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

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

Wzorce obsługi błędów

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

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

Odzyskiwanie po uszkodzeniu stanu. Jeśli stan ulegnie uszkodzeniu, wzorzec odzyskiwania odtwarza go z bezpiecznych wartości domyślnych zamiast się zawiesić:¹⁶

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

Pułapka ((VAR++)) w bashu. ((VAR++)) zwraca kod wyjścia 1, gdy VAR wynosi 0, ponieważ 0++ zostaje obliczone 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 promienia rażenia

Każde działanie agenta należy klasyfikować według promienia rażenia i odpowiednio nakładać bramki:²

Zdalne sterowanie (łączenie się z lokalnym Claude Code z dowolnej przeglądarki lub aplikacji mobilnej) zmienia bramkę „Zewnętrzne” z blokującego oczekiwania w asynchroniczne powiadomienie. Agent kontynuuje pracę nad następnym zadaniem, podczas gdy poprzednie jest sprawdzane z poziomu telefonu.²

Specyfikacja zadań dla uruchomień autonomicznych

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

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: zaliczenie/niezaliczenie testów, wynik lintera, kody statusu HTTP, sprawdzenia istnienia plików. Wczesne zadanie, które prosiło agenta o „napisanie testów, które przechodzą”, wyprodukowało assert True i assert 1 == 1. Technicznie poprawne. Praktycznie bezwartościowe.¹⁶

Tryby awarii, na które należy zwracać uwagę

Konkretny ślad sesji

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

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

2. Agent czyta PRD i planuje pierwszą historię. Uruchamia się UserPromptSubmit. Dispatcher wstrzykuje: aktywny kontekst projektu, bazowy poziom dryfu sesji.

3. Agent wywołuje Bash, aby uruchomić testy. Uruchamia się PreToolUse:Bash. Sprawdzanie poświadczeń, walidacja sandboksa, wykrywanie projektu. 90 ms. Testy się uruchamiają. Uruchamia się PostToolUse:Bash: rejestrowany jest puls aktywności, kontrola dryfu.

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

5. Agent kończy historię. Uruchamia się Stop. Bramka jakości sprawdza: czy agent przytoczył dowody? Język asekuracyjny? Komentarze TODO w diff-ie? Jeśli którakolwiek kontrola zawiedzie, kod wyjścia 2 i agent kontynuuje.

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

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

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

Łączna liczba hooków uruchomionych w 5 historiach: ~340. Łączny czas spędzony w hookach: ~12 sekund. Ten narzut zapobiegł trzem wyciekom poświadczeń, jednemu destrukcyjnemu poleceniu i dwóm niekompletnym implementacjom w jednym całonocnym uruchomieniu.

Studium przypadku: Całonocne przetwarzanie PRD

Produkcyjny harness przetworzył 12 PRD (47 historii) w trakcie 8 całonocnych sesji. Metryki porównują pierwsze 4 PRD (minimalny harness: tylko CLAUDE.md) z ostatnimi 8 (pełny harness: hooki, skille, bramki jakości, wieloagentowy przegląd).

Dwa wycieki poświadczeń wymagały rotacji kluczy API i audytu usług zależnych: około 4 godzin reagowania na incydent. Narzut harnessa, który zapobiegł odpowiednikowi, wynosił 2,4 sekundy basha na historię. Wskaźnik fałszywych ukończeń spadł z 35% do 4%, ponieważ hook Stop niezależnie uruchamiał testy, zanim pozwolił agentowi zaraportować ukończenie.

Kwestie bezpieczeństwa

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

Anthropic opublikował 9 kwietnia 2026 roku formalne ramy dotyczące wiarygodności agentów.²⁷ Pięć zasad jest zbieżnych — i rozszerza — koncepcję Evidence Gate przedstawioną w niniejszym przewodniku:

Anthropic przekazał także MCP na rzecz Agentic AI Foundation działającej w ramach Linux Foundation, dołączając tym samym do AGENTS.md (obecnie współzarządzanego z OpenAI, Google, Cursor, Factory, Sourcegraph). Standardy interoperacyjności agentów są obecnie niezależne od dostawcy.²⁷

Narzędzia sandboxa dla skills: Dla zespołów traktujących skills jako powierzchnię ataku, SandyClaw firmy Permiso (wprowadzony 2 kwietnia 2026) uruchamia skills w dedykowanym sandboxie i dostarcza poparte dowodami werdykty pochodzące z detekcji Sigma/YARA/Nova/Snort. Pierwszy produkt w kategorii sandboxów dla skills.²⁸

Sandbox

Claude Code obsługuje opcjonalny tryb sandbox (włączany za pośrednictwem settings.json lub polecenia /sandbox), który ogranicza dostęp do sieci oraz operacje na systemie plików, wykorzystując izolację na poziomie systemu operacyjnego (seatbelt na macOS, bubblewrap na Linuksie). Po włączeniu sandbox uniemożliwia modelowi wykonywanie dowolnych żądań sieciowych ani uzyskiwanie dostępu do plików spoza katalogu projektu. Bez sandboxingu Claude Code stosuje model oparty na uprawnieniach, w którym można zatwierdzać lub odrzucać poszczególne wywołania narzędzi.¹³

Granice uprawnień

System uprawnień bramkuje operacje na wielu poziomach:

Obrona przed prompt injection

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

Skills z ograniczeniami narzędzi uniemożliwiają skompromitowanemu promptowi uzyskanie uprawnień do zapisu:

allowed-tools: Read, Grep, Glob

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

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

Bezpieczeństwo hooks

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

Wzorzec ten polega na tym, że ludzie są odpowiedzialni za decyzje wymagające kontekstu organizacyjnego, oceny etycznej lub kierunku strategicznego. Agenci natomiast odpowiadają za decyzje wymagające obliczeniowego przeszukiwania dużych przestrzeni możliwości. Hooks egzekwują tę granicę.

Rekursywne egzekwowanie hooks

Hooks uruchamiają się także dla działań subagentów.¹³ Jeśli Claude uruchomi subagenta za pośrednictwem narzędzia Agent, hooks PreToolUse i PostToolUse zostaną wykonane dla każdego narzędzia, którego użyje subagent. Bez rekursywnego egzekwowania hooks subagent mógłby ominąć bramki bezpieczeństwa. Zdarzenie SubagentStop umożliwia uruchomienie czyszczenia lub walidacji w momencie zakończenia działania subagenta.

Nie jest to opcjonalne. Agent uruchamiający subagenta bez hooks zabezpieczających to agent, który może wykonać force push do main, odczytać pliki z poświadczeniami albo uruchomić destrukcyjne polecenia, podczas gdy bramki obserwują główną konwersację, w której nic się nie dzieje.

Koszt jako architektura

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

Poziom tokenów. Kompresja system promptu. Należy usunąć przykłady kodu o charakterze instruktażowym (model zna APIs), połączyć zduplikowane reguły z różnych plików oraz zastąpić wyjaśnienia ograniczeniami. „Odrzucaj wywołania narzędzi pasujące do ścieżek wrażliwych” wykonuje tę samą pracę co 15-wierszowe wyjaśnienie, dlaczego nie należy odczytywać poświadczeń.

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

Poziom architektury. Najpierw CLI, a dopiero potem MCP, gdy operacja jest bezstanowa. Wywołanie claude --print na potrzeby jednorazowej oceny jest tańsze i nie generuje narzutu związanego z połączeniem. MCP ma sens wtedy, gdy narzędzie wymaga trwałego stanu lub strumieniowania.

Ramy podejmowania decyzji

Kiedy stosować poszczególne mechanizmy:

Skills a hooks a subagenty

FAQ

Ile hooków to za dużo?

Ograniczeniem jest wydajność, 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 rozłożonych pomiędzy ustawienia poziomu użytkownika i poziomu projektu działa bez zauważalnych opóźnień, gdy każdy hook kończy się w czasie poniżej 200 ms. Próg, na który warto zwrócić uwagę: jeśli hook PostToolUse dodaje ponad 500 ms do każdej edycji pliku, sesja sprawia wrażenie ociężałej. Przed wdrożeniem warto sprofilować hooki za pomocą time.¹⁴

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

Tak. Hooki PreToolUse blokują dowolną akcję narzędzia, kończąc się kodem wyjścia 2. Claude Code anuluje oczekującą akcję i pokazuje modelowi wyjście stderr hooka. Claude widzi powód odrzucenia i sugeruje bezpieczniejszą alternatywę. Kod wyjścia 1 to nieblokujące ostrzeżenie, w którym akcja i tak jest kontynuowana.³

Gdzie należy umieszczać pliki konfiguracji hooków?

Konfiguracje hooków trafiają do pliku .claude/settings.json w przypadku hooków poziomu projektu (zatwierdzanych w repozytorium, współdzielonych z zespołem) lub do ~/.claude/settings.json w przypadku hooków poziomu użytkownika (osobistych, stosowanych w każdym projekcie). Hooki poziomu projektu mają pierwszeństwo, gdy występują równocześnie. Aby uniknąć problemów z katalogiem roboczym, w plikach skryptów warto stosować ścieżki bezwzględne.¹⁴

Czy każda decyzja wymaga deliberacji?

Nie. Moduł oceny pewności punktuje decyzje w czterech wymiarach (niejednoznaczność, złożoność, stawka, zależność od kontekstu). Deliberację uruchamiają wyłącznie decyzje, których łączna pewność wynosi poniżej 0,70 — z grubsza 10% wszystkich decyzji. Poprawki w dokumentacji, zmiany nazw zmiennych i rutynowe edycje całkowicie pomijają deliberację. Architektura bezpieczeństwa, zmiany schematu bazy danych i nieodwracalne wdrożenia uruchamiają ją konsekwentnie.⁷

W jaki sposób przetestować system zaprojektowany do generowania niezgody?

Należy testować zarówno ścieżki sukcesu, jak i ścieżki niepowodzenia. Sukces: agenci produktywnie się nie zgadzają i osiągają konsensus. Niepowodzenie: agenci osiągają zbieżność zbyt szybko, nigdy jej nie osiągają lub przekraczają budżet uruchomień. Testy end-to-end symulują każdy scenariusz przy deterministycznych odpowiedziach agentów, weryfikując, że obie bramki walidacyjne wychwytują każdy udokumentowany tryb awarii. Produkcyjny system deliberacji uruchamia 141 testów w trzech warstwach: 48 testów integracyjnych w bashu, 81 testów jednostkowych Python oraz 12 symulacji potoku end-to-end.⁷

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

Deliberacja z udziałem 3 agentów dokłada 30–60 sekund czasu rzeczywistego (agenci działają sekwencyjnie poprzez Agent tool). Deliberacja z 10 agentami dodaje 2–4 minuty. Hooki konsensusu i pride check kończą się w czasie poniżej 200 ms każdy. 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ły plik poniżej 150 linii. Długie pliki są obcinane przez okna kontekstowe, dlatego najważniejsze instrukcje należy umieszczać na początku: polecenia i definicje zamknięć przed preferencjami stylistycznymi.²¹

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

Zasady architektoniczne (hooki jako deterministyczne bramki, skills jako wiedza dziedzinowa, subagents jako odizolowane konteksty, system plików jako pamięć) pojęciowo dotyczą każdego systemu agentowego. Konkretna implementacja wykorzystuje zdarzenia cyklu życia, wzorce dopasowań i Agent tool z Claude Code. 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 implementacyjne są dla niego 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 skilla

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