# Przewodnik po Claude Code: konfiguracja do programowania agentowego (dla początkujących)

> Kompletny praktyczny przewodnik po konfiguracji Claude Code: instalacja CLI, konfiguracja plików CLAUDE.md i settings.json, reguły uprawnień, automatyczne hooki, niestandardowa komenda /truth oraz subagenci.

## 1. Instalacja Claude Code i przygotowanie środowiska

Claude Code instaluje się jako autonomiczny interfejs wiersza poleceń (CLI) służący do interakcji z kodem za pośrednictwem modeli agentowych Anthropic. W przeciwieństwie do zwykłych chatbotów, Claude Code bezpośrednio oddziałuje z systemem plików, uruchamia komendy terminalowe, analizuje strukturę projektu i wprowadza atomowe poprawki.

### 1.1. Metody instalacji CLI: natywny skrypt vs npm

Zalecana przez deweloperów metoda instalacji to natywny skrypt systemowy, który automatycznie konfiguruje plik binarny oraz środowisko wykonawcze. Jako alternatywę dla stacji roboczych z gotowym toolchainem Node.js można wykorzystać globalny pakiet npm:

```bash
# macOS, Linux або WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Альтернативне встановлення через npm
npm install -g @anthropic-ai/claude-code
```

Po zakończeniu instalacji zweryfikuj działanie polecenia, wykonując `claude --version` w swoim terminalu.

### 1.2. Powiązanie z katalogiem projektu i uwierzytelnianie

Przed pierwszym uruchomieniem kluczowe jest przejście bezpośrednio do głównego folderu Twojego roboczego projektu:

```bash
cd your-project-directory
claude
```

> 💡 **Dlaczego to ważne:** Claude Code sztywno wiąże pamięć długoterminową, lokalne reguły i uprawnienia z bieżącym katalogiem roboczym. Uruchomienie z folderu domowego (`~`) lub pulpitu spowoduje utratę kontekstu architektonicznego Twojego repozytorium.

Podczas pierwszego uruchomienia narzędzie zaproponuje przejście procesu uwierzytelniania:
- **Logowanie OAuth przez przeglądarkę** przy posiadaniu aktywnej subskrypcji Claude (Pro, Max lub Team).
- **Klucz API Anthropic Console** do bezpośredniego rozliczania tokenów co sekundę zgodnie z taryfami API.

Oprócz czystego terminala, Claude Code obsługuje pracę poprzez oficjalne rozszerzenie dla VS Code, plugin dla JetBrains, aplikację desktopową oraz interfejs webowy na claude.ai. Wszystkie te interfejsy korzystają ze wspólnej struktury plików konfiguracyjnych `.claude/`, dlatego wszystkie reguły pozostają niezmienne niezależnie od wybranego środowiska pracy.

## 2. Trzy pliki konfiguracyjne: architektura pamięci i ustawień

Claude Code wykorzystuje dwupoziomową hierarchię konfiguracji: katalog projektu `.claude/` (wraz z plikiem `CLAUDE.md` w katalogu głównym) oraz globalny katalog `~/.claude/` w folderze domowym użytkownika. Ustawienia globalne stosują się do wszystkich sesji na maszynie, natomiast lokalne mają priorytet dla bieżącego repozytorium.

### 2.1. CLAUDE.md i reguły pamięci repozytorium

`CLAUDE.md` to stała pamięć projektu, którą agent czyta na początku każdej sesji roboczej. Tutaj zapisywane są punkty orientacyjne architektury, komendy uruchamiania testów, zasady stylu kodu oraz stack technologiczny.

| Mechanizm | Lokalizacja | Przeznaczenie |
| --- | --- | --- |
| **Główny przewodnik** | `CLAUDE.md` | Główne instrukcje i opis stacku (zalecane do 2500 tokenów). |
| **Reguły modułowe** | `.claude/rules/*.md` | Specyficzne instrukcje powiązane z konkretnymi ścieżkami i plikami. |
| **Generator pamięci** | Komenda `/init` | Automatyczna analiza bazy kodu i tworzenie pliku startowego. |
| **Edytor pamięci** | Komenda `/memory` | Szybka, interaktywna edycja utrwalonych reguł. |

> ⚠️ **Główna zasada pamięci:** Instrukcje podane bezpośrednio w czacie nieuchronnie gubią się podczas kompresji kontekstu w długich sesjach. Każda reguła, która ma przetrwać między sesjami, musi być jawnie zapisana w `CLAUDE.md`.

### 2.2. settings.json i mechanizm automatycznej pamięci (Auto memory)

