Claude Code workflow: kompletny przewodnik po CLAUDE.md, skills i hooks

Czym właściwie jest Claude Code i dlaczego to nie jest zwykły asystent AI?

Claude Code to agentyczne narzędzie CLI, które żyje w twoim terminalu, rozumie strukturę kodu bazy i pomaga pisać szybciej – wykonując rutynowe zadania, wyjaśniając złożony kod i obsługując workflow gitowy przez komendy w języku naturalnym. Kluczowe słowo to „agentyczne”: model nie tylko podpowiada, ale planuje sekwencję działań, wykonuje je i weryfikuje wynik.

Różnica wobec ChatGPT czy prostych pluginów do IDE jest fundamentalna. Claude Code czyta realne pliki, uruchamia komendy bash, commituje zmiany i komunikuje się z zewnętrznymi API przez serwery MCP. Nie pracuje na wyimaginowanym kodzie. Działa na twoim.

Instalacja i pierwsze uruchomienie

Wymagania są proste: Node.js 18+. Instalacja jedną komendą:

curl -fsSL https://claude.ai/install.sh | bash

Po instalacji przejdź do katalogu projektu i uruchom claude /init. Claude przeskanuje bazę kodu i wygeneruje startowy plik pamięci. To punkt wyjścia, który potem dostosowujesz do swoich potrzeb.

CLAUDE.md – pamięć projektu, którą agent czyta przy każdej sesji

CLAUDE.md to plik Markdown, który Claude Code ładuje automatycznie na początku każdej sesji. Nie musisz za każdym razem tłumaczyć agentowi, jak zbudowany jest twój projekt. Piszesz to raz. Dobrze zbudowany CLAUDE.md to jak onboarding dla nowego seniora: stack technologiczny, architektura katalogów, komendy do uruchomienia testów i lintingu, wzorce, których agent ma unikać.

Hierarchia plików pamięci

Claude Code obsługuje kilka poziomów CLAUDE.md, a każdy kolejny dopisuje kontekst – nie nadpisuje poprzedniego. To ważne, żeby rozumieć zanim zaczniesz konfigurować środowisko.

Każdy plik powinien mieć mniej niż 200 linii. Przekroczenie tej granicy to sygnał, że próbujesz wcisnąć do pamięci rzeczy, które lepiej obsłuży skill lub hook.

Co wpisywać do CLAUDE.md?

• Stack technologiczny: Konkretne wersje frameworków, baza danych, architektura (np. FastAPI + React SPA + Postgres).
• Komendy projektu: Jak uruchomić serwer dev, testy, linting. Agent nie musi ich zgadywać.
• Architektura katalogów: Co gdzie siedzi i dlaczego. Np. /app → Next.js pages, /lib → shared utilities.
• Decyzje projektowe: Dlaczego wybrałeś konkretne wzorce, jakich anti-patterns unikać.
• Reguły workflow: Konwencje commitów, proces code review, kiedy tworzyć PR.

Skills – supermoc, którą instalujesz jeden raz

Skills to pliki SKILL.md przechowywane w .claude/skills/<nazwa>/SKILL.md. Każdy skill to wyspecjalizowany zestaw instrukcji, który Claude invokuje automatycznie na podstawie kontekstu lub na żądanie slash commandem. Prosty przykład: skill /commit automatycznie tworzy conventional commit po przejrzeniu staged zmian – bez wpisywania za każdym razem tej samej instrukcji.

Tu robi się ciekawie. Skills można instalować nie tylko ręcznie, ale też przez npm:

npx skills add anthropics/claude-code --skill frontend-design

Format SKILL.md jest kompatybilny z Claude Code, Cursor, Gemini CLI i innymi agentami. Skill napisany raz działa wszędzie. Ekosystem oficjalnych skills Anthropic liczy dziś kilkadziesiąt pozycji, a community dodaje kolejne.

Jak zbudować własny skill?

Struktura jest prosta. Utwórz katalog i plik:

mkdir -p .claude/skills/pr-review
cat > .claude/skills/pr-review/SKILL.md

Frontmatter YAML definiuje nazwę i opis – i tu jest haczyk. Pole description jest absolutnie krytyczne. Claude używa go do decydowania, kiedy skill powinien się aktywować automatycznie. Złe opisy = skill nigdy nie odpali sam.

Skill vs. agent – kiedy co wybrać?

• Skill: Wstrzykuje instrukcje do bieżącego kontekstu rozmowy. Idealny do reużywalnych instrukcji i workflow, które agent wykonuje w głównym wątku.
• Agent: Spawnuje oddzielne okno kontekstu z własnym system promptem i restrykcjami narzędzi. Stosuj, gdy potrzebujesz izolacji, kontroli kosztów (tańszy model dla prostych zadań) lub ścisłych limitów uprawnień.

Hooks – jedyna metoda, której agent nie zignoruje

