# Claude Code: przewodnik dla początkujących

> Kompleksowy poradnik dotyczący pracy z Claude Code od Anthropic: instalacja CLI, uwierzytelnianie, zarządzanie uprawnieniami, skróty klawiszowe oraz krok po kroku tworzenie pierwszego projektu.

Claude Code to oficjalny interfejs wiersza poleceń (CLI) od firmy Anthropic, zdolny do odczytywania kodu źródłowego, wprowadzania poprawek, wykonywania komend oraz bezpośredniej interakcji z git w terminalu za pomocą zwykłej rozmowy w języku naturalnym. Nie jest to osobne okno czatu webowego, z którego kod trzeba kopiować ręcznie, lecz pełnoprawny autonomiczny agent działający bezpośrednio wewnątrz Twojego projektu.

Ten poradnik stanowi punkt wyjścia do szybkiego startu z Claude Code. Materiał podzielono na trzy logiczne bloki:
- **Moduł 1 — Instalacja i podstawowa konfiguracja:** wdrożenie CLI, uwierzytelnianie przez API lub OAuth, pierwsze uruchomienie oraz przegląd plików konfiguracyjnych.
- **Moduł 2 — Sesja robocza i interakcja:** zarządzanie kontekstem, skróty klawiszowe, polecenia slash, tryb nieinteraktywny oraz optymalizacja pamięci (`/compact`).
- **Moduł 3 — Bezpieczeństwo i model uprawnień:** konfiguracja plików `settings.json`, tworzenie list zezwoleń (allow) oraz zakazów (deny) dla komend bash.

Każdy moduł kończy się praktycznym ćwiczeniem polegającym na utworzeniu, dopracowaniu i finalnej wersji rzeczywistego komponentu webowego w Next.js.

---

## 1. Czym jest Claude Code i wymagania systemowe

### 1.1. Czym jest Claude Code i jego różnice względem czatu webowego

Claude Code integruje się z Twoim codziennym stackiem deweloperskim jako asystent terminalowy. W przeciwieństwie do tradycyjnego czatu webowego, agent dysponuje zestawem narzędzi (Tools):
- **Odczyt i wyszukiwanie:** inspekcjonuje pojedyncze pliki, szuka wystąpień za pomocą wyrażeń regularnych (`grep`) oraz orientuje się w strukturze projektu (`glob`).
- **Modyfikacja kodu:** generuje punktowe zmiany plików poprzez mechanizm patch/diff, unikając całkowitego nadpisywania dużych plików.
- **Wykonywanie komend systemowych:** uruchamia testy, kompilatory, linterzy oraz komendy git z możliwością analizy kodów zwrotu i błędów kompilacji.

### 1.2. Wymagania systemowe i przygotowanie środowiska

Przed instalacją upewnij się, że posiadasz niezbędne komponenty:
- **System operacyjny:** macOS, nowoczesna dystrybucja Linuxa lub Windows poprzez podsystem WSL2.
- **Środowisko wykonawcze:** Node.js w wersji 18.0 lub nowszej (sprawdź przez `node -v`).
- **System kontroli wersji:** Git w wersji 2.20+ (sprawdź przez `git --version`).
- **Dostęp do modeli Anthropic:** aktywny klucz API z konsoli Anthropic Console lub konto z planem Claude Max.

---

## 2. Instalacja i uwierzytelnianie

### 2.1. Instalacja CLI przez npm i menedżer pakietów

Claude Code jest dystrybuowany jako globalny pakiet w rejestrze npm. Wykonaj komendę instalacyjną w terminalu:

```bash
npm install -g @anthropic-ai/claude-code
```

Sprawdź poprawność instalacji pliku binarnego:

```bash
claude --version
```

Jeśli terminal zwraca błąd `command not found`, oznacza to brak ścieżki globalnych pakietów npm w zmiennej środowiskowej `PATH`. Szczegółowe rozwiązanie znajduje się w sekcji diagnostyki poniżej.

### 2.2. Uwierzytelnianie i powiązanie konta Anthropic

Obsługiwane są dwie metody autoryzacji:

**Wariant 1 — Klucz Anthropic API:**  
Określ token poprzez zmienną środowiskową:

```bash
export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-api"
```

Aby klucz był zachowywany między restartami terminala, dodaj komendę do pliku konfiguracyjnego swojej powłoki:

```bash
echo 'export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-api"' >> ~/.zshrc
source ~/.zshrc
```

**Wariant 2 — Subskrypcja Claude Max (OAuth):**  
Jeśli korzystasz z subskrypcji Claude Max ($100 lub $200/mies.), zaloguj się bez użycia osobnego klucza API:

