Claude Code od środka

To nie jest lista funkcji Claude Code. Dokumentacja już to ma, i zmienia się co tydzień. Ten przewodnik jest o mechanizmach: dlaczego Claude czyta pięć plików, zanim edytuje jeden, dlaczego długa sesja robi się gorsza, dlaczego reguła w CLAUDE.md jest prośbą, a hook — gwarancją. Kiedy rozumiesz mechanizm, każda nowa funkcja to po prostu nowe pokrętło w maszynie, którą już znasz.

Droga od zera do eksperta ma cztery etapy. Rozdziały 1–3 budują model mentalny (pętla, terminal, kontekst). Rozdziały 4–8 to codzienne umiejętności (pamięć, uprawnienia, planowanie, prompting, cofanie). Rozdziały 9–12 to warstwa rozszerzeń (skille, subagenci, hooki, MCP, pluginy). Rozdziały 13–16 to warstwa eksperta (sesje równoległe, CI, wybór modelu, nawyki). Każdy rozdział ma jeden interaktywny rysunek: klikaj przyciski, psuj rzeczy, naciśnij ↺ Reset.

Model czatu odpowiada. Agent działa. Claude Code owija model Claude w pętlę z narzędziami: model czyta Twoją prośbę, decyduje, które narzędzie wywołać (przeczytać plik, grep, edytować, uruchomić polecenie shell, pobrać URL), widzi wynik i decyduje ponownie. Powtarza, aż uzna zadanie za skończone — albo aż go przerwiesz.

Dokumentacja opisuje trzy fazy, które przenikają się nawzajem: zbierz kontekst, podejmij działanie, zweryfikuj wyniki. Najważniejsze zdanie w całym tym przewodniku wynika właśnie z tej pętli: Claude jest tak dobry, jak dobra jest jego zdolność do sprawdzenia własnej pracy. Jeśli istnieje test, build, linter albo zrzut ekranu, na który może spojrzeć, pętla zamyka się sama. Jeśli nie — Ty jesteś krokiem weryfikacji.

Zainstaluj natywnym instalatorem i uruchom wewnątrz katalogu projektu:

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

cd my-project
claude            # sesja interaktywna
claude "explain the auth flow"   # start z promptem
claude -c         # kontynuuj najnowszą rozmowę w tym katalogu
claude -r         # wybierz starszą sesję do wznowienia

Ten sam silnik działa w kilku interfejsach: CLI w terminalu, rozszerzenia VS Code i JetBrains, aplikacja Desktop, web pod claude.ai/code (sesje w chmurze, w piaskownicy), aplikacja mobilna i Slack. Dzielą pliki CLAUDE.md Twojego repozytorium, ustawienia i serwery MCP. Z subskrypcją claude.ai możesz przenosić sesję między nimi: /desktop przekazuje sesję z terminala do aplikacji Desktop, --teleport ściąga sesję z chmury do terminala, a /remote-control pozwala sterować lokalną sesją z telefonu.

Wewnątrz prompta kilka znaków zmienia to, co wpisujesz, w coś innego. Naucz się ich, a już używasz Claude Code lepiej niż większość ludzi:

Wszystko, co Claude „wie” w sesji, żyje w jego oknie kontekstu: prompt systemowy, definicje narzędzi, Twój CLAUDE.md, opisy skilli, każda wiadomość, każdy przeczytany plik, każdy wynik polecenia. Okno ma stały rozmiar. Gdy się zapełni, Claude Code kompaktuje: zastępuje starszą historię podsumowaniem. Szczegóły giną w podsumowaniach.

A jest cichszy problem, zanim okno się zapełni: szum. Im więcej nieistotnych rzeczy siedzi w kontekście — dygresja z debugowania, trzy niepowiązane pytania, 2000-liniowy log — tym gorzej Claude trzyma się Twoich instrukcji. Doświadczeni użytkownicy traktują kontekst jak RAM w małej maszynie.

