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