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

TL;DR: Claude Code to nie okno czatu z dostępem do plików. To programowalne środowisko uruchomieniowe z 22 zdarzeniami cyklu życia, z których każde można podpiąć za pomocą skryptów powłoki, których model nie jest w stanie pominąć. Złożone w stos hooks tworzą dispatchers, dispatchers składają się w skills, skills w agents, agents w workflows — i otrzymujemy autonomiczny harness deweloperski, który wymusza ograniczenia, deleguje pracę, zachowuje pamięć między sesjami i orkiestruje wieloagentową deliberację. Ten przewodnik obejmuje każdą warstwę tego stosu: od pojedynczego hook do systemu konsensusu 10 agentów. Zero frameworków. Wyłącznie bash i JSON.

Andrej Karpathy ukuł termin na to, co narasta wokół agenta LLM: pazury (ang. claws). Hooks, skrypty i orkiestracja, które pozwalają agentowi chwytać świat poza jego oknem kontekstu.¹ Większość programistów traktuje agentów kodujących z AI 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 zupełnie inny: agent kodujący z AI to programowalne środowisko uruchomieniowe 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 webowy działa w ramach reguł nginx. Nie siedzi się przy nginx i nie wpisuje żądań. Konfiguruje się go, wdraża i monitoruje.

To rozróżnienie ma znaczenie, ponieważ infrastruktura 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 działa spójnie niezależnie od tego, czy wywołuje go użytkownik, czy agent. Agent przeprowadzający przegląd kodu pod kątem bezpieczeństwa wykonuje te same sprawdzenia niezależnie od tego, czy ktoś obserwuje, czy nie.²

Kluczowe wnioski

• Hooks gwarantują wykonanie; prompty — nie. Hooks należy stosować do lintingu, 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ą i aktywują się automatycznie. Pole description decyduje o wszystkim. Claude wykorzystuje rozumowanie LLM (nie dopasowywanie słów kluczowych), aby określić, kiedy zastosować dany skill.⁴
• Subagents zapobiegają rozrostowi kontekstu. Izolowane okna kontekstu do eksploracji i analizy utrzymują główną sesję w zwartej formie. Równolegle może działać do 10 agentów.⁵
• Pamięć żyje 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 wyłapuje 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 wyłapuje błędy strukturalne, których bramki jakościowe nie są w stanie wykryć.⁷
• Wzorzec harness to cały system. CLAUDE.md, hooks, skills, agents i pamięć to nie oddzielne funkcje. Składają się w deterministyczną warstwę między użytkownikiem 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 dostarcza tabelę referencyjną do wyboru właściwego mechanizmu dla każdego typu problemu.

Dlaczego architektura agentowa ma znaczenie

Simon Willison ujmuje obecny moment jedną obserwacją: pisanie kodu jest teraz tanie.⁸ Zgadza się. Ale wynika z tego, że weryfikacja stała się częścią kosztowną. Tani kod bez infrastruktury weryfikacyjnej generuje błędy na masową skalę. Inwestycją, która się zwraca, nie jest lepszy prompt — lecz system wokół modelu, który wyłapuje to, co model pomija.

Trzy siły sprawiają, że architektura agentowa jest niezbędna:

Okna kontekstowe są skończone i stratne. Każdy odczytany plik, wynik narzędzia i tura rozmowy zużywa tokeny. Microsoft Research i Salesforce przetestowali 15 LLM w ponad 200 000 symulowanych rozmów i stwierdzili średni spadek wydajności o 39% między interakcją jednoturową a wieloturową.⁹ Degradacja zaczyna się już po dwóch turach i przebiega według przewidywalnej krzywej: precyzyjne edycje wielu plików w pierwszych 30 minutach zamieniają się w tunelowe widzenie jednego pliku po 90 minutach. Dłuższe okna kontekstowe tego nie naprawią. W tym samym badaniu warunek „Concat” (cała rozmowa jako pojedynczy prompt) osiągnął 95,1% wydajności trybu jednoturowego przy identycznej zawartości. Degradacja wynika z granic tur, nie z limitów tokenów.

Zachowanie modelu jest probabilistyczne, nie deterministyczne. Polecenie Claude „zawsze uruchamiaj Prettier po edycji plików” działa w około 80% przypadków.³ Model może zapomnieć, priorytetyzować szybkość lub uznać, że zmiana jest „zbyt mała”. Dla zgodności, bezpieczeństwa i standardów zespołu 80% to za mało. Hooks gwarantują wykonanie: każdy Edit lub Write uruchamia formatter, za każdym razem, bez wyjątków. Deterministyczne bije probabilistyczne.

