# Claude Code dla początkujących: analiza i edycja projektów w praktyce

> Praktyczny przewodnik po pracy z Claude Code: eksploracja bazy kodu za pomocą Read, Glob i Grep, przeprowadzanie przeglądów kodu (Code Review), kompleksowa edycja plików oraz bezpieczne cofanie zmian.

## 1. Jak Claude Code eksploruje i czyta kod źródłowy

W przeciwieństwie do zwykłych czatów AI w przeglądarce, gdzie programista musi ręcznie kopiować kod źródłowy do okna dialogowego, Claude Code jest pełnoprawnym agentem terminalowym. Ma bezpośredni dostęp do lokalnego systemu plików Twojego projektu i samodzielnie wybiera wyspecjalizowane narzędzia do nawigacji po bazie kodu.

Agent nie ładuje całego projektu do pamięci jednocześnie (co doprowadziłoby do natychmiastowego wyczerpania limitu tokenów), lecz stosuje punktową strategię etapowego czytania.

```mermaid
flowchart TD
    A["Запит розробника:<br><i>'Як працює авторизація?'</i>"] --> B["Claude Code CLI"]
    B --> C["Glob<br><i>(Пошук файлів auth/*, login.*)</i>"]
    B --> D["Grep<br><i>(Пошук ключових слів createSession, jwt)</i>"]
    C & D --> E["Аналіз знайдених шляхів"]
    E --> F["Read<br><i>(Цільове читання знайдених файлів)</i>"]
    F --> G["Синтез відповіді з точними посиланнями"]
```

### Podstawowy arsenał narzędzi eksploracyjnych

![Przegląd narzędzi nawigacyjnych Claude Code](/api/guides-media/automation/claude-code-practice-guide-for-beginners/images/claude-code-practice-guide-for-beginners-extra-01.webp)

| Narzędzie | Co wykonuje | Typowy scenariusz użycia |
| :--- | :--- | :--- |
| **`Read`** | Otwiera i czyta konkretny plik pod wskazaną ścieżką | `Read src/auth/login.ts` do analizy logiki komponentu |
| **`Glob`** | Znajduje pliki i ścieżki według maski lub rozszerzenia | Wyszukiwanie wszystkich konfiguracji `**/*.config.{js,ts}` lub testów `*.test.ts` |
| **`Grep`** | Wykonuje pełnotekstowe wyszukiwanie znaków lub wyrażeń regularnych | Szukanie miejsc wywołań funkcji lub komentarzy `TODO` w całym kodzie |
| **`Bash(ls)`** | Przegląda strukturę katalogów i dostępne moduły | Eksploracja struktury folderu `src/components/` |

> [!NOTE]
> Nie musisz ręcznie wywoływać tych narzędzi. Wystarczy sformułować pytanie inżynierskie zwykłym językiem, a Claude Code sam uruchomi optymalny łańcuch narzędzi.

---

## 2. Szybki onboarding do nieznanego projektu

Gdy po raz pierwszy otwierasz duże repozytorium, spędzanie godzin na ręcznym czytaniu setek plików jest nieefektywne. Claude Code pozwala uzyskać wyczerpujący obraz architektury w ciągu kilku sekund.

### Formułowanie początkowego zapytania architektonicznego

Wejdź do głównego katalogu repozytorium, uruchom `claude` i zacznij od szerokiego diagnostycznego promptu:

```text
Give me an overview of this project. What does it do, what is the tech stack, and how is the code organized?
```

### Co robi agent podczas skanowania

1. **Czytanie manifestów zależności:** analizuje `package.json`, `Cargo.toml`, `go.mod` lub `requirements.txt`, wykrywając główne biblioteki i frameworki.
2. **Sprawdzanie dokumentacji:** otwiera `README.md`, `ARCHITECTURE.md` lub pliki specyfikacji.
3. **Analiza struktury folderów:** ocenia podział obowiązków między katalogami (`src/api`, `src/components`, `src/services`, `prisma`).
4. **Tworzenie podsumowania:** zwraca ustrukturyzowany raport z listą kluczowych modułów, punktów wejścia i instrukcji uruchomienia.

> [!TIP]
> Wyjaśnienia Claude opierają się na aktualnym kodzie z dysku, a nie na przestarzałej dokumentacji, która często nie jest aktualizowana latami.

