Samouczek Claude Code: konfiguracja, refaktoryzacja i debugowanie w praktyce

Czym jest Claude Code?

Claude Code to narzędzie, które działa bezpośrednio w twoim terminalu, rozumie twoją bazę kodu i pomaga w zadaniach developerskich za pomocą komend w języku naturalnym. Integruje się z twoim środowiskiem programistycznym przy minimalnej konfiguracji, żebyś mógł skupić się na pisaniu i ulepszaniu kodu.

Oto kilka kluczowych możliwości Claude Code:

• Edycja i refaktoryzacja: Modyfikuj, optymalizuj i ulepszaj kod z pomocą sugestii AI.
• Naprawa błędów: Identyfikuj i rozwiązuj błędy, brakujące zależności oraz wąskie gardła wydajności.
• Zrozumienie kodu: Zadawaj pytania o architekturę, logikę i zależności w twoim kodzie.
• Automatyczne testy i linting: Uruchamiaj i naprawiaj padające testy, wykonuj linting i podnoś jakość kodu.
• Integracja z Git: Przeszukuj historię gita, rozwiązuj konflikty scalania, twórz commity i generuj pull requesty bez wysiłku.

Niezależnie od tego, czy pracujesz nad projektem open source, czy zarządzasz kodem na poziomie enterprise, Claude Code zapewnia inteligentną automatyzację, która dopasowuje się do twojego stylu i wymagań projektu. Ostatnie aktualizacje dodały auto mode (mniej przerw na uprawnienia), plan mode (workflow w duchu „najpierw projektuj”), oraz Routines (zaplanowani agenci w chmurze uruchamiani przez wyzwalacze bez konieczności działania twojej maszyny).

Oto przykładowi idealni użytkownicy tego narzędzia:

• Software Developerzy: poprawa jakości i łatwości utrzymania kodu.
• Kontrybutorzy open source: zrozumienie i ulepszanie nieznanych baz kodu.
• Inżynierowie DevOps: automatyzacja code review i zadań lintingu.

Claude Code domyślnie używa Claude Opus 4.7 w planach Max i Team Premium. Użytkownicy Pro startują z Sonnet 4.6, ale mogą przełączyć się na modele Opus przy bardziej wymagających zadaniach. Możesz zmienić model w trakcie sesji komendą /model albo dostosować głębokość rozumowania suwakiem /effort. Możesz też budować samodzielnych agentów AI, korzystając z Claude Agents SDK.

Anthropic wprowadził także Cowork do wsparcia w stylu agenta przy codziennych zadaniach na plikach i dokumentach, wykraczających poza kodowanie. Jest dostępny dla wszystkich płatnych planów (Pro, Max, Team, Enterprise) w aplikacji Claude Desktop.

Zaczynajmy nasz projekt praktyczny.

Krok 1: Konfiguracja Claude Code

Aby zacząć z Claude Code, potrzebujesz terminala, projektu kodu do pracy oraz subskrypcji Claude (Pro/Max/Teams/Enterprise) albo konta w Claude Console z aktywnym rozliczaniem.​

Zainstaluj Claude Code, uruchamiając jedno z poniższych poleceń w terminalu, zależnie od systemu operacyjnego i terminala.

macOS / Linux / WSL: 

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

Windows PowerShell: 

irm https://claude.ai/install.ps1 | iex

Windows CMD:  

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Uwaga: Instalacja przez npm install -g @anthropic-ai/claude-code nadal istnieje, ale jest przestarzała, dlatego preferuj natywny proces instalacji opisany powyżej. Jeśli wcześniej instalowałeś przez npm, możesz migrować poleceniem claude install.

Po instalacji przejdź do katalogu projektu i uruchom Claude, wpisując:

cd your-project-directory
claude

Przy uwierzytelnianiu zostaniesz zapytany, czy chcesz korzystać z Claude Code w oparciu o płatną subskrypcję, czy rozliczanie użycia API.

Następnie otrzymasz link do logowania prowadzący do kodu weryfikacyjnego, który musisz wpisać w terminalu z uruchomionym Claude Code. To wszystko — zostanie automatycznie utworzona dedykowana przestrzeń robocza „Claude Code” do śledzenia użycia i zarządzania kosztami.

Claude Code jest gotowy do użycia.