Pojedyncza perspektywa nie wychwytuje wielowymiarowych problemów. Pojedynczy agent przeglądający endpoint API sprawdził uwierzytelnianie, zwalidował sanityzację danych wejściowych i zweryfikował nagłówki CORS. Czysta ocena. Drugi agent, wywołany osobno jako tester penetracyjny, odkrył, że endpoint akceptuje nieograniczone parametry zapytań, co mogło wywołać odmowę usługi poprzez multiplikację zapytań do bazy danych.⁷ Pierwszy agent nigdy tego nie sprawdził, ponieważ nic w jego ramach ewaluacyjnych nie traktowało złożoności zapytań jako powierzchni ataku. Ta luka jest strukturalna. Żadna ilość prompt engineeringu jej nie naprawi.

Architektura agentowa odpowiada na wszystkie trzy problemy: hooks wymuszają deterministyczne ograniczenia, subagents zarządzają izolacją kontekstu, a orkiestracja wieloagentowa zapewnia niezależne perspektywy. Razem tworzą harness.

Wzorzec Harness

Harness to nie framework. To wzorzec: komponowalny zestaw plików, skryptów i konwencji, które opakowują agenta kodującego AI 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 reguł definiują, co agent wie o projekcie. Ładują się automatycznie na starcie sesji i po każdej kompakcji. To długoterminowa pamięć architektoniczna agenta.

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

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

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

Jak harness wygląda na dysku

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

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

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

System Skills

Skills to rozszerzenia wywoływane przez model. Claude odkrywa je i stosuje automatycznie na podstawie kontekstu, bez konieczności jawnego wywoływania.⁴ Moment, w którym łapiemy się na ponownym tłumaczeniu tego samego kontekstu między sesjami, to moment, w którym warto zbudować skill.

Kiedy budować skill

Skills służą do wiedzy, którą Claude ma zawsze pod ręką. Slash commands służą do akcji, które jawnie uruchamiamy. Przy wyborze między nimi warto zadać pytanie: „Czy Claude powinien stosować to automatycznie, czy to ja decyduję, kiedy uruchomić?”

Tworzenie skilla

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

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

---
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 od użytkownika oczyszczone przed operacjami na bazie danych
- Zapytania parametryzowane (bez interpolacji ciągów znaków w SQL)
- Kodowanie wyjściowe dla renderowanej zawartości HTML

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

Opis pól frontmatter

Pole description jest kluczowe

Przy starcie sesji Claude Code wyodrębnia name i description każdego skilla i wstrzykuje je do kontekstu Claude. Gdy wysyłane jest zapytanie, Claude wykorzystuje rozumowanie modelu językowego do oceny, czy którykolwiek skill jest odpowiedni. Niezależna analiza kodu źródłowego Claude Code potwierdza ten mechanizm: opisy skilli są wstrzykiwane do sekcji available_skills promptu systemowego, a model używa standardowego rozumienia języka do wyboru odpowiednich skilli.¹⁰

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ć (analiza zmian, PR-ów, jakości kodu) oraz frazy wyzwalające (review, audit, check), które użytkownicy naturalnie wpisują.

Budżet kontekstu

Wszystkie opisy skilli dzielą budżet kontekstu, który skaluje się dynamicznie na poziomie 2% okna kontekstu, z wartością domyślną 16 000 znaków.⁴ Przy dużej liczbie skilli warto zachować zwięzłość każdego opisu. Budżet można nadpisać zmienną środowiskową SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ jednak lepszym rozwiązaniem są krótsze, bardziej precyzyjne opisy. Warto uruchomić /context podczas sesji, aby sprawdzić, czy jakiekolwiek skille są wykluczane.

Pliki pomocnicze i organizacja

Skille 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 umieszcza się w SKILL.md za pomocą linków względnych. Claude odczytuje te pliki na żądanie, gdy skill zostaje aktywowany. SKILL.md powinien mieć poniżej 500 linii, a szczegółowe materiały referencyjne należy przenieść do plików pomocniczych.¹²

Udostępnianie skilli przez Git

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

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

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

Skille jako biblioteka promptów

Poza skillami jednocelowymi, struktura katalogów sprawdza się 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 automatycznie czerpie w zależności od kontekstu. Junior developer otrzymuje wskazówki na poziomie seniora, nie musząc o nie prosić.

Skille współdziałają z hooks

Skille mogą definiować własne hooks we frontmatter, które aktywują się wyłącznie podczas działania skilla. Umożliwia to tworzenie zachowań specyficznych dla domeny, które nie ingerują w inne sesje:²

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

Skille filozoficzne aktywują się automatycznie przez hooks SessionStart, wstrzykując ograniczenia jakościowe do każdej sesji bez jawnego wywoływania. Skill sam w sobie jest wiedzą. Hook jest mechanizmem egzekwowania. Razem tworzą warstwę polityk.

