Samouczek Claude Code: konfiguracja, refaktoryzacja i debugowanie w praktyce

Czym jest Claude Code?

Claude Code to narzędzie działające bezpośrednio w twoim terminalu, które rozumie twoją bazę kodu i pomaga w zadaniach developerskich za pomocą poleceń w języku naturalnym. Integruje się ze środowiskiem programistycznym przy minimalnej konfiguracji, dzięki czemu możesz skupić się na pisaniu i ulepszaniu kodu.

Oto kilka kluczowych możliwości Claude Code:

• Edycja i refaktoryzacja: Modyfikuj, optymalizuj i ulepszaj bazę kodu dzięki sugestiom opartym na AI.
• Naprawa błędów: Identyfikuj i usuwaj błędy, brakujące zależności i wąskie gardła wydajnościowe.
• Zrozumienie kodu: Zadawaj pytania o architekturę, logikę i zależności twojego kodu.
• Automatyczne testy i linting: Uruchamiaj i naprawiaj padające testy, wywołuj narzędzia lintujące i podnoś jakość kodu.
• Integracja z Git: Przeszukuj historię gita, rozwiązuj konflikty scalania, twórz commity i generuj pull requesty bez wysiłku.

Nieważne, czy pracujesz nad projektem open source, czy zarządzasz korporacyjną bazą kodu — Claude Code wspiera cię inteligentną automatyzacją dopasowaną do twojego stylu i wymagań projektu. Najnowsze aktualizacje dodały auto mode (mniej przerywania prośbami o zgodę), plan mode (workflow „najpierw projektuj”), oraz Routines (harmonogramowane agenty w chmurze uruchamiane wyzwalaczami, bez potrzeby działania twojej maszyny).

Oto przykładowi idealni użytkownicy:

• Programiści: poprawa jakości i utrzymywalności kodu.
• Współtwórcy open source: zrozumienie i ulepszanie nieznanych baz kodu.
• Inżynierowie DevOps: automatyzacja przeglądu kodu i zadań lintingu.

Claude Code domyślnie korzysta z Claude Opus 4.7 w planach Max i Team Premium. Użytkownicy Pro startują z Sonnet 4.6, ale mogą przełączać się na Opus do wymagających zadań. Modele da się zmienić w trakcie sesji komendą /model lub wyregulować głębokość rozumowania suwakiem /effort. Możesz też budować samodzielne agentowe aplikacje AI, korzystając z Claude Agents SDK.

Anthropic wprowadził także Cowork do agentowej pomocy przy codziennych zadaniach na plikach i dokumentach spoza kodowania. Jest dostępny dla wszystkich płatnych planów (Pro, Max, Team, Enterprise) w aplikacji Claude Desktop.

Zacznijmy od części praktycznej.

Krok 1: Konfiguracja Claude Code

Aby zacząć, potrzebujesz terminala, projektu z kodem oraz subskrypcji Claude (Pro/Max/Teams/Enterprise) albo konta Claude Console z aktywnym rozliczaniem.

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

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, więc preferuj natywny proces instalacji opisany powyżej. Jeśli wcześniej instalowałeś przez npm, możesz zmigrować 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 używać Claude Code na podstawie płatnej subskrypcji czy rozliczania przez API.

Następnie otrzymasz link logowania prowadzący do kodu weryfikacyjnego, który wpiszesz w terminalu z uruchomionym Claude Code. To wszystko — a dedykowany workspace „Claude Code” zostanie automatycznie utworzony do śledzenia użycia i zarządzania kosztami.

Claude Code jest gotowy do pracy.

Krok 2: Przygotowanie środowiska developerskiego

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

Zacznijmy od sklonowania repozytorium i przygotowania środowiska pracy.

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. Utwórz wirtualne środowisko i zainstaluj wymagane zależności, uruchamiając po kolei poniższe polecenia:

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

Twoje środowisko Pythona jest gotowe ze wszystkimi potrzebnymi zależnościami do uruchomienia biblioteki Supabase, a repozytorium można już eksplorować. 

Krok 3: Wybór obszarów do kontrybucji