---

## 3. Punktowa eksploracja: śledzenie przepływów danych i zapytań

Po zrozumieniu ogólnego obrazu przychodzi czas na badanie konkretnych scenariuszy biznesowych. Najpotężniejszą przewagą Claude Code nad zwykłymi modelami jest zdolność śledzenia pełnego łańcucha wywołań (Call Trace) między różnymi warstwami aplikacji.

:::tabs
@tab Uwierzytelnianie
```text
How does authentication work in this project? Trace the lifecycle of a request from the login form submission through JWT validation to the protected database query.
```
@tab Realizacja zamówienia
```text
What happens when a user submits the checkout form? Trace the request flow from the frontend form to payment gateway processing and email notification dispatch.
```
@tab Obsługa zdarzeń (Webhooks)
```text
Trace how incoming Stripe webhooks are received, verified for signature integrity, and processed in our database transaction worker.
```
:::

### Jak Claude śledzi łańcuchy interakcji

Gdy stawiasz zadanie w formacie „śledź flow”, agent wykonuje następujące kroki:
- Znajduje komponent UI formularza przez `Grep`.
- Znajduje funkcję obsługi kliknięcia i identyfikuje odpowiedni endpoint API.
- Otwiera route backendu i analizuje zastosowane warstwy pośredniczące (middleware).
- Eksploruje wywołania ORM/bazy danych i zwraca spójną schemat krok po kroku z numerami linii.

---

## 4. Głębokie wyszukiwanie wzorców i refaktoryzacja importów

Dzięki wbudowanym narzędziom `Grep` i `Glob`, agent wykonuje precyzyjne wyszukiwanie użycia funkcji, typów lub plików według szablonów, oszczędzając Ci surowego wyjścia terminala.

### Przykłady precyzyjnych zapytań wyszukiwania

```bash
# Знайти всі файли, які імпортують утиліту авторизації
Which files import from @/lib/auth or use the useSession hook?

# Знайти всі залишені технічні борги та мітки
Show me all TODO, FIXME, and HACK comments across the codebase with file paths

# Знайти всі виклики конкретної функції
Where is the calculateDiscount function called, and what parameters are passed to it?

# Знайти файли міграцій бази даних
List all migration files in the prisma/migrations/ directory created in the last month
```

Claude przetwarza wyniki, grupuje je kategorie i wyjaśnia kontekst każdego znalezionego wystąpienia, zamiast po prostu wyrzucać niespójną listę linii.

---

## 5. Rozbiór i analiza złożonych fragmentów kodu

Gdy napotykasz zagmatwany legacy code, niezrozumiałe wyrażenia regularne lub złożone potoki przetwarzania danych, zwróć się do Claude o szczegółowy rozbiór.

### Zapytania o dekonstrukcję kodu

```text
# Analiza łańcucha middleware
Wyjaśnij potok wykonania middleware w pliku src/server/middleware.ts. Co robi każdy element middleware i w jakiej dokładnie kolejności są one wykonywane?

# Wyjaśnienie skomplikowanego wyrażenia regularnego
To wyrażenie regularne w pliku src/utils/validators.ts jest trudne do odczytania. Rozłóż je na części i podaj przykłady ciągów znaków, które pasują oraz nie pasują do tego wzorca.

# Analiza cyklu życia komponentu
Zarządzanie stanem w pliku UserDashboard.tsx wygląda na nadmiernie skomplikowane. Wyjaśnij przepływ stanu, co uruchamia każdy efekt useEffect oraz gdzie mogą wystąpić warunki wyścigu (race conditions).
```

Agent nie tylko parafrazuje kod, ale analizuje przypadki brzegowe (edge cases), potencjalne wycieki pamięci i problemy synchronizacji.

---

## 6. Przeprowadzanie Code Review i analiza Git Diff

Claude Code świetnie nadaje się do lokalnego audytu zmian przed utworzeniem commita lub otwarciem Pull Request.

### Proces przeglądania

```bash
# 1. Швидкий аудит застейджених змін перед комітом
git diff --staged | claude -p "Review this diff for bugs, edge cases, security issues, and style problems. Be concise."

# 2. Перевірка розбіжностей між гілкою задачі та main
git diff main...feature-branch | claude -p "Perform a code review of this branch. Focus on performance regressions and breaking changes."
```