Częste błędy przy tworzeniu skilli

Zbyt szerokie opisy. Skill git-rebase-helper, który aktywuje się przy każdym zapytaniu związanym z gitem (rebase, merge, cherry-pick, nawet git status), zaśmieca 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 skilli konkurujących o budżet. Więcej skilli oznacza więcej opisów konkurujących o 2% budżetu kontekstu. Jeśli skille nie aktywują się prawidłowo, warto sprawdzić /context pod kątem wykluczonych pozycji. Lepiej mieć mniej dobrze opisanych skilli niż wiele niejasnych.

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

Architektura hooks

Hooks to polecenia powłoki wyzwalane przez zdarzenia cyklu życia Claude Code.³ Działają poza LLM jako zwykłe skrypty, a nie prompty interpretowane przez model. Model chce uruchomić rm -rf /? Dziesięciowierszowy skrypt bash sprawdza polecenie na liście zablokowanych 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 22 zdarzenia cyklu życia w sześciu kategoriach:¹³

Semantyka kodów wyjścia

Kody wyjścia określają, czy hooks blokują operacje:³

Uwaga krytyczna: Każdy hook bezpieczeństwa musi używać exit 2, nie exit 1. Exit 1 to nieblokujące ostrzeżenie. Niebezpieczne polecenie mimo wszystko zostanie wykonane. To najczęstszy błąd w konfiguracji hooks w zespołach.¹⁴

Konfiguracja hooks

Hooks definiuje się w plikach ustawień. Na poziomie projektu (.claude/settings.json) dla współdzielonych hooks. Na poziomie użytkownika (~/.claude/settings.json) dla osobistych hooks:

{
  "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. Dla zdarzeń bez narzędzi, takich jak UserPromptSubmit, należy użyć "" (pustego ciągu znaków).

Protokół wejścia/wyjścia hooks

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

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

Dla zaawansowanej kontroli hooks PreToolUse mogą zwracać JSON w celu modyfikacji danych wejściowych narzędzia, wstrzyknięcia kontekstu lub podejmowania decyzji o uprawnieniach:

{
  "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ć sobie pytanie: jakiego rodzaju gwarancji potrzebuję?¹⁴

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

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

Gwarancje bezpieczeństwa zapobiegają niebezpiecznym operacjom przed ich wykonaniem. Hooks PreToolUse na Bash sprawdzają polecenia i blokują destrukcyjne wzorce kodem wyjścia 2:

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

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

Gwarancje jakości walidują stan w kluczowych punktach decyzyjnych. Hooks PreToolUse na poleceniach git commit uruchamiają linter lub zestaw testów i blokują commit, jeśli kontrola jakości nie zostanie zaliczona:

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

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

Typy hooks wykraczające poza polecenia powłoki

Claude Code obsługuje trzy typy hooks:¹³

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

Hooks promptów (type: "prompt") wysyłają jednoturowy prompt do szybkiego modelu Claude. Model zwraca { "ok": true }, aby zezwolić, lub { "ok": false, "reason": "..." }, aby zablokować. Warto stosować do niuansowej oceny, której wyrażenia regularne nie są w stanie wyrazić.

Hooks agentowe (type: "agent") uruchamiają subagenta z dostępem do narzędzi (Read, Grep, Glob) do wieloturowej weryfikacji. Należy stosować, gdy sprawdzenie wymaga 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
          }
        ]
      }
    ]
  }
}

Hooks asynchroniczne

Hooks mogą działać w tle bez blokowania wykonania. Dodanie async: true sprawdza się przy niekrytycznych operacjach, takich jak powiadomienia i logowanie:¹³

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

Tryb asynchroniczny warto stosować do powiadomień, telemetrii i kopii zapasowych. Nigdy nie należy go używać do formatowania, walidacji ani czegokolwiek, co musi zakończyć się przed kolejną operacją.

Dispatcher zamiast niezależnych hooks

Siedem hooks uruchamianych na tym samym zdarzeniu, z których każdy niezależnie czyta stdin, tworzy warunki wyścigu. Dwa hooks zapisujące jednocześnie do tego samego pliku stanu JSON obetną JSON. Każdy kolejny hook parsujący ten plik ulegnie awarii.²

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

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

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

Debugowanie hooks

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

1. Testowanie skryptów niezależnie. Przekazanie przykładowego JSON potokiem: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Używanie stderr do komunikatów debugowania. Wszystko zapisane na stderr pojawia się w kontekście Claude.
3. Uważanie na błędy jq. Nieprawidłowe ścieżki JSON zwracają null po cichu. Wyrażenia jq należy testować na rzeczywistych danych wejściowych narzędzia.
4. Weryfikacja kodów wyjścia. Hook PreToolUse używający exit 1 nie zapewnia żadnego egzekwowania, choć sprawia wrażenie działającego.
5. Utrzymywanie szybkości hooks. Hooks uruchamiają się synchronicznie. Wszystkie hooks powinny działać poniżej 2 sekund, najlepiej poniżej 500 ms.