Hooks to deterministyczne skrypty powłoki odpalane na konkretnych zdarzeniach wewnątrz Claude Code. W przeciwieństwie do instrukcji w CLAUDE.md, które model może zinterpretować elastycznie, hooks to twarde reguły. Jeśli hook zwróci exit code 1 – akcja jest zablokowana, bez negocjacji.

Tę właściwość warto zrozumieć przed konfiguracją. CLAUDE.md mówi Claude’owi, co robić. Hooks go do tego zmuszają.

Rodzaje zdarzeń hookowych

• PreToolUse: Odpala się przed wykonaniem narzędzia przez agenta. Idealny do blokowania niebezpiecznych operacji (np. commit pliku z sekretami).
• PostToolUse: Po wykonaniu narzędzia. Świetny do auto-formatowania kodu po każdej edycji pliku.
• SessionStart: Na początku sesji. Ładuj dynamiczny kontekst, zmienne środowiskowe, ostatnie commity.
• Stop: Gdy agent kończy odpowiedź. Możesz go nakłonić do weryfikacji własnej pracy.

Praktyczny przykład: hook blokujący commit plików z credentials:

if git diff --cached --name-only | grep -qE '\.(env|key|pem)$'; then
  echo "BLOCKED: credential files detected"
  exit 1
fi

Ten jeden hook pozwala uruchamiać agenta bez nadzoru – 24/7, na serwerze – bez ryzyka wycieku danych.

Konfiguracja hooks w settings.json

Hooks definiujesz w pliku .claude/settings.json. Pamiętaj: hooks są ładowane przy starcie sesji. Zmiany wymagają restartu Claude Code.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "scripts/security-check.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

4-warstwowa architektura – jak to wszystko działa razem

Claude Code nie jest monolitem. To system czterech warstw, z których każda ma swoją rolę. Zrozumienie tej hierarchii wyjaśnia, dlaczego pewne konfiguracje działają, a inne nie.

Każda warstwa rozwiązuje inny problem. L1 odpowiada na pytanie „co agent powinien wiedzieć”, L2 na „jakie specjalistyczne instrukcje zastosować”, L3 na „co musi się zawsze wydarzyć niezależnie od decyzji modelu”, a L4 na „jak delegować złożone zadania do wyspecjalizowanych jednostek”.

Codzienny workflow – od uruchomienia do commita

Teoria to teoria. Oto praktyczny schemat sesji, który możesz wdrożyć od razu.

1. Wejdź do projektu i uruchom Claude Code – cd your-project && claude. Agent załaduje CLAUDE.md i aktywne hooks automatycznie.
2. Włącz Plan Mode skrótem Shift + Tab + Tab – przed każdym nietrywialnym zadaniem. Opisz intencję, nie implementację. Claude zaplanuje sekwencję kroków i przedstawi ją do zatwierdzenia.
3. Zatwierdź plan i włącz Auto Accept skrótem Shift + Tab – agent wykona wszystkie akcje bez przerywania na każdym kroku.
4. Monitoruj kontekst – przy 50% pojemności wykonaj /compact ręcznie – czekanie do limitu pogarsza jakość odpowiedzi.
5. Commituj często i zaczynaj nową sesję na każdy feature – czysty kontekst to czystsza praca agenta.

Kilka skrótów, które warto znać od początku:

• /init – generuje startowy CLAUDE.md dla projektu
• /compact – kompresuje kontekst sesji bez utraty kluczowych informacji
• /clear – resetuje kontekst przy przełączaniu na nowe zadanie
• Esc Esc – cofa ostatnią akcję (rewind)
• Tab – przełącza extended thinking

Uprawnienia i bezpieczeństwo – zanim uruchomisz agenta bez nadzoru

Claude Code działa w trybie agentic, co oznacza: może czytać pliki, uruchamiać bash, pisać do repozytorium i komunikować się z API. Bez konfiguracji uprawnień to potężne, ale też ryzykowne środowisko.

System permissions w settings.json pozwala precyzyjnie definiować, co jest dozwolone:

{
  "permissions": {
    "allow": ["Read:*", "Bash:git:*", "Write:*:*.md"],
    "deny": ["Read:env:*", "Bash:sudo:*"]
  }
}

Dobra praktyka to polityka minimalnych uprawnień: zacznij od maksymalnych restrykcji, odblokuj tylko to, czego agent faktycznie potrzebuje. Połącz to z hookiem PreToolUse weryfikującym operacje bash. Dopiero wtedy możesz rozważyć uruchomienie agenta bez nadzoru.

Plan cenowy: który wybrać?

Claude Code dostępny jest w ramach subskrypcji Claude Pro i Claude Max. Różnica jest istotna przy intensywnym użyciu.

Jeśli używasz narzędzia intensywnie, Pro skończy się zanim skończy się dzień. Max to inwestycja, która zwraca się po kilku zaoszczędzonych godzinach. Do szybkiego testu wystarczy Pro, ale do poważnej pracy – Max.