Перейти к содержимому
TelegramGitHub

Claude AI Bible, глава 13: Claude Code: агент для кода в терминале

Главная мысль: Claude Code превращает Claude в агента, который сам читает проект, правит файлы и запускает команды. Это сильный инструмент, поэтому он требует дисциплины: сначала план, потом правки, а git служит кнопкой «отменить».

В главе 12 агент работал в таблицах. Теперь автор переходит в терминал и объясняет, как дать агенту доступ к коду и не потерять контроль. Темы: первая сессия, цикл агента, план до правок, subagent, hooks, CLAUDE.md, git как защита, MCP server, slash-команды и цена.

Цикл Claude Code: вы описываете результат, агент изучает файлы, пишет план, вы его одобряете, затем агент правит, запускает тесты и чинит ошибки до успеха

Схема читается по часовой стрелке: верхний ряд — подготовка, нижний — работа, пока тесты не пройдут.

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

Другие продукты Claude живут в чате, и работу после ответа делаете вы. Claude Code делает эту работу сам. Автор подчёркивает, что инструмент полезен не только программистам: с ним справились руководитель маркетинга с CSV-выгрузками, владелец малого бизнеса и исследователь с папкой данных. Здесь важно не умение программировать, а умение описать задачу и проверить результат.

Это терминальная программа: её запускают командой claude в папке проекта. Дальше вы разговариваете с Claude, но его ответы меняют проект. Claude создаёт, меняет и удаляет файлы, запускает shell-команды (сборку, тесты, запросы к базе и API) и после каждого действия читает вывод.

Автор называет это сдвигом от ассистента к оператору: ассистент даёт инструкции, а оператор выполняет их сам. Такая схема сильнее, но и опаснее, ведь без проверки легко получить удалённую папку или неожиданный счёт.

Модели те же, что в главе 2: Opus 4.8 для сложных рассуждений, Sonnet 4.6 по умолчанию, Haiku 4.5 для механических правок. Модель можно сменить посреди сессии. Отличие от чата не в модели («мозге»), а в «теле»: доступ к файлам и shell плюс цикл «сделал, посмотрел, сделал снова».

Команда установки со временем меняется, поэтому автор советует сверить её с docs.claude.com. В книге показан вариант через npm:

Окно терминала
npm install -g @anthropic-ai/claude-code
claude --version
cd ~/projects/order-tracker
claude
2.1.325 (Claude Code)

Пояснение: сейчас Anthropic рекомендует native installer (curl -fsSL https://claude.ai/install.sh | bash), он сам обновляет программу. Вывод claude --version выше — с нашей машины.

При первом запуске нужно войти, и два способа входа — это два разных кошелька (глава 4):

ВходКак платите
Аккаунт ClaudeРасход идёт из лимитов подписки Pro или Max, общих с чатом
API keyКаждый токен считается и оплачивается отдельно

Автор советует не начинать с «сделай мне приложение». Откройте знакомый проект и попросите: «Объясни, что делает проект и как он устроен. Ничего не меняй». Запрос безопасен, а ответ стоит оценить: если Claude не понял проект, вы узнаете это до первой правки.

Хорошая сессия проходит пять шагов, и, зная их, вы можете вмешаться вовремя:

  1. Explore. Агент читает файлы и идёт по импортам, иногда десяток файлов до первой правки. Поэтому правка учитывает, как устроен код, а не противоречит ему.
  2. Plan. Агент описывает, какие файлы тронет и что ожидает. Это ваша лучшая точка контроля.
  3. Edit. Агент вносит правки и показывает каждую как diff.
  4. Run. Он запускает тесты, linter или сервер и читает вывод.
  5. Iterate. Если что-то упало, агент ищет причину и пробует снова. Он видит реальный результат, а не гадает, и на этой обратной связи держится agentic-подход.

Пример сессии из книги, на нашей задаче:

> Добавь проверку в загрузчик клиентов: пустой email и короткий телефон отклонять.
● Ищу загрузчик... нашёл src/load_customers.py и src/checks.py
● В checks.py уже есть is_email(). Переиспользую её и добавлю check_phone().
План: 1) check_phone() в checks.py 2) вызов в загрузчике 3) тесты. Продолжить?
> да
● Правки: checks.py (+11), load_customers.py (+8 -2), tests/test_load.py (+24)
● Запуск pytest: FAIL, телефон "123" прошёл проверку
● Регулярное выражение пропускает короткие номера. Исправляю checks.py (+1 -1)
● Запуск pytest: 12 passed

Агент сам нашёл файлы, взял готовую функцию и исправил свою ошибку, а вы лишь одобрили план и прочитали три diff.

Самая ценная привычка — требовать план, если задача трогает больше двух-трёх файлов. Для этого есть plan mode — режим, в котором агент только читает и думает и ничего не меняет до вашего одобрения. Пример: «Напиши план перевода дат на новую утилиту: файлы и порядок. Жди одобрения».