Pamięć i kontekst

Każda rozmowa z AI odbywa się w ramach skończonego okna kontekstu. W miarę rozrastania się konwersacji 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 utraty spójności w wielu turach

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ęć wykraczająca poza granice kontekstu znajduje się w systemie plików. Claude Code odczytuje CLAUDE.md i pliki pamięci na początku każdej sesji oraz po każdej kompakcji.⁶

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

Plik MEMORY.md przechowuje błędy, decyzje i wzorce między sesjami. Gdy odkryjesz, że ((VAR++)) kończy się błędem przy set -e w bashu, gdy VAR wynosi 0, zapisujesz to. Trzy sesje później, napotykając podobny przypadek brzegowy z liczbami całkowitymi w Python, wpis w MEMORY.md przywołuje ten wzorzec.¹⁵

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

Strategia 2: Proaktywna kompakcja

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

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

Niestandardowe instrukcje kompakcji 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ń obejmujących wiele sesji warto tworzyć dokumenty przekazania, które utrwalają pełny stan:

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

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

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

Przy sesjach trwających dłużej niż 60-90 minut warto uruchomić nową instancję Claude dla każdej iteracji. Stan jest utrwalany 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 ze świeżym kontekstem na iterację wymaga 15-20% narzutu na fazę orientacji (odczytywanie plików stanu, przeglądanie historii git), ale w zamian zapewnia pełne zasoby kognitywne w każdej iteracji.¹⁶ Rachunek kosztów i korzyści: przy sesjach krótszych niż 60 minut pojedyncza konwersacja jest wydajniejsza. Powyżej 90 minut świeży kontekst daje wyższą jakość wyników pomimo narzutu.

Antywzorce

Odczytywanie całych plików, gdy potrzebujesz 10 linii. Pojedynczy odczyt pliku o 2000 liniach zużywa 15 000-20 000 tokenów. Stosowanie przesunięć: Read file.py offset=100 limit=20 pozwala zaoszczędzić zdecydowaną większość tego kosztu.¹⁵

Trzymanie rozwlekłych komunikatów o błędach w kontekście. Po zdebugowaniu błędu kontekst zawiera ponad 40 śladów stosu z nieudanych iteracji. Jedno /compact po naprawieniu błędu uwalnia ten martwy balast.

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

Wzorce subagents

Subagents to wyspecjalizowane instancje Claude, które samodzielnie obsługują złożone zadania. Uruchamiają się z czystym kontekstem (bez zanieczyszczeń z głównej konwersacji), działają z określonymi narzędziami i zwracają wyniki w formie podsumowań. Rezultaty eksploracji nie obciążają głównej konwersacji — wracają jedynie wnioski.⁵

Wbudowane typy subagents

Tworzenie własnych subagents

Subagents definiuje się 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 subagents

Izolacja worktree

Subagents mogą działać w tymczasowych git worktrees, zapewniając pełną izolowaną kopię repozytorium:⁵

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

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

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

Równoległe subagents

Claude Code obsługuje do 10 równoległych subagents.⁵ Równoległe wykonywanie warto wykorzystać przy niezależnych zadaniach 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, wyszukuje odpowiedni kod i zwraca podsumowanie. Główny kontekst pozostaje czysty.

Zabezpieczenie przed rekurencją

Bez limitów uruchamiania agenty delegują do agentów, które delegują do kolejnych agentów — każdy tracąc kontekst i zużywając tokeny. Wzorzec recursion guard wymusza budżety:¹⁶

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

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

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

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

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