Każda sesja zaczyna się od zera — poza plikami, które Claude Code ładuje automatycznie. Głównym z nich jest CLAUDE.md: zwykły markdown z komendami buildu, konwencjami i regułami „nigdy nie rób X”. Uruchom /init raz, a Claude napisze pierwszą wersję, czytając Twoje repozytorium. Jest kilka poziomów i one się sumują (nie nadpisują się nawzajem):

Co powinno trafić do dobrego projektowego CLAUDE.md? Tylko to, czego Claude nie może się domyślić i czego będzie potrzebować w większości sesji:

# Build i testy
- `pnpm dev` uruchamia aplikację, `pnpm test -- path/to/file` uruchamia jeden plik testowy
- Zawsze uruchom `pnpm typecheck` po zmianie typów

# Konwencje
- Używaj pnpm, nigdy npm. Tylko moduły ES.
- Handlery API mieszkają w src/api/, jeden plik na zasób. Zobacz @docs/api-style.md

# Pułapki
- Folder `legacy/` jest zamrożony. Nigdy go nie edytuj.
- Przy kompaktacji zachowaj listę zmodyfikowanych plików i komendy testów.

Każde wywołanie narzędzia przechodzi przez bramkę. Dwie rzeczy decydują o wyniku: Twoje reguły uprawnień (jawne listy allow / ask / deny) i tryb uprawnień sesji (domyślne zachowanie dla wszystkiego, czego nie dotyczy żadna reguła).

Shift+Tab przełącza default → acceptEdits → plan, a opcjonalne tryby, które włączyłeś, wchodzą po planie. dontAsk nigdy nie jest w cyklu; uruchom go przez --permission-mode dontAsk. Reguły żyją w settings.json pod permissions i są sprawdzane w stałej kolejności: deny, potem ask, potem allow. Wygrywa pierwsze trafienie; specyficzność nie ma znaczenia.

// .claude/settings.json  (dzielone z zespołem — commituj to)
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Bash(git commit *)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)"]
  }
}

Ustawienia też mają warstwy. Dla pojedynczego klucza wyższa warstwa wygrywa — ale klucze list, takie jak permissions.allow i deny, są scalane między warstwami: polityka zarządzana > flagi wiersza poleceń (--settings) > .claude/settings.local.json (Ty, ten projekt) > .claude/settings.json (zespół) > ~/.claude/settings.json (Ty, wszędzie). Nie wiesz, gdzie należy klucz? Zapytaj: /update-config allow npm test — albo uruchom /fewer-permission-prompts, które skanuje Twoją historię i proponuje listę allow bezpiecznych komend tylko do odczytu.

Najczęstszy ruch początkującego to „zaimplementuj funkcję X” jako pierwszy prompt. Claude to zrobi — i rozwiąże problem, który zgadł, nie ten, który masz. Zalecany przepływ pracy oddziela badanie od wykonania:

1. Zbadaj (plan mode): „przeczytaj src/auth i wyjaśnij, jak odświeżane są sesje.” Bez edycji.
2. Zaplanuj: „zaplanuj, jak dodać logowanie przez Google. Które pliki się zmienią? Jaka jest migracja?” Naciśnij Ctrl+G, by samodzielnie edytować plan w swoim edytorze. Zatwierdzenie planu wychodzi z plan mode.
3. Koduj: Claude implementuje zgodnie z planem, odhaczając kolejne punkty.
4. Zweryfikuj i commituj: testy, typecheck, rzut oka na /diff, potem „commituj z jasnym komunikatem i otwórz PR”.

Claude potrafi wywnioskować wiele, ale nie to, co masz w głowie. Każdy fakt, który pominiesz, staje się domysłem, a każdy domysł to szansa na rozwiązanie złego problemu. Dobry prompt nie jest długi — jest konkretny: gdzie patrzeć, co jest nie tak, co znaczy „gotowe” i czego nie ruszać.