План можно поправить: запретить хрупкий файл, сменить порядок или увидеть, что агент не понял задачу. Типичный сбой агента — не «ничего не сделал», а «быстро сделал много, но не туда». План стоит дёшево, а распутывать правки дорого.

Дорогая ошибка на этом шаге — большая задача без плана и без commit. Если работа пойдёт не так, останутся частично применённые правки по многим файлам. Поэтому автор советует две привычки: план для всего большого и commit до старта.

На длинной задаче агент заполняет свой context window всем прочитанным и начинает путаться в задаче. Выход — делегировать. Subagent — это отдельный исполнитель: он делает узкую часть работы в своём чистом контексте и возвращает главному агенту сводку.

Автор сравнивает это с прорабом, который держит общий план и раздаёт проводку и сантехнику специалистам. Пример: «Через subagent параллельно напиши тесты модулей цен и скидок и найди функции длиннее 80 строк».

Главный агент раздаёт три задачи трём subagent, каждый работает в своём контексте и возвращает сводку

Выгода двойная: работа идёт одновременно, а главный разговор остаётся чистым. Ещё один приём автора — subagent как одноразовый исследователь: пусть он прочитает тридцать файлов и вернёт только вывод и пути. Тогда главная сессия не тормозит и не «забывает».

Hooks — это команды, которые срабатывают сами в заданные моменты: перед вызовом инструмента, после него, в начале сессии и в конце задачи. Так правила проекта выполняются без напоминаний.

События hooks: SessionStart, PreToolUse может заблокировать команду, PostToolUse запускает форматирование и проверку типов, Stop в конце задачи

Классический пример — форматирование и typecheck после каждой правки: если проверка упала, агент видит ошибку и чинит её. Hook перед запуском может проверить команду и запретить опасную, и эта защита не зависит от суждения модели.

Пример автора — стартап из Лиссабона, где агент дважды сбросил локальную базу, не проверив среду. Команда добавила hook: db:reset и migrate:fresh запрещены, пока переменная среды не пометит сессию как локальную. На него ушло десять минут, и за полгода сбоев не было.

Наш вариант такого hook для data-проекта (.claude/settings.json):

{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "python3 .claude/hooks/block_db_reset.py" }]
}
],
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "npm run format && npm run typecheck" }]
}
]
}
}

Пояснение: в книге command стоит рядом с matcher. В текущем Claude Code команды лежат во вложенном массиве hooks с "type": "command". Если скрипт hook завершается с кодом 2, Claude Code отменяет действие.

Скрипт — ch13_block_db_reset.py. Тест ch13_hook_test.py подаёт скрипту на вход такой же JSON, какой передаёт Claude Code:

npm test APP_ENV=- exit=0 пропущено
npm run db:reset APP_ENV=- exit=2 блок Заблокировано: 'db:reset' разрешён только при APP_ENV=local
npm run db:reset APP_ENV=local exit=0 пропущено
dbt run --full-refresh --target prod APP_ENV=prod exit=2 блок Заблокировано: '--full-refresh' разрешён только при APP_ENV=local

Файл settings есть на уровне пользователя (для всех проектов) и проекта (его коммитят для команды). Настройки проекта перекрывают личные: правила команды важнее привычек одного человека. В файле задают модель и permissions — что агент делает без вопроса:

{
"model": "claude-sonnet-4-6",
"permissions": {
"allow": ["Read", "Edit", "Bash(npm test)", "Bash(npm run *)"],
"deny": ["Bash(rm -rf *)", "Bash(git push *)"]
}
}

Агенту можно читать, править и запускать npm-скрипты, но нельзя удалять рекурсивно и делать git push. Автор советует начинать со строгих прав и ослаблять их по мере доверия.

Больше всего пользы даёт CLAUDE.md — Markdown-файл в корне проекта. Claude Code читает его в начале каждой сессии: что за проект, команды, соглашения и запреты. Хороший файл короткий. В книге пример для пекарни, наш — для data-проекта:

# Проект: витрина заказов
## Что это
Pipeline загружает заказы из CSV в DuckDB и строит витрину для BI.
## Команды
- `make test`: тесты, должны проходить до конца любой задачи
- `make format`: форматирование, запускать после правок
## Соглашения
- Деньги храним в центах (integer), никогда во float.
- Даты в ISO 8601 и UTC, перевод в местное время только в BI.
## Никогда
- Не править `legacy/`: эта папка заморожена.
- Не коммитить `.env` и реальные данные клиентов.

Минута на CLAUDE.md окупается в каждой сессии. Если агент нарушил соглашение, не ругайте его, а допишите правило в файл.

Главное правило автора: делайте commit постоянно. Если перед задачей был commit, любой исход откатывается одной командой.

Цикл с git: чистое состояние, задача, просмотр diff; хорошие правки идут в commit, плохие откатываются к прошлому commit

Окно терминала
git status # перед задачей: рабочая копия чистая
git diff # после задачи: читаем все правки
git add -A && git commit -m "Фильтр пустых заказов"
git restore . # задача пошла не так: отменить правки
git reset --hard HEAD # или жёсткий откат к последнему commit