Kluczowa lekcja: należy stosować budżety uruchamiania, a nie tylko limity głębokości. Limity oparte na głębokości śledzą łańcuchy rodzic-dziecko (blokada na głębokości 3), ale nie wychwytują szerokości: 23 agenty na głębokości 1 to wciąż „głębokość 1”. Budżet uruchamiania śledzi łączną liczbę aktywnych potomków na rodzica z konfigurowalnym maksimum. Model budżetowy odpowiada rzeczywistemu trybowi awarii (zbyt wiele 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 działających niezależnie, komunikujących się poprzez współdzieloną skrzynkę pocztową i listę zadań, z możliwością kwestionowania wzajemnych ustaleń:⁵

Aktywacja: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Kiedy stosować agent teams zamiast subagents:

Orkiestracja wieloagentowa

Jednoagentowe systemy AI mają strukturalną ślepą plamkę: nie są w stanie zakwestionować własnych założeń.⁷ Wieloagentowa deliberacja wymusza niezależną ocenę z wielu perspektyw, zanim jakakolwiek decyzja zostanie podjęta.

Minimalna użyteczna deliberacja

Warto zacząć od 2 agentów i 1 zasady: agenci muszą dokonać oceny niezależnie, zanim zobaczą wyniki pracy drugiego.⁷

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 przynosi jedynie przyrostowe usprawnienia.

Wyzwalacz pewności

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

1. Niejednoznaczność — Czy zapytanie dopuszcza wiele poprawnych interpretacji?
2. Złożoność dziedzinowa — Czy wymaga wiedzy specjalistycznej?
3. Stawka — Czy decyzja jest odwracalna?
4. Zależność kontekstowa — Czy wymaga zrozumienia szerszego systemu?

Wynik przekłada się na trzy poziomy:

Próg dostosowuje się do typu zadania. Decyzje dotyczące bezpieczeństwa wymagają konsensusu na poziomie 0,85. Zmiany w dokumentacji — jedynie 0,50. Zapobiega to nadmiernej inżynierii prostych zadań, jednocześnie zapewniając kontrolę nad ryzykownymi decyzjami.⁷

Maszyna stanów

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

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

RESEARCH: Niezależni agenci badają temat. Każdy agent otrzymuje inną personę (architekt techniczny, analityk bezpieczeństwa, inżynier wydajności i inne). Izolacja kontekstu gwarantuje, że agenci nie widzą wzajemnych ustaleń podczas badań.

DELIBERATION: Agenci widzą wszystkie wyniki badań i generują alternatywy. Agent debatujący identyfikuje konflikty. Agent syntezy łączy niesprzeczne ustalenia.

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

Dwubramkowa architektura walidacji

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

Bramka 1: Walidacja konsensusu (hook PostToolUse). Uruchamiana natychmiast po zakończeniu pracy każdego agenta deliberacyjnego: 1. Faza musi osiągnąć co najmniej RANKING 2. Minimum 2 agentów ukończonych (konfigurowalne) 3. Wynik konsensusu spełnia adaptacyjny próg zadania 4. Jeśli którykolwiek agent zgłosił sprzeciw, zastrzeżenia muszą być udokumentowane

Bramka 2: Pride Check (hook Stop). Uruchamiana przed zamknięciem sesji: 1. Różnorodność metod: reprezentacja wielu 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. Dowód 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), a inne narastające (niska różnorodność, brak dokumentacji sprzeciwów).⁷

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 oponentami podejmują lepsze decyzje niż grupy osiągające szybki konsensus. Oponent nie musi mieć racji. Sam akt sprzeciwu zmusza większość do zbadania założeń, które w przeciwnym razie zostałyby pominięte.¹⁸

Wu i in. sprawdzili, czy agenci LLM potrafią prowadzić autentyczną debatę, i stwierdzili, że bez strukturalnych zachęt do niezgody agenci konwergują ku najbardziej pewnie brzmiącej początkowej odpowiedzi, niezależnie od jej poprawności.¹⁹ Liang i in. zidentyfikowali przyczynę źródłową jako „Degenerację myśli” (Degeneration-of-Thought): gdy LLM ugruntuje pewność co do danego stanowiska, autorefleksja nie jest w stanie wygenerować nowych kontrargumentów, co czyni wieloagentową ewaluację strukturalnie konieczną.²⁰

Niezależność to kluczowe ograniczenie projektowe. Dwóch agentów oceniających tę samą strategię wdrożenia z wglądem we wzajemne ustalenia uzyskało wyniki 0,45 i 0,48. Ci sami agenci bez wzajemnego wglądu: 0,45 i 0,72. Różnica między 0,48 a 0,72 to koszt stadnego zachowania.⁷

Wykrywanie pozornej zgody

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

Skupianie wyników: Gdy wszyscy agenci przyznają oceny w zakresie 0,3 punktu na 10-punktowej skali, sygnalizuje to kontaminację wspólnym kontekstem, a nie niezależną ocenę. Kiedy pięciu agentów oceniających refaktoryzację uwierzytelniania przyznało ryzyku bezpieczeństwa noty od 7,1 do 7,4, ponowne uruchomienie z odświeżoną izolacją kontekstu rozciągnęło wyniki do zakresu 5,8–8,9.

Szablonowy sprzeciw: Agenci kopiujący nawzajem język zastrzeżeń zamiast generowania niezależnych obiekcji.

Brak perspektywy mniejszości: Jednogłośna aprobata ze strony person o sprzecznych priorytetach (analityk bezpieczeństwa i inżynier wydajności rzadko zgadzają się we wszystkim).