Claude Code zapisuje checkpoint przed każdym promptem: stan rozmowy plus zrzuty plików, które Claude edytował. Naciśnij Esc Esc przy pustym prompcie (albo uruchom /rewind), wybierz wiadomość i zdecyduj: przywróć kod, przywróć rozmowę, albo obie — lub podsumuj od tego miejsca. To sprawia, że eksperymenty są tanie: pozwól Claude spróbować śmiałego podejścia i cofnij, jeśli Ci się nie spodoba.

Skilla to folder z SKILL.md: frontmatter YAML plus instrukcje w markdown, opcjonalnie ze skryptami i plikami referencyjnymi obok. Wywołujesz ją jako komendę (/deploy staging), albo Claude ładuje ją sam, gdy Twoje zadanie pasuje do jej description. Niestandardowe slash-komendy zostały scalone ze skillami: stary .claude/commands/deploy.md nadal działa i też tworzy /deploy.

Sztuczka to stopniowe ujawnianie (progressive disclosure). Na starcie sesji w kontekście siedzą tylko nazwa i opis każdej skilli. Pełna treść ładuje się przy użyciu skilli; pliki, do których się odnosi, ładują się tylko, gdy Claude je otworzy. Więc możesz mieć pięćdziesiąt skilli i płacić za pięćdziesiąt krótkich opisów.

.claude/skills/release-notes/SKILL.md
---
name: release-notes
description: Draft release notes from merged PRs since the last tag. Use when asked for a changelog or release notes.
disable-model-invocation: true      # tylko ja mogę ją wywołać (/release-notes)
allowed-tools: Bash(git log *) Bash(gh pr list *)
context: fork                       # uruchom w forkowanym subagencie, zwróć podsumowanie
---
1. Find the last tag with `git describe --tags --abbrev=0`.
2. List merged PRs since then …
3. Group by feat / fix / chore. Output markdown. See [template.md](template.md).

Gdzie żyją skille: ~/.claude/skills/ (Ty, wszystkie projekty), .claude/skills/ (repozytorium — commituj to), zarządzane (Twoja firma) i pluginy (z przestrzenią nazw jak /my-plugin:review). Claude Code dołącza też skille za darmo: /code-review, /simplify, /debug, /batch, /loop, /run, /verify, /doctor, /fewer-permission-prompts i więcej.

Subagent to osobna instancja Claude z własnym oknem kontekstu, własnym promptem systemowym i opcjonalnie własnymi narzędziami, modelem i uprawnieniami. Sesja główna przekazuje mu zadanie; on czyta, szuka, uruchamia różne rzeczy i zwraca tylko podsumowanie. 40 przeczytanych plików nigdy nie trafia do Twojego głównego kontekstu.

Claude sam używa wbudowanych subagentów: Explore (wyszukiwanie w kodzie tylko do odczytu), Plan (badanie podczas plan mode) i general-purpose (eksploracja + modyfikacja, wieloetapowe). Możesz też poprosić: „użyj subagentów, by zbadać, jak płatności, autoryzacja i e-maile każdy obsługuje ponowne próby.” Kilku może działać równolegle.

.claude/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews diffs for injection, authz and secret-handling bugs. Use after changes to auth or API code.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan        # tylko do odczytu
memory: project             # przechowuje własne notatki między sesjami
---
You are a senior application security engineer. For each finding give file:line,
the exploit scenario, and the minimal fix. No style comments.

Inne przydatne pola: skills (wstępne ładowanie pełnych skilli), mcpServers, hooks, maxTurns, effort, isolation: worktree (praca na własnej kopii repozytorium), background: true. Umieszczaj agentów w .claude/agents/ (zespół) albo ~/.claude/agents/ (Ty). Najłatwiejszy sposób napisania jednego: poproś Claude, by go stworzył.