Plik konfiguracyjny `settings.json` (znajdujący się w `.claude/settings.json` dla projektu lub w `~/.claude/settings.json` dla poziomu globalnego) definiuje uprawnienia bezpieczeństwa, hooki systemowe, zmienne środowiskowe oraz domyślny model.

Mechanizm **Auto memory** pozwala Claude Code automatycznie zapisywać obserwacje robocze między sesjami bez bezpośredniej ingerencji dewelopera. Tę zachowanie można kontrolować parametrem `"autoMemoryEnabled": false` lub zmienną środowiskową `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`, jeśli preferujesz wyłącznie przejrzystą, ręczną kontrolę poprzez `CLAUDE.md`.

## 3. Konfiguracja uprawnień i hooków z wyprzedzeniem

Aby zapewnić bezpieczeństwo i wyeliminować zbędne prośby o potwierdzenie, Claude Code oferuje system interaktywnych trybów oraz granularnych reguł w konfiguracji.

### 3.1. Interaktywne tryby uprawnień i macierz allow/ask/deny

Szybkie przełączanie trybów wykonania odbywa się kombinacją klawiszy `Shift+Tab`:
- **Default** – pyta o potwierdzenie użytkownika przed każdą potencjalnie niebezpieczną operacją lub zmianą pliku.
- **Auto-Accept Edits** – automatycznie stosuje poprawki plików, pytając o potwierdzenie tylko dla komend systemowych.
- **Plan Mode** – tryb tylko do odczytu, bez możliwości zmiany kodu lub wykonywania komend bash do czasu zatwierdzenia ogólnego planu.

W celu eliminacji rutynowych potwierdzeń w `.claude/settings.json` konfiguruje się deklaratywną macierz reguł:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  }
}
```

Reguła `deny` zawsze ma najwyższy priorytet: nawet jeśli maska `Read(**)` zezwala na odczyt plików, jawny zakaz `Read(.env)` gwarantuje, że poufne zmienne środowiskowe nigdy nie trafią do kontekstu modelu.

### 3.2. Automatyzacja poprzez hooki PostToolUse i PreToolUse

Hooki pozwalają na uruchamianie lokalnych skryptów przed lub po wywołaniu wbudowanych narzędzi agenta.

Na przykład hook **PostToolUse** automatycznie formatuje edytowane pliki za pomocą Prettier:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Natomiast hook **PreToolUse** umożliwia programowe przechwytywanie i blokowanie niebezpiecznych komend bash na poziomie skryptu Python przed ich faktycznym przekazaniem do powłoki:

```python
#!/usr/bin/env python3
# .claude/hooks/block-dangerous-bash.py
import json
import re
import sys

DANGEROUS_PATTERNS = [
    r'\brm\s+.*-[a-z]*r[a-z]*f',
    r'sudo\s+rm',
    r'chmod\s+777',
    r'git\s+push\s+--force.*main',
]

input_data = json.load(sys.stdin)
if input_data.get('tool_name') == 'Bash':
    command = input_data.get('tool_input', {}).get('command', '')
    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command, re.IGNORECASE):
            print("BLOCKED: command matches dangerous security pattern", file=sys.stderr)
            sys.exit(2)