Świetnym punktem wyjścia jest przejrzenie zakładki Issues na GitHubie. W repozytorium Supabase zidentyfikowałem problem w client.py związany z czytelnością, strukturą i brakiem znaczących komentarzy.

Oto co zrobimy z Claude Code:

• Zrefaktoryzujemy kod, by poprawić czytelność, utrzymywalność i strukturę.
• Dodamy sensowne docstringi i komentarze w kodzie, by wyjaśnić przeznaczenie poszczególnych elementów.
• Wykryjemy 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 każdego pliku i folderu w katalogu Supabase‑py. Czas na eksperymenty.

Refaktoryzacja kodu

W ramach ulepszania SDK Supabase dla Pythona zrefaktoryzujmy plik client.py, aby poprawić czytelność, utrzymywalność i organizację. Wpisz 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, pokaże modyfikacje w terminalu i dołączy podsumowanie zmian.

Dzięki Claude Code wprowadziliśmy następujące ulepszenia w client.py:

• Uporządkowane importy:  Claude Code zgrupował pokrewne importy w logiczne sekcje (błędy autoryzacji, typy API, błędy funkcji), zmienił nazwy dla większej jasności i usunął zbędne aliasy dla spójności.
• Wyższa czytelność: Dodano komentarze sekcji klasyfikujące importy i usunięto duplikacje na liście __all__, aby uporządkować strukturę.
• Uproszczone opcje klienta: Zredukowano liczbę linii, łącząc podobne importy w pojedyncze instrukcje.

Poniżej 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 fragmenty, tworzy ustrukturyzowane docstringi i komentarze oraz sprawdza zgodność ze standardami dokumentacji projektu.

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

• Jasne docstringi 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 kluczowe komponenty.

Poniżej porównanie zrefaktoryzowanego i udokumentowanego kodu obok siebie.

Prompt: Udokumentuj kod client.py, dodając komentarze poprawiające zrozumienie.

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

Prompt: Sprawdź, czy dokumentacja spełnia standardy 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 czy chodzi o brakujące importy, błędy wykonania czy problemy logiczne, zawęża obszar poszukiwań i sugeruje celowane poprawki.

Tak użyjesz Claude Code do debugowania:

1. Zidentyfikuj problem:  Udostępnij Claude komunikat błędu.
2. Otrzymaj rekomendacje poprawek: zapytaj Claude o możliwe rozwiązania.
3. Zastosuj i zweryfikuj poprawkę:  wdroż sugestie Claude i sprawdź, czy problem zniknął.

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

• Komentarze type ignore: dodano # type: ignore, by wyciszyć ostrzeżenia IDE i checkerów typów dla nierozwiązanych importów.
• Spójna kategoryzacja błędów: Claude Code zadbał, by importy błędów z autoryzacji, bazy danych, storage i funkcji były jasno pogrupowane.
• Zachowana czytelność: dodano komentarze wyjaśniające, dlaczego pewne importy są ignorowane — zamiast je usuwać.

Poniżej porównanie oryginalnego kodu i wersji z poprawkami.

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

Polecenia Claude Code

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

Polecam też zajrzeć do oficjalnych tutoriali Anthropic oraz naszego przewodnika po najlepszych praktykach Claude Code.

Zaawansowane funkcje Claude Code

Gdy opanujesz podstawy refaktoryzacji i debugowania, możesz rozszerzyć możliwości Claude Code, dostosowując jego zachowanie. Hooki i wtyczki pozwalają automatyzować powtarzalne zadania i integrować zewnętrzne systemy.

Hooki Claude Code

Hooki Claude Code to automatyczne wyzwalacze uruchamiające polecenia shellowe, gdy w trakcie twojej sesji Claude Code zachodzą określone zdarzenia. Automatyzują powtarzalne czynności, takie jak formatowanie kodu, uruchamianie testów czy sprawdzanie bezpieczeństwa, które Claude mógłby pominąć.

Hooki korzystają z systemu zdarzenie–akcja, gdzie definiujesz trzy elementy:

• Zdarzenie: Kiedy hook ma się uruchomić?

