Строим с Claude Code

Весь курс мы писали код руками, чтобы понять, как устроен API. В работе большую часть этого кода за вас напишет Claude Code — агент для разработчика, которому посвящён отдельный курс. В этом уроке разберём, как использовать его именно для разработки приложений на Claude API: как ставить задачу, чем снабдить, где он ошибается и как это проверять.

Почему здесь есть подвох

Claude Code пишет код на основе того, что модель знает, а API Claude менялся в 2025–2026 годах заметно: изменился способ включения рассуждения, версии встроенных инструментов, параметры структурированного вывода, появились Managed Agents. Модель может уверенно написать thinking: { type: "enabled", budget_tokens: 4000 } — и это будет ошибка 400 на Opus 5. Или подставить идентификатор модели с датой, которого не существует.

Поэтому главное правило: Claude Code должен работать от документации, а не от памяти. Всё остальное в уроке — способы это обеспечить.

Дать документацию

Самый прямой способ — сослаться на документацию в задаче. У Claude Code есть инструмент загрузки страниц, и он сходит по ссылке сам.

Прочитай https://docs.claude.com/en/docs/build-with-claude/tool-use и
https://docs.claude.com/en/docs/about-claude/models, а потом реализуй
в src/review/ агента, который проверяет pull request: инструменты get_diff
и read_file, модель claude-opus-5, адаптивное рассуждение, tool runner из SDK.

Второй способ — положить актуальные примеры в репозиторий. Если у команды уже есть работающая интеграция (тот же классификатор из второго урока), скажите: «Возьми за образец src/support/classify.ts». Рабочий код в репозитории для модели убедительнее любых инструкций.

Третий — проверить, есть ли в вашей установке Claude Code встроенный справочник по Claude API. В свежих версиях он поставляется как навык и загружается, когда в задаче упоминается Anthropic SDK; проверить можно командой /skills или вопросом «какие навыки у тебя есть». Если справочник есть, Claude Code сверится с ним сам; если нет — ссылки на документацию обязательны.

Записать правила в CLAUDE.md

Всё, что вы узнали в курсе о «правильном» API, стоит записать в CLAUDE.md проекта один раз, чтобы не повторять в каждой задаче. Пример раздела:

## Claude API

- Используем @anthropic-ai/sdk, модель `claude-opus-5` (алиас без даты).
- Рассуждение: `thinking: { type: "adaptive" }`, глубина — `output_config.effort`.
  Никогда не использовать `budget_tokens`.
- Структурированный вывод: `client.messages.parse` + `zodOutputFormat`.
- Агентный цикл: `client.beta.messages.toolRunner` с `betaZodTool`;
  ручной цикл только по явной просьбе.
- Версии встроенных инструментов и бета-заголовки брать из docs.claude.com,
  не по памяти. Перед использованием нового параметра — прочитать документацию.
- Ключ только из `ANTHROPIC_API_KEY`; никаких вызовов API из браузера.
- В историю сообщений всегда добавлять `response.content` целиком.

Это те же правила, что в уроках про режим рассуждения, вызов инструментов и контекст, только в форме, которую Claude Code прочитает при каждом запуске. Как устроен CLAUDE.md — в уроке курса по Claude Code.

Рабочий процесс

Процесс тот же, что для любой задачи в Claude Code: исследовать, спланировать, написать, проверить. Для интеграций с API есть особенности на каждом шаге.

Исследовать. Попросите Claude Code сначала прочитать документацию и существующий код, не трогая файлы. Хороший первый промпт: «Прочитай документацию по MCP-коннектору и наш src/portal/, потом расскажи, как ты подключишь сервер трекера, но пока ничего не пиши».

Спланировать. Потребуйте план с перечислением параметров API, которые он собирается использовать: имена типов инструментов, бета-заголовки, поля запроса. Этот список легко сверить с документацией до того, как написана хоть одна строка. Если в плане есть budget_tokens или модель с датой в идентификаторе — исправляйте на этом этапе.

Написать. Дайте написать код и тесты. Для тестов SDK удобно подменять: попросите вынести клиент в зависимость, чтобы тест подставлял заглушку с заранее известным ответом. Отдельно — один интеграционный тест на настоящем ключе с минимальным запросом (max_tokens: 16), который запускается вручную или в отдельном CI-шаге.

Проверить. Здесь важнее всего не доверять тому, что «тесты зелёные». Заглушка не заметит неправильного имени параметра. Запустите интеграционный тест, посмотрите на usage и stop_reason в ответе, откройте консоль на platform.claude.com и убедитесь, что запрос там виден с ожидаемой моделью.

Чек-лист ревью кода от Claude Code

Перед тем как влить интеграцию, пройдитесь по списку. Он собран из ошибок, которые модель делает чаще всего.

• Идентификатор модели — из документации, без выдуманной даты.
• Рассуждение — adaptive, никакого budget_tokens на Opus 5, Sonnet 5 и Fable.
• Типы встроенных инструментов с актуальной датой версии; code_execution не смешан с веб-инструментами _20260209.
• Бета-функции (компакция, очистка, MCP-коннектор, навыки, Managed Agents) вызываются через client.beta.messages с правильным заголовком.
• В агентном цикле response.content добавляется в историю целиком; все tool_result одного шага — одним сообщением; ошибки инструментов — через is_error.
• Есть ограничение на число итераций.
• stop_reason проверяется; pause_turn и refusal обработаны.
• Ключ не захардкожен, нет вызовов API из клиентского кода.
• Команды и пути из tool_use не выполняются без проверки.
• В usage пишутся логи, кэширование проверено по cache_read_input_tokens.

Многие пункты можно закрыть тестами, и Claude Code напишет их, если попросить: «добавь тест, который падает, если в коде встречается budget_tokens».

Что Claude Code делает хорошо

Не стоит воспринимать урок как список опасений. В разработке интеграций Claude Code реально экономит время там, где работа рутинная: обвязка вокруг SDK, обработка ошибок по классам, типизация ответов, тесты с заглушками, миграция существующего кода на новую модель (для этого достаточно дать ему страницу с руководством по миграции). Он хорошо разбирает большой JSON ответа и пишет диспетчеры инструментов. И он отлично объясняет чужой код: «расскажи, что делает этот цикл и где он может зависнуть» — быстрый способ провести ревью интеграции, которую писал не вы.

Главное — помнить, кто отвечает за результат. Claude Code написал, вы проверили по документации и на настоящем ключе, потом влили.