sys.exit(0)
```

Kod wyjścia `2` sygnalizuje Claude Code awaryjne zablokowanie wywołania bez wykonania komendy w systemie.

## 4. Komendy, które warto poznać w pierwszej kolejności

Wbudowana biblioteka Claude Code zawiera ponad sześćdziesiąt komend slash, jednak do codziennej produktywnej pracy wystarczy bazowe jądro.

### 4.1. Zestawienie tabelaryczne podstawowych i zaawansowanych komend slash

Poniżej znajduje się ustrukturyzowany przewodnik najważniejszych komend CLI:

| Komenda | Kategoria | Przeznaczenie i zachowanie |
| --- | --- | --- |
| `/init` | Konfiguracja | Skanuje projekt i tworzy pierwotny `CLAUDE.md`. |
| `/memory` | Konfiguracja | Otwiera plik pamięci projektu do bezpośredniej edycji. |
| `/clear` | Kontekst | Resetuje bieżącą rozmowę, zachowując pamięć projektu. |
| `/compact [focus]` | Kontekst | Kompresuje historię sesji, pozostawiając wskazane kluczowe aspekty. |
| `/context` | Kontekst | Pokazuje szczegółowy stan wypełnienia okna kontekstowego. |
| `/plan` | Planowanie | Przełącza CLI w tryb tylko do odczytu i projektowania kroków. |
| `/diff` | Weryfikacja | Wyświetla interaktywny podgląd wszystkich zmian w bieżącej sesji. |
| `/code-review [--fix]` | Weryfikacja | Analizuje niezakomitowane zmiany pod kątem błędów logicznych. |
| `/security-review` | Weryfikacja | Specjalistyczny audyt kodu pod kątem podatności. |
| `/resume [session]` | Nawigacja | Wznawia poprzednią sesję na podstawie jej identyfikatora lub nazwy. |
| `/branch [name]` | Nawigacja | Tworzy osobną gałąź rozmowy bez restartu sesji. |
| `/rewind` | Nawigacja | Cofa stan plików lub dialogu do wcześniejszego checkpointu. |
| `/model` | Produktywność | Przełącza model roboczy (Sonnet, Haiku, Opus) w trakcie rozmowy. |
| `/effort` | Produktywność | Reguluje głębokość łańcucha rozumowania modelu (od low do max). |
| `/cost` | Produktywność | Wyświetla statystyki zużycia tokenów i bilans sesji. |
| `/agents` | Delegowanie | Zarządza wyspecjalizowanymi subagentami i zadaniami w tle. |
| `/permissions` | Konfiguracja | Interaktywne menu przeglądania i zmiany listy uprawnień. |
| `/hooks` | Konfiguracja | Panel diagnostyki zarejestrowanych hooków systemowych. |
| `/doctor` | Diagnostyka | Kompleksowa sprawdzenie środowiska, sieci i kluczy systemowych. |

![Przegląd i nawigacja wbudowanych komend slash w Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-01.webp)

### 4.2. Triada codziennej produktywności: /compact, /plan oraz /diff

Dla szybkiego opanowania zaleca się utrwalenie trzech obowiązkowych narzędzi:
1. **`/plan`** – zawsze uruchamiaj na początku złożonego zadania. Eliminuje to chaotyczne, niekontrolowane edycje kodu bez jasnego zrozumienia konsekwencji.
2. **`/compact`** – używaj co 20–30 minut aktywnego dialogu lub po zakończeniu podzadania, aby zapobiec spadkowi szybkości i utracie uwagi modelu.
3. **`/diff`** – otwieraj przed każdym commitem dla krokowej, wizualnej weryfikacji wygenerowanego kodu.

## 5. Tworzenie własnej komendy /truth

Komenda `/truth` nie wchodzi w skład standardowego zestawu Claude Code, jednak rozwiązuje fundamentalny problem programowania agentowego – skłonność modelu do raportowania sukcesu bez faktycznej weryfikacji wyników w systemie plików.

### 5.1. Koncepcja weryfikacji faktów względem bazy kodu

Gdy agent twierdzi: *«Zaktualizowałem typ w pliku X i sprawdziłem importy w pliku Y»*, często opiera się na własnych pośrednich intencjach zawartych w kontekście. Koncepcja komendy `/truth` polega na wymuszeniu ponownego załadowania rzeczywistych plików z dysku i porównaniu każdego stwierdzenia z `git diff`.

![Interaktywne zarządzanie kontekstem, sesjami i komendami Claude Code](/api/guides-media/automation/claude-code-agentic-programming-setup-guide/images/claude-code-agentic-programming-setup-guide-extra-02.webp)

### 5.2. Implementacja skillu .claude/skills/truth/SKILL.md

Niestandardowe komendy formułuje się jako umiejętności (skills). Utwórz plik `.claude/skills/truth/SKILL.md` w swoim projekcie:

```markdown
---
description: "Verify Claude's most recent claims and edits against the actual codebase"
allowed-tools: ["Read", "Grep", "Glob", "Bash(git diff:*)"]
---

Re-examine everything you just told me in this conversation against what actually exists in the codebase right now. Specifically:

1. For every file you claim to have edited, read it again and confirm the change is actually present and matches what you described.
2. For every claim about existing code (a function's behavior, a config value, an import, a dependency version), verify it against the real file rather than your memory of reading it earlier in the session.
3. Run `git diff` and compare the actual diff against what you described changing.
4. Report back plainly: which claims checked out, which didn't, and exactly what the discrepancy was for anything that failed. Do not soften or hedge a discrepancy you find, state it directly.
```

Dzięki izolacji w `allowed-tools` komenda fizycznie nie ma prawa modyfikować plików – działa wyłącznie jako niezależny audytor.

## 6. Subagenci i praca równoległa

Podczas pracy nad dużymi projektami pojawia się problem przeciążenia kontekstu: czytanie dziesiątek plików i uruchamianie ciężkich testów szybko wypełniają dostępne okno kontekstowe.

### 6.1. Izolacja kontekstu i wyspecjalizowani subagenci (/agents)

Subagent to osobny egzemplarz Claude Code z własnym, izolowanym kontekstem, zestawem narzędzi i wąskim promptem systemowym. Rozwiązuje postawione podzadanie autonomicznie i zwraca do głównej sesji jedynie zwięzłe podsumowanie.

```bash
# Відкрити інтерактивне меню субагентів усередині сесії
/agents
```

Możesz również deklaratywnie opisać stałego subagenta w pliku `.claude/agents/code-reviewer.md`:
- Przyznać mu dostęp tylko do odczytu (`Read`, `Grep`, `Glob`).
- Przypisać szybki i oszczędny model.
- Zabronić samodzielnego wprowadzania zmian w kodzie, przekształcając go w niezawodnego recenzenta.

### 6.2. Skalowanie zadań poprzez worktree i wykonanie wsadowe (/batch)

Do równoległego wykonywania kilku niespokrewnionych ze sobą zadań Claude Code obsługuje tryb Git Worktree oraz komendę `/batch`:
- **Równoległe drzewa (`--worktree`):** kilka agentów pracuje w osobnych, izolowanych kopiach roboczych repozytorium bez konfliktów blokad plików.
- **Tryb wsadowy (`/batch`):** wykonanie jednorodnych zadań refaktoryzacji lub generowania dokumentacji w wątku w tle.

## 7. Gotowy szablon CLAUDE.md i settings.json

Oto sprawdzone w praktyce pliki konfiguracyjne, które warto zakomitować do repozytorium Twojego projektu, aby stworzyć stabilne środowisko produkcyjne.

### 7.1. Bazowy szablon pamięci CLAUDE.md

Zapisz następującą zawartość w pliku `CLAUDE.md` w katalogu głównym Twojego repozytorium:

```markdown
# Project Context

### Stack
- Language/Framework: [Node.js, TypeScript, Next.js / Python, FastAPI]
- Styling: [Tailwind CSS]
- Database: [PostgreSQL / SQLite via Drizzle ORM]

### Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

### Conventions
- Strict TypeScript typing without `any`
- Functional React components with named exports
- Keep business logic in services or hooks, not inside UI components

### Before finishing any task
- Run test suite and confirm 100% pass rate
- Run `/truth` if the task involved modifying multiple files
```

### 7.2. Produkcyjna konfiguracja .claude/settings.json z hookami

Zapisz konfigurację w `.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Read(**)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(sudo:*)",
      "Read(.env)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block-dangerous-bash.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ]
  }
}
```

Dla ustawień lokalnych, specyficznych dla Twojej maszyny, użyj pliku `.claude/settings.local.json`, dodając go do `.gitignore`.

## 8. Podsumowanie i checklista gotowości

Jakościowe środowisko do programowania agentowego różni się od chaotycznego czatu wcześniejszym skonfigurowaniem mechanizmów ochronnych, reguł pamięci oraz jasnych protokołów weryfikacji.

### 8.1. Kluczowe zasady programowania agentowego

1. **Kontekst musi być czysty:** regularnie używaj `/compact` i deleguj długotrwałe zadania do subagentów.
2. **Pamięć musi być zapisana:** jeśli reguła jest ważna – utrwal ją w `CLAUDE.md`, a nie powtarzaj w wiadomościach.
3. **Działania muszą być weryfikowane:** uruchamiaj `/truth` oraz `/diff` przed zatwierdzeniem zmian w systemie kontroli wersji.

### 8.2. Checklista początkowej konfiguracji przestrzeni roboczej

| Etap | Działanie | Status gotowości |
| --- | --- | --- |
| **Instalacja** | Zainstalowano natywne CLI Claude Code i przeprowadzono uwierzytelnianie | `Obowiązkowe` |
| **Pamięć projektu** | Utworzono `CLAUDE.md` z opisem stacku, komend i konwencji | `Obowiązkowe` |
| **Uprawnienia** | Sformułowano listy `allow`, `ask` oraz `deny` w `settings.json` | `Obowiązkowe` |
| **Hook formatowania** | Skonfigurowano `PostToolUse` dla automatycznego wywoływania Prettier | `Zalecane` |
| **Skrypt bezpieczeństwa** | Podłączono `block-dangerous-bash.py` poprzez `PreToolUse` | `Zalecane` |
| **Niestandardowy skill** | Utworzono komendę weryfikacyjną `.claude/skills/truth/SKILL.md` | `Zalecane` |