Krok 2: Przygotuj środowisko developerskie

Do tego demo użyję biblioteki Supabase dla Pythona supabase-py — otwartoźródłowego klienta w Pythonie do pracy z Supabase, backendem jako usługą zbudowanym na PostgreSQL. Supabase oferuje zestaw narzędzi, w tym uwierzytelnianie, subskrypcje w czasie rzeczywistym, storage i automatycznie generowane API.

Zacznijmy od sklonowania repozytorium i skonfigurowania środowiska developerskiego.

1. Otwórz terminal, przejdź do katalogu, w którym chcesz sklonować repozytorium Supabase-py (np. cd Desktop) i uruchom:

git clone https://github.com/supabase/supabase-py.git
cd  supabase-py

2. Następnie utwórz wirtualne środowisko i zainstaluj wymagane zależności, uruchamiając po kolei poniższe polecenia w terminalu

python3 -m venv env
source env/bin/activate  # On Windows, use ./env/Scripts/activate
pip install -e .

Twoje środowisko Pythona jest już skonfigurowane ze wszystkimi niezbędnymi zależnościami do uruchomienia biblioteki Supabase, a repozytorium jest gotowe do eksploracji. 

Krok 3: Zidentyfikuj obszary do kontrybucji

Świetnym sposobem na kontrybucję jest przejrzenie zakładki Issues na GitHubie. W repozytorium Supabase zidentyfikowałem problem w client.py związany z czytelnością kodu, strukturą i brakiem sensownych komentarzy.

Oto co zrobimy z Claude Code:

• Zrefaktoryzujemy kod, by poprawić czytelność, łatwość utrzymania i strukturę.
• Dodamy sensowne docstringi i komentarze w kodzie, aby wyjaśnić cel poszczególnych komponentów.
• Zidentyfikujemy i naprawimy błędy, analizując zgłoszenia i inne potencjalne problemy.

Krok 4: Eksperymenty z Claude Code

Skoro jesteśmy już w folderze supabase-py, przejdź do katalogu supabase zawierającego plik client.py i uruchom Claude Code:

cd supabase
claude

Claude Code ma teraz dostęp do wszystkich plików i folderów w folderze Supabase-py. Teraz poeksperymentujmy.

Refaktoryzacja kodu

Jako część ulepszania Supabase Python SDK zrefaktoryzujmy plik client.py, aby poprawić czytelność, łatwość utrzymania i organizację. Po prostu wpisz następującą prośbę w wierszu poleceń:

Prompt: Zrefaktoryzuj kod w pliku client.py znajdującym się w folderze Supabase.

Claude poprosi o potwierdzenie przed kontynuacją. Naciśnij Enter, aby zatwierdzić zmiany. Po zakończeniu Claude Code zaktualizuje plik, wyświetli modyfikacje w terminalu i poda podsumowanie wprowadzonych zmian.

Z użyciem Claude Code wprowadziliśmy w client.py następujące ulepszenia:

• Uporządkowane importy:  Claude Code pogrupował powiązane importy w logiczne sekcje (błędy auth, typy API, błędy funkcji), zmienił nazwy importów dla większej jasności i usunął zbędne aliasy dla spójności.
• Lepsza czytelność: Dodano komentarze sekcji klasyfikujące importy i usunięto duplikacje w liście __all__ dla czystszej organizacji.
• Uproszczone opcje klienta: Zredukowano liczbę linii, łącząc podobne importy w jedno wyrażenie.

Oto porównanie oryginalnego i zrefaktoryzowanego kodu obok siebie.

Dokumentowanie kodu

Oprócz refaktoryzacji Claude Code potrafi generować, aktualizować i standaryzować dokumentację kodu w całym projekcie. Wykrywa nieudokumentowane sekcje, tworzy ustrukturyzowane docstringi lub komentarze i sprawdza zgodność ze standardami dokumentacji projektu.

Użyliśmy Claude Code do poprawy dokumentacji w client.py, co dało:

• Jasne docstringi na poziomie modułu, wyjaśniające cel pliku.
• Szczegółowe komentarze sekcji kategoryzujące importy (typy błędów, implementacje klientów, usługi storage).
• Komentarze w linii opisujące typy błędów, funkcje klienta i ważne komponenty.

Oto porównanie zrefaktoryzowanego i udokumentowanego kodu obok siebie.

