Skip to main content
Wszystkie poradniki
Spis treści poradnika

Spis treści poradnika

Czas czytania: 20 min
#automation#claude_code#cli#terminal#ai_tools
Początkujący20 min

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.

Opublikowano:
DLA AGENTA AIChatGPTClaude

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 uruchomieniuPrzyczyna pierwotnaRozwiązanie inżynierskie
claude: command not foundKatalog npm bin nie został dodany do PATHDodaj ścieżkę do powłoki: export PATH="$(npm config get prefix)/bin:$PATH"
Błąd autoryzacji 401 UnauthorizedNieważny lub wygasły klucz APIWykonaj claude logout, sprawdź wartość ANTHROPIC_API_KEY i powtórz claude login
Wolna inicjalizacja sesjiIndeksowanie dużego repozytoriumPierwsze 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:

KombinacjaPrzeznaczenie
EnterWysyłka bieżącej wiadomości do agenta
EscapeNatychmiastowe anulowanie aktywnej generacji lub wykonania narzędzia
Ctrl+CPoprawne zakończenie pracy sesji Claude Code
Up / DownPrzegląd historii poprzednich zapytań
Shift+TabPrzełą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ępuDostępne operacjeMechanizm wykonania
Bezpieczne (Read-only)Read, Grep, Glob, listowanie katalogówWykonywane automatycznie bez pytań do użytkownika
Potencjalnie niebezpieczneEdit, Write, Bash, usuwanie plików, git pushWymagają 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

Ten poradnik jest całkowicie darmowy. Jeśli oszczędził Ci wieczór, możesz wesprzeć rozwój projektu.
Wesprzyj autora