# Claude Code для початківців: розбираємо та редагуємо проєкти на практиці

> Практичний посібник з роботи в Claude Code: дослідження кодової бази через Read, Glob та Grep, проведення Code Review, наскрізне редагування файлів та безпечне скасування змін.

## 1. Як Claude Code досліджує та читає кодову базу

На відміну від звичайних AI-чатів у браузері, де розробник змушений вручну копіювати вихідний код у вікно діалогу, Claude Code є повноцінним термінальним агентом. Він має прямий доступ до локальної файлової системи вашого проєкту і самостійно обирає спеціалізовані інструменти для навігації по кодовій базі.

Агент не завантажує весь проєкт у пам'ять одночасно (що призвело б до миттєвого вичерпання ліміту токенів), а застосовує точкову стратегію поетапного читання.

```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["Синтез відповіді з точними посиланнями"]
```

### Основний арсенал інструментів дослідження

![Огляд інструментів навігації Claude Code](/api/guides-media/automation/claude-code-practice-guide-for-beginners/images/claude-code-practice-guide-for-beginners-extra-01.webp)

| Інструмент | Що виконує | Типовий сценарій використання |
| :--- | :--- | :--- |
| **`Read`** | Відкриває та читає конкретний файл за вказаним шляхом | `Read src/auth/login.ts` для вивчення логіки компонента |
| **`Glob`** | Знаходить файли та шляхи за маскою або розширенням | Пошук усіх конфігів `**/*.config.{js,ts}` або тестів `*.test.ts` |
| **`Grep`** | Виконує повнотекстовий пошук символів або регулярних виразів | Пошук місць виклику функції чи коментарів `TODO` по всьому коду |
| **`Bash(ls)`** | Оглядає структуру директорій та наявні модулі | Дослідження структури папки `src/components/` |

> [!NOTE]
> Вам не потрібно вручну викликати ці утиліти. Достатньо сформулювати інженерне запитання звичайною мовою, і Claude Code самостійно запустить оптимальний ланцюжок інструментів.

---

## 2. Швидкий онбординг у незнайомий проєкт

Коли ви вперше відкриваєте великий репозиторій, витрачати години на ручне читання сотень файлів неефективно. Claude Code дає змогу отримати вичерпну архітектурну картину за лічені секунди.

### Формулювання вхідного архітектурного запиту

Увійдіть у корінь репозиторію, запустіть `claude` та почніть із широкого діагностичного промпту:

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

### Що робить агент під час сканування

1. **Читання маніфестів залежностей:** аналізує `package.json`, `Cargo.toml`, `go.mod` або `requirements.txt`, виявляючи основні бібліотеки та фреймворки.
2. **Перевірка документації:** відкриває `README.md`, `ARCHITECTURE.md` або файли специфікацій.
3. **Аналіз структури папок:** оцінює розподіл обов'язків між директоріями (`src/api`, `src/components`, `src/services`, `prisma`).
4. **Формування резюме:** повертає структурований звіт із переліком ключових модулів, точок входу та інструкцій із запуску.

> [!TIP]
> Пояснення Claude будується на актуальному коді з диска, а не на застарілій документації, яка часто не оновлюється роками.

---

## 3. Точкове дослідження: відстеження потоків даних та запитів

Після розуміння загальної картини настає час дослідження конкретних бізнес-сценаріїв. Найпотужніша перевага Claude Code над звичайними моделями — здатність простежувати повний ланцюжок викликів (Call Trace) між різними шарами додатку.

:::tabs
@tab Аутентифікація
```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 Оформлення замовлення
```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 Обробка подій (Webhooks)
```text
Trace how incoming Stripe webhooks are received, verified for signature integrity, and processed in our database transaction worker.
```
:::

### Як Claude простежує ланцюжки взаємодії

Коли ви ставите завдання формату «простеж флоу», агент виконує наступні кроки:
- Знаходить UI-компонент форми через `Grep`.
- Знаходить функцію-обробник кліку та визначає відповідний API-ендпоінт.
- Відкриває роут бекенду та аналізує застосовані проміжні шари (middleware).
- Досліджує виклики ORM/бази даних і повертає зв'язну покрокову схему з номерами рядків.

---

## 4. Глибокий пошук за патернами та рефакторинг імпортів

Завдяки вбудованим інструментам `Grep` і `Glob`, агент виконує точний пошук використання функцій, типів або файлів за шаблонами, позбавляючи вас від сирого виводу термінала.

### Приклади точних пошукових запитів

```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 обробляє результати, групує їх за категоріями та пояснює контекст кожного знайденого входження, а не просто вивалює незв'язний список рядків.

---

## 5. Розбір та аналіз складних ділянок коду

Коли ви стикаєтеся зі заплутаним спадковим кодом, незрозумілими регулярними виразами або складними конвеєрами обробки даних, зверніться до Claude за детальним розбором.

### Запити на деконструкцію коду

```text
# Розбір ланцюжка проміжних обробників (Middleware)
Explain the middleware execution pipeline in src/server/middleware.ts. What does each middleware do, and in what exact order are they executed?

# Пояснення заплутаного регулярного виразу
This regex in src/utils/validators.ts is hard to read. Break it down part by part and provide examples of matching and non-matching strings.