Wszystko do tej pory to rada, którą model interpretuje. Hook jest inny: sam Claude Code uruchamia Twoją komendę shell (albo wywołanie HTTP, narzędzie MCP, prompt lub subagenta), gdy wyzwala się zdarzenie cyklu życia. Zawsze się uruchamia. Może blokować działania, wstrzykiwać kontekst albo po prostu logować. Konfiguruj hooki w settings.json; /hooks pozwala je przeglądać (tylko do odczytu).

{
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh" }] }],
    "PostToolUse": [{ "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "npx prettier --write \"$(jq -r .tool_input.file_path)\"" }] }]
  }
}

Hook dostaje ładunek JSON na stdin (nazwa narzędzia, dane wejściowe, informacje o sesji). Kod wyjścia 0 = jedź dalej; kod wyjścia 2 = zablokuj, a stderr wraca jako powód (dla PreToolUse, Claude go czyta i dostosowuje się). Dla precyzyjniejszej kontroli, wypisz JSON z decyzją.

MCP (Model Context Protocol) łączy Claude z systemami zewnętrznymi jako narzędziami: GitHub, Sentry, Linear, Notion, Twoja baza danych, przeglądarka. Jeśli wciąż kopiujesz dane z karty przeglądarki do czatu, ten system chce być serwerem MCP.

# zdalny serwer HTTP (OAuth w /mcp)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# lokalny serwer stdio: wszystko po -- to komenda serwera
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:…@localhost:5432/app"
# udostępnij zespołowi przez .mcp.json
claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp

Zasięgi MCP nadpisują się po nazwie: lokalny > projekt > użytkownik. Serwery lokalne i użytkownika są zapisane w ~/.claude.json; serwery projektu w .mcp.json w korzeniu repozytorium, które koledzy z zespołu zatwierdzają przy pierwszym użyciu. Nigdy nie commituj tam sekretów — użyj rozwinięcia ${ENV_VAR}.

Pluginy to warstwa pakowania: jedna instalowalna jednostka łącząca skille, subagentów, hooki, serwery MCP (i serwery inteligencji kodu LSP). Dodaj marketplace raz, potem instaluj z niego:

/plugin marketplace add your-org/claude-plugins
/plugin install commit-commands@claude-plugins-official
/plugin            # przeglądaj, włączaj, wyłączaj, wybierz zasięg

Gdy jedna sesja już dobrze działa, kolejnym wąskim gardłem jesteś Ty czekający. Claude Code ma kilka sposobów na uruchomienie więcej niż jednej rzeczy naraz. Pytanie, które je odróżnia: kto trzyma plan?

claude -p "prompt" uruchamia jedno zadanie nieinteraktywnie i wypisuje wynik. Wszystko, czego się nauczyłeś, nadal działa — CLAUDE.md, skille, hooki, MCP — więc wpasowuje się w skrypty, sprawdzenia pre-commit i CI.

# jednorazowe, wlej rurą, wypisz JSON
git diff main | claude -p "review for bugs; reply as a list" --output-format json

# wynik strukturalny walidowany względem schematu (korzeń musi być obiektem)
claude -p "list TODOs" --output-format json \
  --json-schema '{"type":"object","properties":{"todos":{"type":"array","items":{"type":"string"}}},"required":["todos"]}' \
  | jq '.structured_output'

# zamknięte dla CI: wylistowane narzędzia + odczyty / komendy tylko do odczytu; wszystko, co wymagałoby pytania, jest odmawiane
claude -p "run the tests and fix failures" \
  --permission-mode dontAsk --allowedTools "Read" "Edit" "Bash(npm test *)" \
  --max-turns 20 --max-budget-usd 5

# rozgałęzienie po plikach
git ls-files -z 'src/*.js' | while IFS= read -r -d '' f; do   # * w gicie pasuje też przez /
  claude -p "migrate $f from CommonJS to ESM, keep behavior" --allowedTools "Read" "Edit"