```bash
claude login
```

Komenda otworzy sesję w domyślnej przeglądarce w celu potwierdzenia dostępu.

---

## 3. Pierwsze uruchomienie i podstawowa konfiguracja

### 3.1. Pierwsze uruchomienie w projekcie i weryfikacja środowiska

Przejdź do katalogu dowolnego swojego projektu kodowego i zainicjuj Claude Code:

```bash
cd ~/my-project
claude
```

Po uruchomieniu trafisz do interaktywnego środowiska komend. Spróbuj wysłać podstawowe zapytanie testowe:

```text
Summarize the structure of this project and list the main technologies used.
```

Claude automatycznie przejrzy pliki `package.json`, konfiguracje buildu oraz strukturę katalogów, a następnie sformułuje krótki raport wprowadzający.

### 3.2. Podstawowa konfiguracja i rozwiązywanie problemów (Troubleshooting)

Pliki konfiguracyjne znajdują się w katalogu `~/.claude/`:
- `~/.claude/settings.json` — globalne zezwolenia i ograniczenia dostępu do narzędzi.
- `~/.claude/CLAUDE.md` — osobiste instrukcje systemowe użytkownika.
- `.claude/settings.json` — ustawienia projektowe (zatwierdzane w systemie kontroli wersji).
- `CLAUDE.md` — instrukcje poziomu repozytorium (architektura, zasady lintingu).

| Problem przy uruchomieniu | Przyczyna pierwotna | Rozwiązanie inżynierskie |
| :--- | :--- | :--- |
| `claude: command not found` | Katalog npm bin nie został dodany do `PATH` | Dodaj ścieżkę do powłoki: `export PATH="$(npm config get prefix)/bin:$PATH"` |
| Błąd autoryzacji `401 Unauthorized` | Nieważny lub wygasły klucz API | Wykonaj `claude logout`, sprawdź wartość `ANTHROPIC_API_KEY` i powtórz `claude login` |
| Wolna inicjalizacja sesji | Indeksowanie dużego repozytorium | Pierwsze uruchomienie wymaga analizy drzewa plików; kolejne iteracje wykorzystują cache |

---

## 4. Praktyka: tworzenie pierwszej aplikacji

### 4.1. Krok po kroku: wdrożenie prototypu

Celem pierwszego ćwiczenia jest praktyczne stworzenie minimalnego komponentu klienta Next.js / React przy użyciu Claude Code:
1. Poproś Claude o utworzenie nowego pliku strony `app/practice/page.tsx`.
2. Zleć opis prostego stanu ładowania oraz przycisku wywołującego endpoint testowy.
3. Sprawdź działanie interfejsu pod adresem `http://localhost:3000/practice`.

### 4.2. Szablon startowy komponentu i lokalna weryfikacja

Bazowy kod prototypu:

```tsx
// app/practice/page.tsx
'use client';

import { useState } from 'react';

export default function PracticePage() {
  const [result, setResult] = useState('');
  const [loading, setLoading] = useState(false);

  async function runTest() {
    setLoading(true);
    try {
      const response = await fetch('/api/test');
      const data = await response.json();
      setResult(data.message || 'Запит виконано успішно');
    } catch {
      setResult('Помилка виконання тестового запиту');
    } finally {
      setLoading(false);
    }
  }

  return (
    <div className="p-8 max-w-2xl mx-auto font-sans">
      <h1 className="text-3xl font-bold mb-6">Практична вправа 1: Прототип</h1>
      <button
        onClick={runTest}
        disabled={loading}
        className="bg-black text-white px-6 py-3 rounded-lg hover:bg-neutral-800 disabled:opacity-50 transition"
      >
        {loading ? 'Виконується...' : 'Запустити тест'}
      </button>
      {result && (
        <div className="mt-6 p-4 bg-neutral-100 rounded-lg border border-neutral-200">
          {result}
        </div>
      )}
    </div>
  );
}
```

---

## 5. Sesja robocza i cykl dialogu

### 5.1. Uruchomienie interaktywnej sesji REPL

Do codziennej pracy przejdź do katalogu roboczego i aktywuj interaktywny cykl read-eval-print-loop (REPL):

```bash
cd ~/my-project
claude
```

Claude zachowuje kontekst rozmowy w trakcie trwania sesji, pamiętając zmienione pliki oraz wykryte błędy. Komunikacja odbywa się zwykłym językiem bez sformalizowanej składni.

### 5.2. Cykl dialogu: planowanie, narzędzia i wykonanie

