14 инженерных правил для Claude Code: опыт работы с агентом на $31 000

Автономные кодинг-агенты обещают революцию в разработке: разработчик формулирует задачу на естественном языке, а модель сама исследует репозиторий, меняет файлы и собирает проект. Однако реальная коммерческая эксплуатация быстро сталкивается с суровой реальностью. Ник Сараев провел более 1000 часов практических экспериментов с фронтирными моделями Claude Opus 5.5 и GPT-6 Astra, потратив на токены суммарно свыше $31 141. Итогом этой интенсивной работы стал свод из четырнадцати строгих инженерных принципов, отделяющих надежную разработку от бесконечной борьбы со сбоями.

Главная иллюзия начинающих инженеров — восприятие большой языковой модели как детерминированной программы. На практике модель остается статистической системой. Первый удачный ответ при разовом промпте часто оказывается случайным статистическим выбросом. Если не выстроить жесткий инженерный контур с регулярными проверками, агент быстро превратит стройную кодовую базу в клубок противоречивых правок.

Иллюзия первого вывода и статистические проверки

Первое базовое правило требует отказаться от слепого доверия первому сгенерированному результату. Если промпт сработал один раз, это не гарантирует его надежность в продакшне. Для критических инструкций необходим запуск повторяющихся промпт-эвалов: серия из минимум десяти прогонов на одинаковом контексте позволяет оценить реальную вероятность успеха (например, 7 успешных решений из 10 против 9 из 10 при уточнении требований).

Второе правило напрямую связано с первым: агенту необходимо предоставить строгие инструменты автономной самопроверки. Модель склонна уверенно заявлять об исправлении бага, даже если код перестал компилироваться. Единственный надежный предохранитель — запуск юнит-тестов, интеграционных тестов и линтеров перед фиксацией изменений. Если тесты падают, агент обязан продолжить цикл исправления без вмешательства человека.

Третий принцип формулируется просто: код — это лучший контекст. Разработчики часто пытаются компенсировать непонимание архитектуры длинными текстовыми пояснениями в промпте. Это неэффективно и быстро заполняет контекстную память. Гораздо надежнее опираться на строгую типизацию (TypeScript, интерфейсы, схемы валидации Pydantic в Python) и прозрачную структуру директорий. Явно объявленные типы данных передают модели правила проекта надежнее любых словесных инструкций.

Четвертое правило использует технику мета-промптинга. Инженеру не обязательно вручную формулировать идеальные системные промпты до последней запятой. Достаточно описать черновой замысел задачи и попросить саму модель структурировать детальные инструкции, ограничения и граничные случаи. Claude отлично понимает собственную механику внимания и формулирует системные требования эффективнее человека.

Гигиена контекстного окна и автономность правок

Пятое правило касается управления контекстным окном (Context Window). Контекст модели — это ограниченный и дорогой ресурс. Когда в диалог попадают портянки сырых логов сборки, километровые дампы stack trace или минифицированные бандлы, ключевые системные правила вытесняются на периферию внимания (эффект «растворения внимания» в середине длинного контекста). Логи необходимо фильтровать, передавая агенту только лаконичные выжимки ошибок.

Шестое правило рекомендует ослаблять микроменеджмент и переходить в режим автономии (autonomy mode). Пошаговое подтверждение каждой команды терминала человеком разрушает продуктивность. Агенту следует разрешать выполнять серию последовательных изменений самостоятельно, но при одном категорическом условии: в конце цепочки действий всегда запускается автоматический прогон тестов.

Седьмое правило требует обязательной диагностики до начала любых модификаций файлов. Когда модель сразу бросается писать код, она часто «лечит симптомы», ломая соседние модули. Инженерная норма — заставить агента сначала исследовать кодовую базу исключительно в режиме чтения, локализовать первопричину проблемы, сформировать план и лишь затем переходить к редактированию.