Detektor konformizmu wychwytuje oczywiste przypadki (około 10–15% deliberacji, w których agenci zbiegają się zbyt szybko). W 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 tekstowej na temat indeksowania bazy danych wygenerowały 7 500 tokenów debaty. Runda 1: autentyczna niezgoda. Runda 2: powtórzone stanowiska. Runda 3: identyczne argumenty innymi słowami. Strukturalna ocena wymiarowa 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ł niepowiązane zadania przez 20 minut, zanim hook końca sesji zgłosił błąd. Podział na dwie bramki (jedna przy zakończeniu zadania, druga przy końcu 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 — około 50 000–80 000 tokenów.⁷

Przy obecnych cenach Opus 3-agentowa deliberacja kosztuje około 0,68–0,90 USD. 10-agentowa deliberacja kosztuje 2,25–3,00 USD. System uruchamia deliberację dla około 10% decyzji, więc zamortyzowany koszt w przeliczeniu na wszystkie decyzje wynosi 0,23–0,30 USD za sesję. Czy to się opłaca, zależy od tego, ile kosztuje zła decyzja.

Kiedy deliberować

Projektowanie CLAUDE.md

CLAUDE.md to polityka operacyjna dla agenta AI, a nie README dla ludzi.²¹ Agent nie musi rozumieć, dlaczego stosowane są konwencjonalne commity. Musi znać dokładne polecenie do uruchomienia i wiedzieć, jak wygląda stan „gotowe”.

Hierarchia pierwszeństwa

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

Co jest ignorowane

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

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

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

Sprzeczne priorytety. „Działaj szybko i wdrażaj” plus „Zapewnij kompleksowe pokrycie testami” plus „Utrzymuj czas wykonania poniżej 5 minut” plus „Uruchom 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 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 zamknięcia:

## Definicja ukończenia
Zadanie jest ukończone, gdy WSZYSTKIE poniższe warunki są spełnione:
1. `ruff check .` kończy się kodem 0
2. `pytest -v` kończy się kodem 0 bez żadnych błędów
3. `mypy app/ --strict` kończy się kodem 0
4. Zmienione pliki zostały dodane do staging i zatwierdzone
5. Komunikat commita jest zgodny z formatem konwencjonalnym: `type(scope): description`

Sekcje zorganizowane według zadań:

## Podczas pisania kodu
- Uruchamiaj `ruff check .` po każdej zmianie pliku
- Dodawaj type hints do wszystkich nowych funkcji

## Podczas przeglądu kodu
- Sprawdzaj problemy bezpieczeństwa: `bandit -r app/`
- Weryfikuj pokrycie testami: `pytest --cov=app --cov-fail-under=80`

## Podczas wydawania
- Zaktualizuj wersję w `pyproject.toml`
- Uruchom pełny zestaw: `pytest -v && ruff check . && mypy app/`

Reguły eskalacji:

## W przypadku zablokowania
- Jeśli testy nie przechodzą po 3 próbach: zatrzymaj się i zgłoś nieprzechodzący test z pełnym wynikiem
- Jeśli brakuje zależności: najpierw sprawdź `requirements.txt`, potem zapytaj
- Nigdy: nie usuwaj plików w celu rozwiązania błędów, nie używaj force push, nie pomijaj testów

Kolejność dodawania sekcji

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 zakończeniom)
3. Reguły eskalacji (zapobiega destrukcyjnym obejściom)
4. Sekcje zorganizowane według zadań (ogranicza parsowanie nieistotnych instrukcji)
5. Zakres katalogów (monorepo: izoluje instrukcje poszczególnych serwisów)

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

Importy plików

Odwoływanie się do innych plików w ramach CLAUDE.md:

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

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

Kompatybilność instrukcji między narzędziami

AGENTS.md to otwarty standard przyjęty przez ponad 60 000 projektów i rozpoznawany przez każde główne narzędzie AI do kodowania.²¹ Jeśli zespół korzysta z wielu narzędzi, należy pisać AGENTS.md jako kanoniczne źródło i kopiować odpowiednie sekcje do plików specyficznych dla danego narzędzia:

Wzorce z AGENTS.md (polecenia na początku, zamknięcia definiujące zakres, organizacja według 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 z czasem się rozjeżdżają. Warto napisać jedno autorytatywne źródło i je kopiować.

Testowanie instrukcji

Weryfikacja, czy agent faktycznie odczytuje i stosuje instrukcje:

# 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 decydujący: należy poprosić agenta o wyjaśnienie poleceń budowania. Jeśli nie potrafi odtworzyć ich dosłownie, instrukcje są albo zbyt rozwlekłe (treść wypchana poza kontekst), albo zbyt ogólnikowe (agent nie może wyodrębnić konkretnych działań), albo w ogóle nie są wykrywane. Analiza 2500 repozytoriów przeprowadzona przez GitHub wykazała, że ogólnikowość jest najczęstszą przyczyną niepowodzeń.²¹

Wzorce produkcyjne

Quality loop

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

1. Implementacja — napisz kod
2. Przegląd — przeczytaj ponownie każdą linię. Wyłap literówki, błędy logiczne, niejasne fragmenty
3. Ewaluacja — uruchom evidence gate. Sprawdź wzorce, przypadki brzegowe, pokrycie testami
4. Udoskonalenie — napraw każdy problem. Nigdy nie odkładaj na „później”
5. Szersze spojrzenie — sprawdź punkty integracji, importy, sąsiedni kod pod kątem regresji
6. Powtórzenie — jeśli którekolwiek kryterium evidence gate nie przejdzie, wróć do kroku 4
7. Raport — wymień co się zmieniło, jak zweryfikowano, powołaj się na konkretne dowody

Evidence gate

„Uważam, że” i „powinno działać” to nie są dowody. Należy powoływać się na ś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 Udoskonalenie.²²

Wzorce obsługi błędów

Atomowe zapisy plików. Wielu agentów zapisujących jednocześnie do tego samego pliku stanu powoduje uszkodzenie JSON. Należy zapisywać do plików .tmp, a następnie przenosić atomowo za pomocą mv. System operacyjny gwarantuje, że mv jest operacją atomową 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. W przypadku uszkodzenia stanu wzorzec odzyskiwania odtwarza dane z bezpiecznych wartości domyślnych zamiast przerywać działanie:¹⁶

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

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

Klasyfikacja zasięgu oddziaływania

Każdą akcję agenta należy sklasyfikować według zasięgu oddziaływania i odpowiednio ją bramkować:²

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

Specyfikacja zadań dla autonomicznych uruchomień

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

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

Kryteria muszą być weryfikowalne maszynowo: wynik testu pass/fail, wyjście lintera, kody statusu HTTP, sprawdzenie istnienia plików. Wczesne zadanie, które prosiło agenta o „napisanie testów, które przechodzą”, dało w wyniku assert True i assert 1 == 1. Technicznie poprawne. Praktycznie bezwartościowe.¹⁶

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

Konkretny ślad sesji

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

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

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

3. Agent wywołuje Bash w celu uruchomienia testów. Uruchamia się PreToolUse:Bash. Sprawdzenie poświadczeń, walidacja sandboxa, wykrywanie projektu. 90 ms. Testy się uruchamiają. Uruchamia się PostToolUse:Bash: logowany jest heartbeat aktywności, sprawdzenie dryfu.

4. Agent wywołuje Write w celu utworzenia pliku. Uruchamia się PreToolUse:Write: sprawdzenie zakresu pliku. Uruchamia się PostToolUse:Write: sprawdzenie lintera, śledzenie commitów.

5. Agent kończy story. Uruchamia się Stop. Bramki jakości sprawdzają: czy agent powołał się na dowody? Język spekulatywny? Komentarze TODO w diffie? Jeśli którekolwiek sprawdzenie nie przejdzie, zwracany jest exit 2 i agent kontynuuje pracę.

6. Niezależna weryfikacja: nowy agent uruchamia zestaw testów bez polegania na samoocenie poprzedniego agenta.

7. Trzy agenty code review uruchamiają się równolegle. Każdy recenzuje diff niezależnie. Jeśli którykolwiek recenzent oznaczy problem jako CRITICAL, story wraca do kolejki.

8. Story przechodzi. Ładowana jest następna story. Cykl powtarza się dla wszystkich 5 stories.

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

Kwestie bezpieczeństwa

Piaskownica (sandbox)

Claude Code działa w piaskownicy, która ogranicza dostęp do sieci oraz operacje na systemie plików. Piaskownica uniemożliwia modelowi wykonywanie dowolnych żądań sieciowych lub dostęp do plików poza katalogiem projektu.¹³

Granice uprawnień

System uprawnień kontroluje operacje na wielu poziomach:

Obrona przed wstrzykiwaniem promptów

Skills i hooks zapewniają wielowarstwową ochronę przed wstrzykiwaniem promptów:

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

allowed-tools: Read, Grep, Glob

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

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

Izolacja subagentó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ów

Hooki HTTP, które interpolują zmienne środowiskowe do nagłówków, wymagają jawnej listy allowedEnvVars, aby zapobiec ekstrakcji dowolnych zmiennych środowiskowych:¹³

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

Podział odpowiedzialności między człowiekiem a agentem

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

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

Rekurencyjne egzekwowanie hooków

Hooki uruchamiają się również dla akcji subagentów.¹³ Jeśli Claude uruchomi subagenta za pomocą Agent tool, hooki PreToolUse i PostToolUse wykonają się dla każdego narzędzia użytego przez subagenta. Bez rekurencyjnego egzekwowania hooków subagent mógłby obejść bramki bezpieczeństwa. Zdarzenie SubagentStop umożliwia uruchomienie czyszczenia lub walidacji po zakończeniu pracy subagenta.

To nie jest opcjonalne. Agent, który uruchamia subagenta bez hooków bezpieczeństwa, to agent, który może wymusić push na main, odczytać pliki z poświadczeniami lub wykonać destrukcyjne polecenia, podczas gdy bramki bezpieczeństwa bezczynnie obserwują główną konwersację.

Koszt jako element architektury

Koszt jest decyzją architektoniczną, a nie kwestią operacyjną rozwiązywaną po fakcie.² Można go rozpatrywać na trzech poziomach:

Poziom tokenów. Kompresja promptu systemowego. Warto usunąć przykłady kodu z tutoriali (model zna API), skonsolidować zduplikowane reguły w plikach i zastąpić objaśnienia ograniczeniami. „Odrzucaj wywołania narzędzi pasujące do wrażliwych ścieżek” realizuje to samo zadanie co 15-wierszowe wyjaśnienie, dlaczego nie należy odczytywać poświadczeń.

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

Poziom architektury. Podejście CLI-first zamiast MCP, gdy operacja jest bezstanowa. Wywołanie claude --print dla jednorazowej ewaluacji kosztuje mniej i nie generuje narzutu połączeniowego. MCP ma sens, gdy narzędzie wymaga trwałego stanu lub streamowania.

Ramy decyzyjne

Kiedy stosować poszczególne mechanizmy:

Skills vs hooks vs subagenty

FAQ

Ile hooków to za dużo?

Ograniczeniem jest wydajność, nie liczba. Każdy hook uruchamia się synchronicznie, więc łączny czas wykonania hooków dodaje się do każdego pasującego wywołania narzędzia. 95 hooków na poziomie użytkownika i projektu działa bez zauważalnych opóźnień, gdy każdy hook kończy się w mniej niż 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 staje się ociężała. Warto profilować hooki za pomocą time przed ich wdrożeniem.¹⁴

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

Tak. Hooki PreToolUse blokują dowolną akcję narzędzia, kończąc działanie z kodem wyjścia 2. Claude Code anuluje oczekującą akcję i wyświetla modelowi wyjście stderr hooka. Claude widzi powód odrzucenia i proponuje bezpieczniejszą alternatywę. Kod wyjścia 1 to nieblokujące ostrzeżenie — akcja jest mimo to wykonywana.³

Gdzie umieszczać pliki konfiguracyjne hooków?

Konfiguracje hooków należy umieszczać w .claude/settings.json dla hooków na poziomie projektu (commitowane do repozytorium, współdzielone z zespołem) lub w ~/.claude/settings.json dla hooków na poziomie użytkownika (osobiste, stosowane do każdego projektu). Hooki na poziomie projektu mają pierwszeństwo, gdy istnieją oba pliki. Warto używać ścieżek bezwzględnych dla plików skryptów, 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 z ogólnym wynikiem pewności poniżej 0,70 wyzwalają deliberację — to mniej więcej 10% wszystkich decyzji. Poprawki dokumentacji, zmiany nazw zmiennych i rutynowe edycje pomijają deliberację całkowicie. Architektura bezpieczeństwa, zmiany schematu bazy danych i nieodwracalne wdrożenia wyzwalają ją konsekwentnie.⁷

Jak testować system zaprojektowany do generowania rozbieżności?

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 zbyt szybko się zgadzają, nigdy nie dochodzą do porozumienia lub przekraczają budżety instancji. Testy end-to-end symulują każdy scenariusz z deterministycznymi odpowiedziami agentów, weryfikując, że bramki walidacyjne wyłapują każdy udokumentowany tryb awarii. Produkcyjny system deliberacji uruchamia 141 testów w trzech warstwach: 48 testów integracyjnych bash, 81 testów jednostkowych Python i 12 symulacji pipeline’u end-to-end.⁷

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

Deliberacja z 3 agentami dodaje 30–60 sekund czasu zegarowego (agenci uruchamiają się sekwencyjnie przez Agent tool). Deliberacja z 10 agentami dodaje 2–4 minuty. Hooki konsensusu i pride check wykonują się w mniej niż 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żda sekcja powinna mieć mniej niż 50 wierszy, a cały plik nie powinien przekraczać 150 wierszy. Długie pliki są obcinane przez okna kontekstu, dlatego najważniejsze instrukcje należy umieszczać na początku: polecenia i definicje zamknięć przed preferencjami stylistycznymi.²¹

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

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

Skrócona karta referencyjna

Konfiguracja hooks

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

Frontmatter skills

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

Definicja subagents

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

Historia zmian

Źródła