### Interaktywne przeglądanie wewnątrz sesji

Jeśli już jesteś w trybie interaktywnym Claude, po prostu wpisz:

```text
Review the changes I made in the last commit. Look for logic bugs, missing error handling, and potential production bottlenecks.
```

Claude przeanalizuje wyjście `git diff`, wskaże potencjalne problemy z niezawodnością i zaproponuje konkretne poprawki jeszcze zanim kod zobaczą Twoi koledzy.

---

## 7. Narzędzia modyfikacji: Edit, Write oraz Bash

Zrozumienie, jak Claude Code modyfikuje system plików, jest kluczem do kontroli bezpieczeństwa bazy kodu. Do wprowadzania zmian agent używa triady narzędzi: `Edit`, `Write` i `Bash`.

```mermaid
flowchart LR
    subgraph Модифікація_диска["Інструменти редагування"]
        E["Edit Tool<br><i>(Точкова заміна рядків)</i>"]
        W["Write Tool<br><i>(Створення / перезапис файлів)</i>"]
        B["Bash Tool<br><i>(Команди, пакети, збірка)</i>"]
    end
    E --> D["Диференційний перегляд (Diff)"]
    W --> D
    B --> D
    D --> U{"Підтвердження користувача"}
    U -->|Y| S["Збереження на диску"]
    U -->|N| R["Скасування правки"]
```

### Narzędzie Edit: punktowe, chirurgiczne edycje

`Edit` wykonuje punktową zamianę fragmentów tekstu. Znajduje unikalny blok linii w pliku i zastępuje go zaktualizowaną wersją, pozostawiając resztę pliku nietkniętą.

```diff
// Приклад візуалізації дифу в терміналі Claude Code:
async function fetchUser(id: string) {
-  const response = await fetch(`/api/users/${id}`);
-  return response.json();
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch user: ${response.status}`);
+    }
+    return await response.json();
+  } catch (error) {
+    console.error('Error fetching user:', error);
+    throw error;
+  }
}
```

Zawsze widzisz kolorowy diff w terminalu przed zatwierdzeniem zastosowania zmiany.

### Narzędzie Write: tworzenie nowych modułów

`Write` służy do generowania nowych plików od zera lub do całkowitej aktualizacji plików konfiguracyjnych:

```text
Create a new utility module at src/lib/formatters.ts with helpers for currency formatting, relative timestamps, and phone numbers. Include JSDoc comments.
```

### Narzędzie Bash: operacje systemowe i weryfikacja

`Bash` pozwala agentowi interagować z systemem operacyjnym: instalować pakiety, wykonywać migracje, budować projekt i uruchamiać testy.

```text
Install zod and create a registration form schema in src/schemas/auth.ts, then run typecheck to make sure types align.
```

---

## 8. End-to-end changes w wielu plikach jednocześnie

Główną przewagą pełnego podejścia agentowego nad zwykłymi czatami jest zdolność wykonywania spójnych, end-to-end refaktoryzacji, które dotykają różnych warstw architektury.

```text
Add a 'phoneNumber' field to the User entity. Update the Prisma schema, generate the migration, update the registration API route, and add the input field to the Profile form component.
```

### Jak Claude zapewnia spójność edycji

1. **Aktualizacja schemy danych:** edytuje `schema.prisma` przez `Edit`.
2. **Uruchomienie migracji:** wywołuje `npx prisma migrate dev` przez `Bash`.
3. **Aktualizacja walidacji backendu:** dodaje walidację pola do schemy Zod w route `src/app/api/user/route.ts`.
4. **Aktualizacja interfejsu UI:** dodaje pole input do pliku `src/components/ProfileForm.tsx`.
5. **Walidacja kompilacji:** uruchamia `npm run typecheck`, potwierdzając brak konfliktów typów.

Każda akcja wymaga Twojego potwierdzenia, zapewniając pełną przejrzystość procesu.

---

## 9. Iteracyjne dopracowywanie i bezpieczne cofanie edycji

Rozwój z Claude Code to interaktywny dialog. Jeśli wygenerowana edycja wymaga korekty, nie musisz powtarzać całego kontekstu od nowa.

### Doprecyzowanie edycji w kontekście bieżącej sesji

```text
# Zmiana stylu kodu
Wygląda dobrze, ale proszę zastąpić instrukcje if/else zwięzłą instrukcją switch.