Praca agenta podporządkowana jest pięcioetapowemu cyklowi:

```mermaid
flowchart TD
    A["Користувач ставить завдання природною мовою"] --> B["Claude аналізує кодову базу та формує план"]
    B --> C["Агент запитує дозвіл на модифікацію файлів/команд"]
    C --> D["Виконання затверджених дій та валідація дифу"]
    D --> E["Користувач перевіряє результат та надає фідбек"]
```

Typowy fragment interakcji:
- **Zapytanie:** `Dodaj wskaźnik ładowania na stronę dashboardu.`
- **Analiza:** Claude odczytuje `app/dashboard/page.tsx`, wykrywając brak obsługi oczekiwania na dane.
- **Propozycja:** Utworzenie komponentu `loading.tsx` oraz objęcie bloku granicami `Suspense`.
- **Podsumowanie:** Agent prezentuje punktowy diff i czeka na Twoje zatwierdzenie.

---

## 6. Skróty klawiszowe, komendy i tryby pracy

### 6.1. Skróty klawiszowe i polecenia slash do zarządzania kontekstem

Efektywna nawigacja w terminalu opiera się na skrótach systemowych:

| Kombinacja | Przeznaczenie |
| :--- | :--- |
| `Enter` | Wysyłka bieżącej wiadomości do agenta |
| `Escape` | Natychmiastowe anulowanie aktywnej generacji lub wykonania narzędzia |
| `Ctrl+C` | Poprawne zakończenie pracy sesji Claude Code |
| `Up` / `Down` | Przegląd historii poprzednich zapytań |
| `Shift+Tab` | Przełączanie między jednowierszowym a wielowierszowym wprowadzaniem |

Specjalne wbudowane polecenia slash do kontroli środowiska:
- `/help` — lista dostępnych dyrektyw.
- `/clear` — resetowanie bieżącej historii wiadomości.
- `/compact` — kompresja okna kontekstowego w celu oszczędności tokenów bez utraty istoty.
- `/model` — operatywna zmiana bieżącego modelu (np. przełączanie między Sonnet a Opus).
- `/permissions` — sprawdzenie aktywnych zezwoleń na wywołanie narzędzi systemowych.

### 6.2. Tryb nieinteraktywny i wskazówki dla efektywnej pracy

Do używania Claude Code w skryptach automatyzacji lub jednorazowych operacjach stosuj flagę `-p` (`print`):

```bash
# Отримання швидкої довідки про проєкт
claude -p "Яку базу даних використовує цей проєкт?"

# Передача логів для аналізу через пайплайн
cat error.log | claude -p "Знайди першопричину збою та запропонуй рішення"
```

> 💡 **Rekomendacje dla stabilnej pracy:**
> - Formułuj wymagania konkretnie: zamiast „napraw formularz” pisz „dodaj debounce do handlera kliknięcia przycisku wysyłania formularza”.
> - Regularnie uruchamiaj `/compact`, gdy długość dialogu przekracza 30–40 kroków.

---

## 7. Praktyka: dopracowanie aplikacji

### 7.1. Refaktoryzacja i ulepszenie bazy kodowej przez Claude

W drugiej części praktycznej rozszerzymy stworzony prototyp, zlecając Claude ulepszenie obsługi stanów brzegowych oraz typowania.

Wyślij agentowi taką instrukcję:
```text
Otwórz plik app/practice/page.tsx. Dodaj poprawne, ścisłe typowanie TypeScript, blok przechwytywania błędów try/catch z wyświetlaniem tekstu błędu na czerwonym tle oraz dodaj animowany spinner CSS podczas ładowania.
```

### 7.2. Rozszerzenie funkcjonalności: stylizacja, obsługa błędów i animacja

Zaktualizowany kod strony:

```tsx
// app/practice/page.tsx - Доопрацьована версія
'use client';

import { useState } from 'react';

export default function PracticePage() {
  const [result, setResult] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);

  async function runTest() {
    setLoading(true);
    setError(null);
    try {
      const response = await fetch('/api/test');
      if (!response.ok) throw new Error(`Помилка сервера: код ${response.status}`);
      const data = await response.json();
      setResult(data.message || 'Операцію успішно завершено');
    } catch (err: unknown) {
      setError(err instanceof Error ? err.message : 'Сталася непередбачена помилка');
    } finally {
      setLoading(false);
    }
  }

  return (
    <div className="p-8 max-w-2xl mx-auto font-sans">
      <h1 className="text-3xl font-bold mb-4">Практична вправа 2: Доопрацювання</h1>
      <p className="text-neutral-600 mb-6">Тестування обробки винятків та динамічних станів.</p>
      
      <button
        onClick={runTest}
        disabled={loading}
        className="flex items-center gap-2 bg-black text-white px-6 py-3 rounded-lg hover:bg-neutral-800 disabled:opacity-50 transition"
      >
        {loading && (
          <span className="w-4 h-4 border-2 border-white border-t-transparent rounded-full animate-spin" />
        )}
        {loading ? 'Обробка запиту...' : 'Виконати дію'}
      </button>

      {error && (
        <div className="mt-6 p-4 bg-red-50 text-red-700 rounded-lg border border-red-200">
          {error}
        </div>
      )}

      {result && (
        <div className="mt-6 p-4 bg-neutral-100 text-neutral-800 rounded-lg border border-neutral-200">
          {result}
        </div>
      )}
    </div>
  );
}
```

---

## 8. Model uprawnień i bezpieczeństwo

### 8.1. Architektura modelu uprawnień i poziomy ryzyka narzędzi

System bezpieczeństwa Claude Code dzieli wszystkie dostępne operacje na dwie fundamentalne kategorie według poziomu potencjalnego ryzyka:

| Poziom dostępu | Dostępne operacje | Mechanizm wykonania |
| :--- | :--- | :--- |
| **Bezpieczne (Read-only)** | `Read`, `Grep`, `Glob`, listowanie katalogów | Wykonywane automatycznie bez pytań do użytkownika |
| **Potencjalnie niebezpieczne** | `Edit`, `Write`, `Bash`, usuwanie plików, `git push` | Wymagają jawnego potwierdzenia przed wykonaniem |

### 8.2. Mechanika zatwierdzania i odrzucania potencjalnie niebezpiecznych działań

Przed wykonaniem ryzykownej akcji Claude zatrzymuje wykonanie i wyświetla zapytanie:

```text
Claude wants to run: npm install express
Allow? (y/n/always)
```

Dostępne opcje wyboru:
- `y` (`yes`) — zatwierdzenie konkretnego jednorazowego wywołania.
- `n` (`no`) — odrzucenie działania z podaniem powodu odmowy.
- `always` (lub `a`) — udzielenie zezwolenia na wywołanie tego narzędzia do końca bieżącej sesji roboczej.

---

## 9. Pliki ustawień i zarządzanie uprawnieniami

### 9.1. Globalne i projektowe pliki ustawień (settings.json)

Aby utrwalić stałe reguły, utwórz lub edytuj globalny plik `~/.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Write",
      "Bash(npm run *)",
      "Bash(git status)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}
```

### 9.2. Wzorce dla komend bash i weryfikacja przez /permissions

Sekcja `permissions.allow` wspiera elastyczne maski wyszukiwania (glob patterns):
- `Bash(npm test *)` — pozwala na uruchamianie pakietów testowych bez potwierdzeń.
- `Bash(git commit *)` — pozwala na zatwierdzanie zmian.
- `Bash(rm -rf *)` na liście `deny` — gwarantuje absolutne zablokowanie masowego usuwania danych.

Aby przejrzeć obowiązujące reguły w dowolnym momencie sesji, wykonaj komendę `/permissions`.

---

## 10. Najlepsze praktyki bezpieczeństwa i pracy

### 10.1. Strategia kontroli dostępu: zasada najmniejszych przywilejów

- **Stopniowe rozszerzanie praw:** Zacznij pracę z pełną ręczną moderacją. Dodawaj komendy do listy `allow` dopiero po upewnieniu się co do stabilności zachowań agenta.
- **Zakaz wildcard dla bash:** Nigdy nie wpisuj `"Bash(*)"` w dozwolonych narzędziach — całkowicie niweluje to ochronną piaskownicę.
- **Aktywne wykorzystanie deny:** Jawno blokuj destrukcyjne narzędzia (`sudo`, `mkfs`, `dd`), aby uniemożliwić przypadkowe uszkodzenie systemu.

### 10.2. Ochrona sekretów środowiskowych i dokładny audyt diffów

- **Izolacja tokenów:** Claude Code ma dostęp do zmiennych środowiskowych bieżącej powłoki. Nie przechowuj w sesji roboczej krytycznych kluczy do produkcyjnych baz danych.
- **Przegląd diffu przed zatwierdzeniem:** Zawsze analizuj zaproponowany diff edycji pliku, aby w porę zauważyć przypadkowe usunięcie sąsiednich modułów.

---

## 11. Praktyka: finalna wersja aplikacji

### 11.1. Bezpieczna finalna wersja aplikacji