Prompt: Udokumentuj kod w client.py, dodając komentarze dla lepszego zrozumienia.

Po dodaniu dokumentacji możesz sprawdzić jej zgodność ze standardami projektu, prosząc Claude:

Prompt: Sprawdź, czy dokumentacja jest zgodna ze standardami naszego projektu.

Naprawianie błędów

Debugowanie bywa czasochłonne, ale Claude Code skraca ten cykl, analizując komunikaty błędów, identyfikując przyczyny i proponując poprawki. Niezależnie od tego, czy chodzi o brakujące importy, błędy czasu wykonania, czy problemy logiczne, zawęża obszar poszukiwań i sugeruje celowane korekty.

Oto jak używać Claude Code do debugowania:

1. Zidentyfikuj problem:  Przekaż komunikat błędu Claude.
2. Uzyskaj rekomendacje poprawek: poproś Claude o możliwe rozwiązania.
3. Zastosuj i zweryfikuj poprawkę:  wdrożona propozycja Claude i sprawdź, czy problem zniknął.

Claude Code wprowadził następujące ustalenia, aby rozwiązać problemy z importami w pliku client.py: 

• Komentarze type ignore: dodano komentarz # type: ignore, aby wyciszyć ostrzeżenia IDE i narzędzi type-checkingu dla nierozwiązanych importów.
• Spójna kategoryzacja błędów: Claude Code zadbał, by importy błędów z uwierzytelniania, bazy danych, storage i funkcji były jasno pogrupowane.
• Zachowana czytelność kodu: dodano komentarze wyjaśniające, dlaczego pewne importy zostały zignorowane, zamiast je usuwać.

Oto porównanie oryginalnego i naprawionego kodu obok siebie.

Prompt: Widzę kilka błędów, np. „Import gotrue.errors nie mógł zostać rozwiązany”. Pomóż mi naprawić wszystkie błędy w client.py.

Polecenia Claude Code

Oto kilka poleceń, które możesz wypróbować z Claude.

Po więcej szczegółów zajrzyj do naszego przewodnika Claude Code: polecenia ze slashem.

Zaawansowane funkcje Claude Code

Gdy poczujesz się pewnie z podstawami refaktoryzacji i debugowania, możesz rozszerzyć możliwości Claude Code, dostosowując jego zachowanie. Hooks i wtyczki pozwalają automatyzować powtarzalne zadania i integrować systemy zewnętrzne.

Hooki Claude Code

Hooki w Claude Code to zautomatyzowane wyzwalacze, które uruchamiają polecenia powłoki, gdy podczas sesji Claude Code wystąpią określone zdarzenia. Automatyzują powtarzalne zadania, takie jak formatowanie kodu, uruchamianie testów i kontrole bezpieczeństwa, które Claude mógłby pomijać.

Hooki korzystają z mechanizmu zdarzenie–akcja, w którym definiujesz trzy rzeczy:

• Zdarzenie: Kiedy hook jest wyzwalany?

• Dopasowanie (matcher): Które akcje są objęte?

• Polecenie: Co zostaje uruchomione po wyzwoleniu hooka?

Na przykład hook może zadziałać po zapisaniu przez Claude pliku Pythona i automatycznie uruchomić black do sformatowania kodu. Hooki otrzymują kontekst JSON o tym, co się wydarzyło, co pozwala podejmować inteligentne decyzje w zależności od typów lub ścieżek plików. Mogą wypisywać do transkryptu Claude albo wysyłać komunikaty o błędach bezpośrednio do Claude, blokując operacje.

Typowe zastosowania hooków obejmują:

• Formatowanie kodu: Automatyczne uruchamianie linterów i formaterów po zapisaniu kodu

• Testowanie: Uruchamianie zestawów testów po zmianach, aby wcześnie wyłapywać błędy

• Bezpieczeństwo: Blokowanie modyfikacji w wrażliwych plikach, jak produkcyjne konfiguracje czy klucze API

• Dokumentację: Automatyczne generowanie dokumentacji API po zmianach w plikach źródłowych

• Automatyzację Git: Tworzenie sprytnych commitów i weryfikację zasad ochrony gałęzi

• Powiadomienia: Informowanie zespołu przez Slack o zmianach w ważnych plikach