# Dodawanie dokumentacji
Świetnie, teraz dodaj wyczerpujące komentarze JSDoc do wszystkich eksportowanych funkcji w tym pliku.

# Optymalizacja wydajności
Czy możemy zmemoizować to obliczenie za pomocą useMemo, aby uniknąć ponownego przeliczania przy każdym renderowaniu?
```

### Mechanizmy cofania niechcianych zmian

Jeśli zmiana została zatwierdzona, ale wynik Cię nie satysfakcjonuje, istnieją dwa niezawodne sposoby przywrócenia stanu poprzedniego:

1. **Przez Claude:**
   ```text
   Undo the last changes you made to src/lib/validation.ts and return the file to its previous state.
   ```
2. **Bezpośrednio przez Git w terminalu:**
   ```bash
   # Скасувати зміни в конкретному файлі
   git checkout -- src/lib/validation.ts

   # Скасувати всі незафіксовані зміни в проєкті
   git reset --hard HEAD
   ```

> [!TIP]
> Rób czysty commit przed rozpoczęciem każdej dużej refaktoryzacji z Claude Code. Pozwala to w dowolnym momencie wrócić do roboczego stanu jedną komendą `git checkout`.

---

## 10. Inżynieryjne najlepsze praktyki i końcowy checklist

Przestrzeganie sprawdzonych praktyk inżynieryjnych przekształca Claude Code w niezawodnego partnera pair programmingu.

### Cztery zasady produktywnego współdziałania

1. **Jedno zadanie – jedno zapytanie:** Nie mieszaj różnych feature’ów w jednym prompcie (*„Dodaj autoryzację, przepisz style nagłówka i usuń stare testy”*). Rozbijaj pracę na atomowe kroki.
2. **Weryfikacja kompilatorem i testami:** Po zakończeniu każdej serii edycji proś asystenta o sprawdzenie wyniku: `Run npm test and npm run typecheck to make sure everything compiles cleanly`.
3. **Zrozumienie mechaniki narzędzi:** Pamiętaj, że punktowe zmiany idą przez `Edit`, nowe pliki przez `Write`, a sprawdzenia przez `Bash`. Pomaga to dawać bardziej precyzyjne instrukcje.
4. **Higiena kontekstu:** Jeśli zadanie zostało wykonane i przechodzisz do zupełnie innego tematu, skorzystaj z komendy `/compact` lub zrestartuj sesję, aby wyczyścić pamięć z zbędnych logów.

### Szybka samoocena

> **1. Jakie narzędzie Claude Code wykorzystuje do punktowej zamiany fragmentów kodu bez pełnego nadpisania pliku?**
>
> > [!TIP]
> > **Odpowiedź:** Narzędzie `Edit`. Znajduje unikalny fragment kodu i wykonuje zamianę, prezentując widok różnicowy (diff).

> **2. Dlaczego Claude Code nie ładuje wszystkich plików projektu do pamięci od razu przy starcie?**
>
> > [!TIP]
> > **Odpowiedź:** Aby nie przekraczać limitów okna kontekstowego i nie marnować zbędnych tokenów. Zamiast tego stosuje celowaną nawigację przez `Glob`, `Grep` i `Read`.

> **3. Jak szybko sprawdzić różnice bieżącej gałęzi PR względem main za pomocą Claude Code?**
>
> > [!TIP]
> > **Odpowiedź:** Uruchomić w terminalu komendę `git diff main...feature-branch | claude -p "Code review this PR"`.

### Końcowy checklist pracy praktycznej

- [ ] Używaj przeglądowych promptów do szybkiego zapoznawania się z nowymi bazami kodu.
- [ ] Eksploruj architekturę poprzez zapytania śledzenia przepływów (*„Trace the flow from UI to database”*).
- [ ] Prowadź lokalne code review przed utworzeniem każdego Pull Request przez `claude -p`.
- [ ] Uważnie przeglądaj kolorowy diff w terminalu przed zatwierdzeniem wywołania `Edit`.
- [ ] Utrwalaj stabilny stan przez `git commit` przed rozpoczęciem złożonych zmian end-to-end.
- [ ] Zawsze kończ zadanie uruchomieniem testów i sprawdzeniem typów przez `Bash`.