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 deweloperskich za pomocą poleceń w języku naturalnym. Integruje się z twoim środowiskiem deweloperskim 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 propozycjom wspieranym przez AI.
• Naprawa błędów: identyfikuj i usuwaj błędy, brakujące zależności oraz wąskie gardła wydajnościowe.
• 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 poprawiaj 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 firmową bazą kodu, Claude Code zapewnia inteligentną automatyzację dopasowującą się do twojego stylu i wymagań projektu. Najnowsze aktualizacje wprowadziły auto mode (mniej przerw na uprawnienia), plan mode (workflow z projektowaniem przed implementacją) oraz Routines (planowane agentowe zadania w chmurze uruchamiane przez wyzwalacze bez konieczności włączonej twojej maszyny).

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

• Programiści: poprawa jakości i łatwości utrzymania kodu.
• Kontrybutorzy open source: zrozumienie i ulepszanie nieznanych baz kodu.
• Inżynierowie DevOps: automatyzacja przeglądów 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łączyć się na Opus do bardziej wymagających zadań. Możesz zmienić model w trakcie sesji komendą /model lub regulować głębokość rozumowania suwakiem /effort. Możesz też budować samodzielne agentowe aplikacje przy użyciu Claude Agents SDK.

Anthropic wprowadził także Cowork do wsparcia w stylu agenta przy codziennej pracy z plikami i dokumentami poza kodowaniem. Dostępny jest dla wszystkich płatnych planów (Pro, Max, Team, Enterprise) w aplikacji Claude Desktop.

Jeśli porównujesz Claude Code z agentem terminalowym xAI, nasz Grok Build vs. Claude Code testuje oba na tym samym zadaniu.

Zacznijmy nasz projekt praktyczny.

Krok 1: Konfiguracja Claude Code

Aby zacząć z Claude Code, potrzebujesz terminala, projektu kodowego do pracy 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ń — odpowiednie dla twojego systemu 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, więc preferuj natywny proces instalacji opisany wyżej. Jeśli wcześniej instalowałeś przez npm, możesz przenieść się poleceniem claude install.

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

cd your-project-directory
claude

Na potrzeby uwierzytelnienia zostaniesz zapytany, czy chcesz używać Claude Code w oparciu o płatną subskrypcję, czy rozliczanie użycia API.

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

Teraz Claude Code jest gotowy do użycia.

Krok 2: Konfiguracja środowiska deweloperskiego

W tym demo użyję biblioteki Supabase w Pythonie supabase-py — otwartoźródłowego klienta Pythona do interakcji 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 przygotowania środowiska.

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 w terminalu kolejno poniższe polecenia

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

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

Krok 3: Wybór obszarów do kontrybucji

Świetnym sposobem na kontrybucję jest przejrzenie zakładki Issues na GitHubie. W repozytorium Supabase zidentyfikowałem problem w client.py dotyczący czytelności kodu, struktury i braku sensownych komentarzy.

Oto co zrobimy z pomocą Claude Code:

• Zrefaktoryzujemy kod, by poprawić czytelność, utrzymywalność i strukturę.
• Dodamy sensowne docstringi i komentarze w linii, by wyjaśnić cel różnych elementó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 katalogu supabase-py. No to poeksperymentujmy.

Refaktoryzacja kodu

W ramach ulepszania Supabase Python SDK zrefaktoryzujmy plik client.py, by poprawić czytelność, utrzymywalność i organizację. Wpisz po prostu w wierszu poleceń poniższy prompt:

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 dokonanych zmian.

Korzystając z Claude Code, wprowadziliśmy następujące usprawnienia w client.py:

• Uporządkowane importy:  Claude Code zgrupował powiązane importy w logiczne sekcje (błędy auth, typy API, błędy funkcji), zmienił nazwy importów dla przejrzystości i usunął zbędne aliasy dla spójności.
• Zwiększona czytelność: dodano komentarze sekcji klasyfikujące importy i usunięto duplikacje na 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. Może wskazać nieudokumentowane fragmenty, tworzyć ustrukturyzowane docstringi lub komentarze oraz sprawdzać zgodność ze standardami dokumentacji projektu.

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

• Jasnymi docstringami na poziomie modułu, wyjaśniającymi cel pliku.
• Szczegółowymi komentarzami sekcji kategoryzującymi importy (typy błędów, implementacje klienta, usługi storage).
• Komentarzami w linii opisującymi typy błędów, funkcje klienta i ważne komponenty.

