W poprzednim wpisie zdefiniowaliśmy, czym jest agent AI. Teraz przyjrzymy się konkretnemu agentowi od środka — Claude Code od Anthropic. To agent terminalowy: działa w Twoim shellu, czyta i edytuje Twoje pliki, uruchamia polecenia, zarządza gitem. Nie jest pluginem do IDE ani chatbotem z doklejonym terminalem — to pełnoprawny agent z pętlą percepcja→rozumowanie→akcja, pamięcią i systemem rozszerzeń.

Architektura Claude Code

Claude Code składa się z kilku warstw, które razem tworzą środowisko agentyczne:

graph TD
    U[Użytkownik] -->|prompt| CC[Claude Code CLI]
    CC -->|kontekst + narzędzia| M[Model Claude 4.x]
    M -->|tool_call| T[Narzędzia wbudowane]
    M -->|tool_call| MCP[Serwery MCP]
    M -->|tool_call| S[Skills]
    T --> FS[System plików]
    T --> SH[Shell / Bash]
    T --> G[Git]
    CC -->|odczyt| CM[CLAUDE.md]
    CC -->|odczyt/zapis| MEM[Pamięć]
    CC -->|hooks| H[Hooks pre/post]

Narzędzia wbudowane

Claude Code ma zestaw narzędzi dostępnych bez konfiguracji:

To nie są "komendy" — to narzędzia w sensie MCP . Każde ma schemat JSON z parametrami, opis dla modelu i walidację. Model wybiera narzędzie na podstawie kontekstu zadania i konstruuje parametry wywołania.

System uprawnień

Claude Code implementuje wielopoziomowy system uprawnień:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run build)",
      "Edit(src/**)"
    ]
  }
}

CLAUDE.md — instrukcja obsługi agenta

CLAUDE.md to plik w korzeniu projektu (lub w ~/.claude/), który Claude Code czyta na starcie każdej sesji. To odpowiednik instrukcji systemowej — ale wersjonowany w git, współdzielony z zespołem i ewoluujący z projektem.

Co warto umieścić w CLAUDE.md:

• Stack technologiczny — "Python 3.13, Flask 3.x, uv, pnpm, Vite"
• Konwencje kodu — "angielskie nazwy zmiennych, brak docstringów, Pydantic zamiast dataclass"
• Workflow — "nigdy nie commituj samodzielnie, zawsze czekaj na vibe check"
• Architektura — blueprint'y, wzorzec feature-driven, gdzie co żyje
• Zakazy — "nie edytuj docs/private/, nie używaj Bootstrap grid"

Dobry CLAUDE.md sprawia, że agent zachowuje się jak nowy członek zespołu, który przeczytał onboarding doc. Zły (lub brakujący) oznacza, że agent zgaduje konwencje — i zgaduje źle.

Anatomia CLAUDE.md

Praktyczny CLAUDE.md ma kilka sekcji:

# Project — Quick Start (TL;DR)
1. Przeczytaj PLAN.md → znajdź pierwszy [ ] na liście.
2. Zrób PoC → pokaż → czekaj na vibe check.
3. Po akceptacji: smoke test → zaktualizuj PROJECT_STATUS.md.
4. Zapytaj o commit — nigdy nie commituj samodzielnie.

# Architecture
- Entry point: app_entry.py
- Blueprinty w app/<feature>/blueprint.py
- Posty w blog_data/<rok>/<slug>/<slug>.md

# Code Style
- Język kodu: angielski
- Brak docstringów — kod ma być samoopisujący
- Pydantic, nie dataclass

# Zakazy
- NIE edytuj docs/private/
- NIE używaj Bootstrap grid (.row, .col-*)
- NIE commituj samodzielnie

Pamięć — jak agent pamięta między sesjami

Claude Code ma wbudowany system pamięci oparty na plikach w ~/.claude/projects/<projekt>/memory/. Działa bez konfiguracji i bez zewnętrznych serwerów MCP.

Typy pamięci

Jak działa

Każda pamięć to osobny plik Markdown z frontmatter:

---
name: no-auto-commit
description: git commit tylko na wyraźną instrukcję użytkownika
metadata:
  type: feedback
---

Git commit tylko po jawnym poleceniu użytkownika.
**Why:** użytkownik chce kontrolować treść commitów.
**How to apply:** po zakończeniu pracy pytaj "czy commitować?"

Pole name to slug w kebab-case (nie pełne zdanie), a type jest zagnieżdżony pod metadata:. W treści pamięci można linkować do powiązanych pamięci składnią [[nazwa-slug]].

Plik MEMORY.md w tym samym katalogu działa jako indeks — lista wskaźników do poszczególnych pamięci (max ~150 znaków na wpis, truncation po 200 liniach).

Czego NIE zapisywać

System pamięci ma wyraźne ograniczenia — nie służy do duplikowania informacji dostępnej innymi kanałami:

• Wzorce kodu, konwencje, architektura, ścieżki plików — to można odczytać z bieżącego stanu projektu
• Git history, kto co zmienił — git log / git blame są autorytatywne
• Rozwiązania debugowania — fix jest w kodzie, kontekst w commit message
• Cokolwiek już udokumentowane w CLAUDE.md
• Efemeryczne detale zadania — bieżący stan pracy, kontekst aktualnej konwersacji

Agent powinien też weryfikować pamięć przed użyciem — jeśli pamięć mówi, że istnieje konkretna funkcja lub plik, agent sprawdza grepem/globem czy to nadal prawda. Pamięć to snapshot z przeszłości, nie stan obecny.

Pamięć vs CLAUDE.md

Plan Mode — myślenie przed działaniem

Claude Code ma dedykowany tryb planowania uruchamiany komendą /plan lub przez Skill EnterPlanMode. W tym trybie agent:

• Nie edytuje plików — tylko czyta i analizuje
• Nie uruchamia poleceń — tylko planuje
• Tworzy strukturalny plan — lista kroków z uzasadnieniem

Plan Mode jest szczególnie przydatny przy:

• Refaktoryzacji dużych modułów ("zanim zaczniesz przerabiać, pokaż mi plan")
• Decyzjach architektonicznych ("rozważ opcje A/B/C")
• Debugowaniu skomplikowanych problemów ("przeanalizuj możliwe przyczyny zanim dotkniesz kodu")

Po wyjściu z Plan Mode (/exitplan) agent ma gotowy plan, który może realizować krok po kroku — z Twoją akceptacją na każdym etapie lub autonomicznie.

Skills — rozszerzalny zestaw umiejętności

Skills to predefiniowane instrukcje, które Claude Code może aktywować w odpowiedzi na polecenie użytkownika (np. /review, /init, /security-review). Skill to nie narzędzie — to zestaw instrukcji, który mówi agentowi, jak podejść do konkretnego typu zadania.

Wbudowane skills:

Skills można pisać samemu — to plik Markdown z instrukcjami, triggerami i opcjonalnymi narzędziami. Szczegóły w poście #5.

Hooks — automatyczna reakcja na zdarzenia

Hooks to skrypty shell, które Claude Code uruchamia w odpowiedzi na zdarzenia agentyczne. Działają jak git hooks, ale dla agenta:

Konfiguracja w settings.json:

{
  "hooks": {
    "PreToolCall": [
      {
        "matcher": "Bash(git push --force*)",
        "command": "echo 'BLOCKED: force push is not allowed' && exit 1"
      }
    ],
    "PostToolCall": [
      {
        "matcher": "Edit(*)",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Hooks dają Ci programowalną kontrolę nad zachowaniem agenta. Zamiast polegać na instrukcji "nie rób X" w CLAUDE.md (którą agent może zignorować), ustawiasz twardy blok na poziomie runtime.

Subagenci — delegowanie podzadań

Claude Code może uruchamiać subagentów — wyspecjalizowane instancje do konkretnych zadań:

• Explore — szybkie przeszukiwanie codebase'u (pliki, grepping, odpowiadanie na pytania o kod)
• Plan — projektowanie strategii implementacji
• general-purpose — ogólne zadania wielokrokowe

Subagent działa w izolacji: ma własny kontekst, nie widzi historii rozmowy z głównym agentem. Dostaje briefing (prompt) i zwraca wynik. To chroni główne okno kontekstowe przed zaśmieceniem wynikami eksploracji.

Agent główny: "Zbadaj, jak działa moduł autoryzacji"
    └─ Subagent (Explore): czyta 15 plików, analizuje flow
       └─ Zwraca: "Moduł auth używa JWT z refresh tokenami,
          walidacja w middleware auth.py:42, config w .env"
Agent główny: kontynuuje z podsumowaniem, nie z 15 plikami w kontekście

Subagenci mogą też działać w worktree — izolowanej kopii repozytorium. Zmiany subagenta nie wpływają na główną kopię roboczą dopóki nie zostaną jawnie zmergowane.

Praktyczny workflow z Claude Code

Typowa sesja z dobrze skonfigurowanym Claude Code — krok po kroku:

Prompt: Napraw buga: formularz kontaktowy nie waliduje emaila po stronie serwera

Krok 1 — Inicjalizacja sesji

Krok 2 — Analiza problemu

Krok 3 — Raport i vibe check

Krok 4 — Commit

Model mentalny: agent jako junior developer

Co dalej

W tym wpisie zobaczyliśmy, jak Claude Code działa od środka. W następnym poście wejdziemy w szczegóły protokołu, który łączy agenta z narzędziami — MCP (Model Context Protocol). Jeśli interesują Cię konkretne serwery MCP (wyszukiwanie, scraping, generowanie obrazków, narzędzia deweloperskie), zajrzyj do serii o MCP .