• Zgodność: Wymuszanie nagłówków licencji lub standardów kodowania przed zezwoleniem na modyfikacje

Skonfiguruj hooki za pomocą komendy /hooks w Claude Code lub edytując bezpośrednio ~/.claude/settings.json.

Wtyczki Claude Code

Wtyczki to rozszerzenia łączące Claude Code z zewnętrznymi narzędziami, usługami i API. Podczas gdy hooki automatyzują lokalne polecenia powłoki, wtyczki integrują się z szerszym ekosystemem developmentu, takim jak pipeline’y CI/CD, narzędzia do zarządzania projektami i platformy komunikacji zespołowej.

Wtyczki mogą łączyć wiele komponentów — subagentów (wyspecjalizowanych asystentów Claude do konkretnych zadań), serwery MCP (standaryzowane integracje narzędzi) i hooki — w jeden pakiet, który je orkiestruje.

Wtyczka może np. analizować zmiany w kodzie i automatycznie zakładać zgłoszenia w Jira albo łączyć się z twoją wewnętrzną infrastrukturą testową. Wtyczki reagują na te same zdarzenia co hooki, ale wysyłają dane do usług zewnętrznych i przetwarzają odpowiedzi, wpływając na workflow Claude.

Oto kilka zadań, w których wtyczki Claude Code sprawdzają się świetnie:

• Integracja z CI/CD: Wyzwalaj buildy, testy i wdrożenia po zmianach w plikach

• Zarządzanie projektami: Automatycznie twórz lub aktualizuj zgłoszenia w Jira, GitHub czy Linear

• Komunikacja zespołowa: Wysyłaj aktualizacje do Slacka lub Teams po zmianach

• Code review: Automatycznie twórz pull requesty i zarządzaj recenzjami na GitHub/GitLab

• Analiza zewnętrzna: Wywołuj SonarQube, CodeClimate czy Snyk do skanowania kodu w środowisku enterprise

• Narzędzia niestandardowe: Integruj własne systemy i workflowy firmowe

• Rozszerzenia IDE: Dodawaj własne polecenia i ułatwienia nawigacji

Instaluj wtyczki z rejestru lub buduj je wewnętrznie dla swojej organizacji, a następnie skonfiguruj, na jakie zdarzenia reagują. Razem hooki i wtyczki tworzą elastyczną platformę, która dopasowuje Claude Code do twojej istniejącej infrastruktury.

Inne zaawansowane funkcje

W 2026 r. Claude Code zyskał kilka dużych możliwości, które rozszerzają sposób i miejsce jego użycia:

• Plan mode: Workflow „najpierw projekt”, w którym Claude tworzy szczegółowy plan implementacji przed pisaniem kodu. Używam tego do wszystkich nietrywialnych zadań.
• Auto mode: Klasyfikator uprawnień, który pozwala Claude pracować z mniejszą liczbą przerw — przydatny przy dłuższych zadaniach, gdy nie chcesz zatwierdzać każdego zapisu pliku.
• Routines: Zaplanowani agenci w chmurze uruchamiani według crona, zdarzenia GitHub (np. otwarcie PR) lub wywołania webhooka. Twoja maszyna nie musi działać.
• Integracja z IDE: Oficjalne rozszerzenia dla VS Code, Cursor i IDE JetBrains z diffami inline, checkpointami i wielosesyjnością.
• Zdalne sterowanie i Channels: Uruchamiaj sesje Claude Code i wchodź z nimi w interakcję z telefonu lub innych urządzeń.

Na zakończenie

W tym samouczku użyłem Claude Code do zrefaktoryzowania, udokumentowania i zdebugowania pliku w Supabase Python SDK. Poprawiliśmy czytelność kodu, dodaliśmy ustrukturyzowaną dokumentację i rozwiązaliśmy problemy z importami.

Claude Code dynamicznie się rozwija — z funkcjami takimi jak plan mode, auto mode i Routines — więc warto poeksperymentować na własnych projektach, aby zobaczyć, jak wpisuje się w twój workflow.

Aby zrobić kolejny krok, zachęcam do lektury naszego samouczka Claude Code: najlepsze praktyki, który uczy, jak najlepiej wykorzystać okno kontekstu Claude. Jeśli chcesz zbudować projekt od zera, polecam nasz poradnik Spec-Driven Development z Claude Code.