Claude Code: pierwsza sesja krok po kroku, od instalacji do commita

Claude Code to agent programistyczny działający w terminalu: czyta kod w repozytorium, proponuje zmiany, uruchamia polecenia i potrafi przygotować commit. Ten przewodnik prowadzi przez pierwszą sesję tak, żeby skończyła się czymś użytecznym, a nie bałaganem w repozytorium. Zakładam, że masz zainstalowane narzędzie według oficjalnej instrukcji i konto, które pozwala się zalogować.

Zanim zaczniesz: przygotuj bezpieczne miejsce

Pierwsza zasada jest nudna i ratuje przed większością problemów: pracuj w repozytorium Git, w którym nie ma niezatwierdzonych zmian. Wtedy każdą propozycję agenta da się obejrzeć jako różnicę i w razie czego cofnąć jednym poleceniem. Utwórz osobną gałąź na ćwiczenie, na przykład cwiczenie-claude-code, i dopiero w niej uruchom agenta.

Wybierz zadanie małe i sprawdzalne. Dobre pierwsze zadania to poprawka literówek w dokumentacji, dopisanie testu do istniejącej funkcji albo wyjaśnienie, jak działa moduł, którego nie rozumiesz. Złe pierwsze zadania to „przepisz całą aplikację” albo „napraw wszystko”. Agent działa najlepiej, gdy wie, jak ma wyglądać koniec pracy, a ty potrafisz to sprawdzić.

1. 01
   Czyste repoGałąź robocza, brak niezatwierdzonych zmian.
2. 02
   CLAUDE.mdZasady projektu zapisane raz.
3. 03
   PlanAgent opisuje, co zrobi, zanim zacznie.
4. 04
   ZmianaMałe kroki, każdy z możliwością cofnięcia.
5. 05
   PrzeglądCzytasz różnicę i uruchamiasz testy.
6. 06
   CommitZatwierdzasz ty, z opisem własnymi słowami.

CLAUDE.md: pamięć projektu zamiast powtarzania się

Bez dodatkowych instrukcji agent zaczyna każdą sesję od zera. Plik CLAUDE.md w katalogu głównym repozytorium jest wczytywany na starcie i działa jak krótka instrukcja dla nowego współpracownika. Dokumentacja pamięci opisuje też poziomy: plik projektu, plik użytkownika i pliki w podkatalogach.

Dobry CLAUDE.md jest krótki i konkretny. Zapisz w nim polecenia, których nie da się odgadnąć (jak uruchomić testy, jak zbudować projekt), konwencje, które odbiegają od domyślnych (styl nazw, język komunikatów) oraz rzeczy zakazane (nie ruszaj katalogu vendor, nie edytuj plików wygenerowanych). Nie przepisuj tam dokumentacji ani ogólnych porad w rodzaju „pisz czysty kod”, bo rozmywają to, co ważne.

# Zasady projektu
- Testy: npm test (szybkie), npm run test:e2e (wolne, tylko przed wydaniem).
- Nazwy plików: kebab-case. Komunikaty dla użytkownika po polsku.
- Nie edytuj katalogów dist/ i vendor/.
- Każda zmiana w logice ma test.

Taki plik to kilka linii, a oszczędza powtarzania tych samych poleceń. Gdy zauważysz, że poprawiasz agenta w ten sam sposób drugi raz, dopisz regułę do pliku. Więcej o doborze treści znajdziesz w przewodniku dobrych praktyk.

Najpierw plan, potem zmiany

Przy zadaniu większym niż jedna poprawka poproś o plan, zanim agent cokolwiek zmieni. Claude Code ma tryb planowania, w którym agent czyta kod i proponuje kroki bez edytowania plików. To najtańsza kontrola: jeśli plan jest zły, poprawiasz zdanie, a nie pięć plików.