Восьмой принцип — интеграция внешних источников через протокол Model Context Protocol (MCP). Стандарт MCP позволяет подключать к терминальному агенту специализированные серверы с доступом к корпоративным базам данных, логам окружения или актуальной технической документации. Это избавляет модель от необходимости гадать о структуре таблиц или актуальных сигнатурах сторонних библиотек.

Изоляция сессий и параллельная оркестрация

Девятое правило предписывает изолировать независимые задачи. Попытка поручить одной сессии одновременный рефакторинг авторизации, верстку новой страницы и настройку платежного шлюза гарантированно приведет к деградации рассуждений. Каждая крупная задача должна решаться в изолированном контексте.

Десятое правило вводит механизм передаточных записок (handoff notes). При длительной работе контекстное окно неизбежно засоряется историей промежуточных попыток. Вместо того чтобы продолжать тяжелую сессию, агент генерирует компактную сводку текущего состояния (что сделано, какие файлы затронуты, что осталось сделать), после чего сессия завершается, а чистая сессия стартует с готовой передаточной запиской.

Одиннадцатое правило опирается на команду /btw. При работе в терминале у инженера регулярно возникают побочные вопросы («почему здесь выбран этот тип?», «какой порт слушает сервис?»). Если задать такой вопрос в основной диалог, он осядет в контексте навсегда. Команда /btw позволяет запустить изолированное ветвление диалога, получить ответ и вернуться в чистую рабочую сессию.

Двенадцатый принцип описывает продвинутую архитектуру fan-out / fan-in. Для реализации масштабной фичи центральный агент-координатор разбивает задачу на независимые подзадачи, запускает параллельных субагентов в изолированных деревьях Git (git worktree), а после завершения их работы собирает результаты воедино и проводит финальное интеграционное тестирование.

Настройка проекта через CLAUDE.md и база знаний

Тринадцатое правило фиксирует проектные соглашения в файле CLAUDE.md. Этот файл размещается в корне репозитория и автоматически считывается агентом при каждой инициализации сессии. В нем прописываются команды сборки, линтинга, стандарты именования и строгие запреты (например, табу на прямое редактирование миграций базы данных).

# Руководство проекта для Claude Code

## Стек и архитектура
- Язык: TypeScript (Node.js 22 LTS), фреймворк NestJS
- СУБД: PostgreSQL с Prisma ORM
- Тестирование: Vitest

## Обязательные правила разработки
1. Всегда запускай линтер и тесты перед завершением задачи: npm run lint && npm test
2. Запрещено модифицировать файлы в директории src/migrations/ напрямую без создания миграции Prisma
3. Не включай сырые логи сборки в вывод, используй лаконичную диагностику
4. Все изменения API должны сопровождаться обновлением Swagger-декораторов

Для передачи контекста между сессиями используется структурированный шаблон передаточной записки:

# Передаточная записка (Handoff Note) — Модуль биллинга

## Контекст задачи
- Цель: внедрение подписки на базе Stripe Webhooks
- Текущий статус: контроллер эндпоинта создан, валидация сигнатуры реализована

## Измененные файлы
- src/billing/stripe.controller.ts: добавлен обработчик POST /webhooks/stripe
- src/billing/stripe.service.ts: реализована обработка события customer.subscription.created

## Следующие шаги для новой сессии
1. Написать юнит-тесты на проверку поддельной подписи в stripe.controller.spec.ts
2. Проверить миграцию схемы пользователя в prisma/schema.prisma
3. Запустить тестовый прогон: npm test -- src/billing

Четырнадцатое правило замыкает цикл: обучение на ошибках. Каждый исправленный нетривиальный баг или архитектурный тупик фиксируется в локальной базе знаний или добавляется как ограничение в CLAUDE.md. Это гарантирует, что агент не наступит на те же грабли через неделю.

Для начала работы с агентом и организации правильного рабочего цикла используются стандартные консольные команды:

# Установка глобального пакета Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Авторизация в учетной записи
claude auth login

# Запуск первичной диагностики репозитория без изменения файлов
claude -p "Проанализируй архитектуру src/billing и составь перечень потенциальных рисков"