# Аналіз життєвого циклу компонента
The state management in UserDashboard.tsx looks overly complex. Explain the state flow, what triggers each useEffect, and where race conditions might occur.
```

Агент не просто переказує код, а аналізує крайові випадки (edge cases), потенційні витоки пам'яті та проблеми синхронізації.

---

## 6. Проведення Code Review та аналіз Git Diff

Claude Code чудово підходить для локального аудиту змін перед створенням коміту або відкриттям Pull Request.

### Робочий процес рецензування

```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."
```

### Інтерактивне рецензування всередині сесії

Якщо ви вже перебуваєте в інтерактивному режимі Claude, просто введіть:

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

Claude проаналізує вивід `git diff`, вкаже на потенційні проблеми надійності та запропонує конкретні виправлення ще до того, як код побачать ваші колеги.

---

## 7. Інструменти модифікації: Edit, Write та Bash

Розуміння того, як Claude Code модифікує файлову систему, є ключем до контролю за безпекою кодової бази. Для внесення змін агент використовує тріаду інструментів: `Edit`, `Write` та `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["Скасування правки"]
```

### Інструмент Edit: точкові хірургічні правки

`Edit` виконує точкову заміну фрагментів тексту. Він знаходить унікальний блок рядків у файлі та замінює його оновленою версією, зберігаючи решту файлу недоторканою.

```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;
+  }
}
```

Ви завжди бачите кольоровий diff у терміналі перед тим, як погодитися на застосування зміни.

### Інструмент Write: створення нових модулів

`Write` використовується для генерації нових файлів з нуля або для повного оновлення конфігураційних файлів:

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

### Інструмент Bash: системні операції та верифікація

`Bash` дозволяє агенту взаємодіяти з операційною системою: встановлювати пакети, виконувати міграції, збирати проєкт та запускати тести.

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

---

## 8. Наскрізні зміни у кількох файлах одночасно

Головна перевага повноцінного агентного підходу перед звичайними чатами — здатність виконувати узгоджені наскрізні рефакторинги, що зачіпають різні шари архітектури.

```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.
```

### Як Claude забезпечує узгодженість правок

1. **Оновлення схеми даних:** редагує `schema.prisma` через `Edit`.
2. **Запуск міграції:** викликає `npx prisma migrate dev` через `Bash`.
3. **Оновлення бекенд-валідації:** додає валідацію поля в Zod-схему роуту `src/app/api/user/route.ts`.
4. **Оновлення UI-інтерфейсу:** додає поле вводу у файл `src/components/ProfileForm.tsx`.
5. **Валідація компіляції:** запускає `npm run typecheck`, підтверджуючи відсутність конфліктів типів.

Кожна дія запитує ваше підтвердження, забезпечуючи повну прозорість процесу.

---

## 9. Ітеративне доопрацювання та безпечне скасування правок

Розробка з Claude Code — це інтерактивний діалог. Якщо згенерована правка потребує коригування, не потрібно повторювати весь контекст заново.

### Уточнення правок у контексті поточної сесії

```text
# Зміна стилю коду
That looks good, but please replace the if/else statements with a concise switch statement.

# Додавання документації
Great, now add comprehensive JSDoc comments to all exported functions in this file.

# Оптимізація продуктивності
Can we memoize this calculation with useMemo to avoid re-computations on each render?
```

### Механізми скасування небажаних змін

Якщо зміна була схвалена, але результат вас не влаштував, існує два надійних способи повернути все назад:

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

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

> [!TIP]
> Робіть чистий коміт перед початком кожного масштабного рефакторингу з Claude Code. Це дає змогу в будь-який момент повернутися до робочого стану однією командою `git checkout`.

---

## 10. Інженерні найкращі практики та підсумковий чек-лист

Дотримання перевірених інженерних практик перетворює Claude Code на наднадійного партнера з парного програмування.

### Чотири правила продуктивної взаємодії

1. **Одне завдання — один запит:** Не змішуйте різні фічі в одному промпті (*«Додай авторизацію, перепиши стилі хедера і видали старі тести»*). Розбивайте роботу на атомарні кроки.
2. **Верифікація компілятором і тестами:** Після завершення кожної серії правок просіть асистента перевірити результат: `Run npm test and npm run typecheck to make sure everything compiles cleanly`.
3. **Розуміння механіки інструментів:** Пам'ятайте, що точкові зміни йдуть через `Edit`, нові файли через `Write`, а перевірки через `Bash`. Це допомагає давати точніші вказівки.
4. **Контекстна гігієна:** Якщо задача виконана, і ви переходите до принципово іншої теми, скористайтеся командою `/compact` або перезапустіть сесію, щоб очистити пам'ять від зайвих логів.

### Швидка самоперевірка

> **1. Який інструмент Claude Code використовує для точкової заміни фрагментів коду без повного перезапису файлу?**
>
> > [!TIP]
> > **Відповідь:** Інструмент `Edit`. Він знаходить унікальний фрагмент коду та виконує заміну, демонструючи диференційний перегляд (diff).

> **2. Чому Claude Code не завантажує всі файли проєкту в пам'ять одразу при запуску?**
>
> > [!TIP]
> > **Відповідь:** Щоб не перевищувати ліміти контекстного вікна і не витрачати зайві токени. Замість цього він використовує цільову навігацію через `Glob`, `Grep` та `Read`.

> **3. Як швидко перевірити відмінності поточної PR-гілки від main за допомогою Claude Code?**
>
> > [!TIP]
> > **Відповідь:** Виконати в терміналі команду `git diff main...feature-branch | claude -p "Code review this PR"`.

### Підсумковий чек-лист практичної роботи

- [ ] Використовуйте оглядові промпти для швидкого знайомства з новими кодовими базами.
- [ ] Досліджуйте архітектуру через запити відстеження потоків (*«Trace the flow from UI to database»*).
- [ ] Проводьте локальне код-рев'ю перед створенням кожного Pull Request через `claude -p`.
- [ ] Уважно переглядайте кольоровий diff у терміналі перед підтвердженням виклику `Edit`.
- [ ] Фіксуйте стабільний стан через `git commit` перед початком складних наскрізних змін.
- [ ] Завжди завершуйте задачу запуском тестів і перевіркою типів через `Bash`.