Dobry plan odpowiada na trzy pytania. Które pliki zostaną zmienione? Jak sprawdzisz, że działa? Co może się zepsuć przy okazji? Jeśli agent nie potrafi odpowiedzieć na drugie pytanie, sam zaproponuj kryterium, na przykład „istniejące testy przechodzą i nowy test pokrywa przypadek z błędem”. Więcej o takim podejściu do człowieka w pętli piszę w hubie Człowiek w pętli.

Uprawnienia: co wolno bez pytania

Domyślnie Claude Code pyta o zgodę przed edycją plików i uruchomieniem poleceń. To dobre ustawienie na start. Z czasem zobaczysz powtarzające się, bezpieczne prośby, na przykład o uruchomienie testów, i wtedy możesz wybrać „nie pytaj ponownie”: reguła zapisze się w pliku .claude/settings.local.json repozytorium. Opisuje to dokument o uprawnieniach, a miejsca zapisu ustawień wyjaśnia strona ustawień.

Reguła kciuka: zezwalaj na polecenia tylko do odczytu i na testy, zakazuj tego, czego nie chcesz nigdy (na przykład odczytu plików z sekretami), a wszystko inne zostaw z pytaniem. Reguły sprawdzane są w kolejności: najpierw „zakaz”, potem „pytaj”, na końcu „zezwól”, więc wąskie zezwolenie nie wyłączy szerszego zakazu. Szerokie zezwolenia „na wszystko” zostaw sobie na izolowane środowiska jednorazowe, nie na laptop z kluczami do produkcji.

Przegląd i commit: ostatnie słowo należy do ciebie

Gdy agent skończy, nie zatwierdzaj od razu. Przeczytaj różnicę zmian tak, jakbyś robił przegląd kodu kolegi: czy zmiany dotyczą tylko tego, o co prosiłeś, czy nie dotknięto plików obok, czy testy faktycznie coś sprawdzają. Uruchom je sam, zamiast polegać na deklaracji „wszystko przechodzi”.

Dopiero potem poproś o commit albo zrób go sam. Opis commita napisz własnymi słowami lub popraw ten, który zaproponował agent, tak by wyjaśniał powód zmiany, a nie tylko jej treść. Gdy sesja idzie źle, nie brnij: wyczyść kontekst, wróć do ostatniego dobrego stanu w Git i zacznij od lepiej sformułowanego zadania. Rozszerzenia, takie jak serwery MCP czy agenci pomocniczy, dołóż dopiero, gdy podstawowy obieg zacznie ci ciążyć.

Typowe błędy na początku

Pierwszy błąd to zbyt ogólne zadanie. „Popraw formularz” zmusza agenta do zgadywania, a „dodaj walidację adresu e-mail w formularzu kontaktowym i test, który odrzuca adres bez znaku @” daje mu jasny cel. Drugi błąd to przeładowany kontekst: długa rozmowa o kilku niepowiązanych sprawach sprawia, że agent gubi wątek, więc przy nowym zadaniu zacznij nową sesję. Trzeci błąd to ślepe zaufanie do podsumowania. Agent może napisać, że wszystko działa, a ty i tak sprawdzasz to poleceniem, które sam uruchomisz.

Czwarty błąd to pomijanie kopii zapasowej. Git chroni kod, ale nie chroni plików poza repozytorium ani bazy danych, więc nie pozwalaj agentowi dotykać produkcji, dopóki nie masz sprawdzonego sposobu wycofania zmian.

Lista kontrolna pierwszej sesji

• Czyste repozytorium i osobna gałąź.
• Krótki CLAUDE.md z poleceniami testów i zakazami.
• Zadanie małe i sprawdzalne, z kryterium ukończenia.
• Plan przeczytany przed pierwszą zmianą.
• Uprawnienia domyślne, bez zezwoleń „na wszystko”.
• Różnica przeczytana, testy uruchomione osobiście.
• Commit z opisem, który tłumaczy powód zmiany.

Stan wiedzy: 20 października 2026. Narzędzie rozwija się szybko, więc nazwy poleceń i ustawień zawsze potwierdź w dokumentacji, do której prowadzą źródła pod tekstem.