• Dopasowanie: Jakie akcje obejmuje?

• Polecenie: Co ma zostać wykonane po wyzwoleniu hooka?

Przykładowo hook może uruchamiać się po zapisaniu pliku Pythona przez Claude i automatycznie wywoływać black do sformatowania kodu. Hooki otrzymują kontekst JSON o tym, co zaszło, co pozwala podejmować inteligentne decyzje w zależności od typów czy ścieżek plików. Mogą wypisywać dane do transkryptu Claude lub wysyłać błędy bezpośrednio do Claude, by blokować operacje.

Typowe zastosowania hooków:

• Formatowanie kodu: automatyczne uruchamianie linterów i formatterów po zapisach

• Testowanie: wykonywanie testów po zmianach, by szybko wychwycić błędy

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

• Dokumentacja: autogenerowanie dokumentacji API przy zmianach w źródłach

• Automatyzacja Git: tworzenie sprytnych commitów i walidacja zasad ochrony gałęzi

• Powiadomienia: informowanie zespołu przez Slacka o zmianach w ważnych plikach

• Zgodność: egzekwowanie nagłówków licencyjnych lub standardów kodowania przed dopuszczeniem zmian

Skonfiguruj hooki komendą /hooks w Claude Code albo edytując ~/.claude/settings.json bezpośrednio.

Wtyczki Claude Code

Wtyczki to rozszerzenia łączące Claude Code z zewnętrznymi narzędziami, usługami i API. Hooki automatyzują lokalne polecenia shellowe, a wtyczki integrują się z szerszym ekosystemem developmentu, jak pipeliny 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) oraz hooki — w jeden pakiet, który nimi orkiestruje.

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

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

• Integracja CI/CD: wyzwalanie buildów, testów i wdrożeń po zmianach plików

• Zarządzanie projektami: automatyczne tworzenie/aktualizowanie zgłoszeń w Jira, GitHub lub Linear

• Komunikacja zespołowa: wysyłanie aktualizacji do Slacka lub Teams po zmianach

• Code review: automatyczne tworzenie pull requestów i obsługa recenzji na GitHub/GitLab

• Analiza zewnętrzna: wywoływanie SonarQube, CodeClimate czy Snyk do skanowania korporacyjnych baz kodu

• Narzędzia własne: integracja z firmowymi systemami i workflowami

• Rozszerzenia IDE: dodawanie własnych poleceń i ułatwień nawigacji

Instaluj wtyczki z rejestru lub buduj je wewnętrznie dla swojej organizacji, a potem skonfiguruj, na jakie zdarzenia mają reagować. Razem hooki i wtyczki tworzą rozszerzalną platformę dopasowującą Claude Code do twojej infrastruktury.

Inne funkcje zaawansowane

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 wdrożenia, zanim napisze jakikolwiek kod. Używam do każdego nietrywialnego zadania.
• Auto mode: klasyfikator pozwoleń, który pozwala Claude pracować z mniejszą liczbą przerw — przydatne w dłuższych zadaniach, gdy nie chcesz zatwierdzać każdego zapisu pliku.
• Routines: harmonogramowane agenty w chmurze uruchamiane według crona, zdarzenia GitHub (np. otwarcie PR) lub webhooka. Twoja maszyna nie musi działać.
• Integracja z IDE: oficjalne rozszerzenia dla VS Code, Cursor i JetBrains z diffami inline, checkpointami i wsparciem wielu sesji.
• Zdalne sterowanie i Channels: uruchamiaj sesje Claude Code i wchodź z nimi w interakcje z telefonu lub innych urządzeń.

Na zakończenie

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

Claude Code aktywnie się rozwija — pojawiły się m.in. plan mode, auto mode i Routines — dlatego warto poeksperymentować na własnych projektach i zobaczyć, jak wpisuje się w twój workflow.

Aby zrobić kolejny krok, zachęcam do lektury naszego tutoriala Claude Code Best Practices, który uczy, jak najlepiej wykorzystać okno kontekstu Claude. Jeśli chcesz zbudować projekt od zera, polecam tutorial Spec-Driven Development with Claude Code.