Oto 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 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 w czasie wykonania czy problemy logiczne, zawęża przestrzeń 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ż propozycje Claude i sprawdź, czy problem ustąpił.

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

• Komentarze type ignore: dodano komentarz # type: ignore, by wyciszyć ostrzeżenia IDE i checkerów typów dotyczące nierozwiązanych importów.
• Spójna kategoryzacja błędów: Claude Code zadbał, by importy błędów z auth, bazy, storage i funkcji były jasno pogrupowane.
• Zachowana czytelność kodu: dodano komentarze wyjaśniające, dlaczego niektóre importy pominięto, zamiast je usuwać.

Oto porównanie oryginalnego kodu i kodu po naprawie błędów.

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 komend, które możesz wypróbować z Claude.

Po więcej szczegółów zajrzyj do naszego przewodnika slash commands w Claude Code.

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 Claude Code to automatyczne wyzwalacze uruchamiające polecenia shellowe, gdy podczas twojej sesji Claude Code wystąpią określone zdarzenia. Automatyzują powtarzalne zadania, jak formatowanie kodu, uruchamianie testów i kontrole bezpieczeństwa, które Claude mógłby pominąć.

Hooki używają systemu zdarzenie–akcja, w którym definiujesz trzy rzeczy:

• Zdarzenie: kiedy hook ma się uruchomić?

• Matcher: które akcje są objęte?

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

Przykładowo, hook może uruchomić się po zapisaniu przez Claude pliku Pythona i automatycznie uruchomić black w celu sformatowania kodu. Hooki otrzymują kontekst JSON o tym, co zaszło, co umożliwia inteligentne decyzje zależnie od typów plików czy ścieżek. Mogą wypisywać do transkryptu Claude lub przesyłać komunikaty o błędach bezpośrednio do Claude, by blokować operacje.

Typowe zastosowania hooków obejmują:

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

• Testowanie: uruchamianie zestawów testów po modyfikacjach, by wcześnie wychwytywać błędy

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

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

• Automatyzacja Gita: tworzenie inteligentnych commitów i walidacja zasad ochrony gałęzi

• Powiadomienia: alertowanie zespołu na Slacku przy zmianach istotnych plików

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

Skonfiguruj hooki komendą /hooks w Claude Code lub 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. Podczas gdy hooki automatyzują lokalne polecenia shellowe, wtyczki integrują się z szerszym ekosystemem deweloperskim, 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) oraz hooki — w jeden pakiet, który je orkiestruje.

Wtyczka może analizować zmiany w kodzie i automatycznie tworzyć 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 usług zewnętrznych i przetwarzają odpowiedzi, by wpływać na workflow Claude.

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

• Integracja z CI/CD: wyzwalanie buildów, testów i wdrożeń przy zmianach w plikach

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

• Komunikacja zespołu: publikowanie aktualizacji do Slacka lub Teams przy zmianach

• Przegląd kodu: automatyczne tworzenie pull requestów i zarządzanie recenzjami na GitHub/GitLab

• Analiza zewnętrzna: wywołania SonarQube, CodeClimate lub Snyk do skanowania kodu w firmie

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

• Rozszerzenia IDE: dodawanie własnych komend i pomocników nawigacji

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

Inne funkcje zaawansowane

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

• Plan mode: workflow z projektowaniem najpierw — Claude tworzy szczegółowy plan implementacji przed napisaniem kodu. Używam tego przy wszystkich nietrywialnych zadaniach.
• Auto mode: klasyfikator uprawnień, który pozwala Claude pracować z mniejszą liczbą przerw — przydatne przy dłuższych zadaniach, gdy nie chcesz zatwierdzać każdego zapisu pliku.
• Routines: planowane agentowe zadania w chmurze uruchamiane według crona, zdarzenia GitHub (np. otwarcie PR) lub wywołania webhooka. Twoja maszyna nie musi być włączona.
• Integracja z IDE: Claude Code ma oficjalne rozszerzenia do VS Code, Cursor i IDE JetBrains z diffami inline, checkpointami i wsparciem wielu sesji.
• 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 refaktoryzacji, dokumentowania i debugowania 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 — plan mode, auto mode i Routines — więc warto poeksperymentować w swoich projektach i sprawdzić, jak wpisuje się w twój workflow.

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