Наш скрипт ch13_git_safety.sh проходит этот цикл во временной папке:

== 1. Перед задачей: рабочая копия чистая
(нет изменений)
== 2. Агент поменял файл. Смотрим diff перед commit
orders.sql | 1 +
1 file changed, 1 insertion(+)
== 3. Следующая задача пошла не так: откатываем
M orders.sql
?? tmp_debug.txt
(снова чисто)
== 4. История: один commit на задачу
Фильтр пустых заказов
Чистое состояние до задачи

Перед commit читайте полный git diff как ревьюер: не поменял ли агент лишнее, не оставил ли отладочный вывод. Код пишет агент, а решаете, годится ли он, вы. Один commit на задачу даёт точную отмену, а рискованную работу лучше вести в ветке. Самая болезненная ошибка — час работы без commit: если сбой случился три задачи назад, отменить только его уже нельзя.

MCP server — это программа, которая по общему протоколу даёт агенту новые возможности: читать базу, трекер задач или документы. Подробно о протоколе — в главе 16. Сервер подключают в конфигурации, например в .mcp.json:

{
"mcpServers": {
"company-docs": {
"command": "npx",
"args": ["-y", "@yourco/docs-mcp-server"],
"env": { "DOCS_API_KEY": "${DOCS_API_KEY}" }
}
}
}

Теперь можно попросить: «Найди в company-docs политику rate limit и поправь клиент под неё». Агент не гадает, а читает реальные данные. Но каждый сервер — новый путь доступа к вашей среде, поэтому подключайте только доверенные серверы с минимальными правами.

Ввод со слешем идёт не модели, а самому инструменту и управляет сессией. Список меняется, поэтому начните с /help:

КомандаЗачем
/helpСписок команд вашей версии
/clearНачать с чистого листа при смене задачи
/compactСжать историю в сводку, чтобы длинная сессия не тормозила
/modelСменить модель: Haiku для механики, Opus для сложного
Просмотр правок и ваши командыПосмотреть ожидающие правки; ваши команды зависят от настройки

Частый многошаговый запрос можно сохранить как свою команду (см. главу 14). Автор особо советует /compact: если сессия стала медленной и забывчивой, сводка сохранит решения и сбросит лишние детали.

Работа агента тратит больше токенов, чем чат: он читает файлы, запускает команды и повторяет попытки. На подписке вы быстрее упрётесь в лимиты, на API увидите это в счёте. Автор считает, что работа обычно стоит этих денег, но советует:

  • Sonnet 4.6 по умолчанию, Opus 4.8 для сложного, Haiku 4.5 для механики;
  • узко ставить задачу, чтобы агент не перечитывал весь проект;
  • вести CLAUDE.md, чтобы агент не изучал проект заново.

Вторая опасность — привычка. Первые десять diff вы читаете внимательно, а к пятидесятому хочется просто нажать «одобрить». Именно тогда вы и пропустите ошибку агента, поэтому дисциплину лучше выработать сразу.

  • Claude Code — терминальная программа, с которой Claude сам читает, правит и запускает код проекта.
  • Инструмент полезен и не программистам: важно описать задачу и проверить результат.
  • Цикл агента: explore, plan, edit, run, iterate.
  • Задаче, которая трогает больше двух-трёх файлов, нужен план, одобренный вами.
  • Subagent работает в своём контексте и держит главную сессию чистой.
  • Hooks сами выполняют правила проекта и могут запретить опасную команду.
  • Короткий CLAUDE.md — самая выгодная настройка проекта.
  • Git — кнопка «отменить»: commit до задачи, полный diff перед commit, маленькие commit часто.
  • Цену контролируют выбор модели, узкие задачи и CLAUDE.md, а проверку diff бросать нельзя.
ТерминЗначение
plan modeАгент составляет план и ничего не меняет до одобрения
subagentОтдельный агент со своим контекстом, возвращает сводку
hooksКоманды на события сессии: PreToolUse, PostToolUse и другие
permissionsЧто агенту можно без вопроса и что запрещено
CLAUDE.mdИнструкции проекта, Claude Code читает их в начале сессии
diffРазница между старой и новой версией файлов
  • В CLAUDE.md dbt- или Airflow-проекта опишите команды тестов, именование и запретные папки.
  • Добавьте PreToolUse hook против --full-refresh, DROP TABLE и --target prod.
  • Запретите агенту git push и доступ к боевым учётным данным.
  • Перед миграцией схемы просите план со списком файлов.
  • Подключайте MCP server к базе только на чтение.
  1. Чем оператор отличается от ассистента и почему это и сильнее, и опаснее?
  2. Почему первый запрос в новом проекте лучше сделать без права на правки?
  3. Когда нужен план до выполнения и какой сбой агента он предотвращает?
  4. Почему subagent помогает на длинных задачах, даже без параллельной работы?
  5. Чем hook надёжнее правила в CLAUDE.md для опасных команд?
  6. Почему час работы без commit опаснее пяти маленьких commit?

Предыдущая: Claude in Excel: агент для таблиц. Следующая: Skills — многоразовые умения.