Ошибки Claude Code в продакшене: 12 ловушек и правки

С чем обычно ломается работа с Claude Code в продакшене

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

Часто это видно по симптомам, даже если код компилируется.

Симптомы, что генерация вышла из-под контроля

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

В таких PR обычно всплывает одно и то же:

• Изменения сразу в нескольких слоях (UI, бизнес-логика, база) без явной причины.
• Линтер и форматирование игнорируются, стиль кода «плавает».
• Появляются новые зависимости или утилиты, о которых команда не договаривалась.
• Нет тестов на новый сценарий, а старые начинают падать «без причины».

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

Где модель реально помогает, а где нужен строгий контроль

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

Строгий контроль нужен там, где легко ошибиться без контекста: миграции базы, авторизация и права, платежи, кэширование, конкурентный доступ, интеграции с внешними сервисами.

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

Минимальный процесс перед тем, как просить модель писать код

Большая часть проблем начинается не с модели, а с постановки задачи. Если потратить 5-10 минут до генерации, можно сэкономить часы на откатах, спорных PR и неожиданных побочных эффектах.

1) Сначала задайте границы, потом просите код

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

Минимальный процесс:

• Назвать точку входа: какой endpoint или экран меняем, какой модуль трогаем.
• Уточнить, что не трогаем: соседние сервисы, миграции, конфиги, UI.
• Зафиксировать критерии приемки: что должно работать и как это проверить.
• Задать ограничения: стиль, архитектура, совместимость, запрет новых зависимостей.
• Определить источник правды: спека, тесты, линтер (и что важнее при конфликте).

2) Критерии приемки и ограничения: формулируйте до генерации

Критерии приемки должны быть проверяемыми, а не вкусовыми. «Endpoint возвращает 400 при пустом поле» лучше, чем «сделай красиво».

Примеры нормальных критериев:

• Новый endpoint отвечает 200 и возвращает конкретные поля.
• Ошибки валидируются и дают 400 с понятным сообщением.
• Старые сценарии не ломаются (перечислите 1-2 ключевых).
• Добавлены тесты на успех и на ошибку.
• Линтер проходит без исключений.

Ограничения стоит писать прямо в запросе: «не добавляй новые библиотеки», «сохрани текущую архитектуру», «код должен быть совместим с текущей версией языка и фреймворка». Если в проекте принят форматтер или линтер, добавьте: «не расползайся форматированием по файлу, меняй только нужные строки».

Отдельно договоритесь об источнике правды. Если у вас есть спека, но тесты уже описывают реальное поведение, решите заранее, что именно корректируем: спеки, тесты или реализацию. Тогда модель не будет «угадывать», а вы сможете быстро принять или отклонить результат.

Пример: вместо «добавь поле phone» лучше писать так: «в модуле пользователей, в endpoint POST /users добавить поле phone, валидировать по маске, без новых зависимостей, обновить тесты, линтер должен пройти, не менять другие endpoints». Это снижает шанс получить лишний рефакторинг и делает результат проверяемым.

Ошибки 1-4: запросы без рамок и без проверяемого результата

Если рамок нет, модель будет додумывать за вас. Итог - лишние изменения, неожиданные зависимости и спорный результат.

Ошибка 1: слишком широкий запрос

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

Хороший признак: вы можете назвать файл(ы), где ожидаете правку, и коротко описать эффект. Например: «В форме логина показывать понятную ошибку при неверном пароле, менять только компонент LoginForm и обработчик запроса».

Ошибка 2: нет ограничений

Если не запретить лишнее, модель может добавить новую библиотеку, поменять структуру проекта или «улучшить» архитектуру. В продакшене это редко уместно.

Набор ограничений, который стоит писать почти всегда:

• Не добавляй новые зависимости и не меняй версии пакетов.
• Не меняй публичные API и контракты без явного запроса.
• Не переносить файлы и не переименовывать сущности.
• Не трогать форматирование вне изменяемых строк.
• Не делать рефакторинг, если он не нужен для задачи.

Ошибка 3: мало контекста

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

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

Ошибка 4: нет критериев приемки

Без критериев вы получите «похоже работает» вместо проверяемого результата. Запрос должен завершаться списком того, что считается успехом, включая крайние случаи.

Например для логина:

• При неверном пароле показываем одно сообщение без утечки деталей.
• При 500 от сервера показываем «Попробуйте позже».
• Кнопка блокируется на время запроса, повторный клик не отправляет второй запрос.
• После успеха сохраняем токен и переходим на нужный экран.
• Поведение одинаковое в двух браузерах или в веб и мобильном клиенте.

Такая рамка снижает количество сюрпризов в PR и делает результат удобным для проверки.

Как писать запросы с ограничениями: пошаговый шаблон

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

Шаг 1: сформулируйте проблему коротко и конкретно

Опишите текущую боль в 2-3 предложениях, без абстракций. Не «падает авторизация», а «после логина токен не сохраняется, на перезагрузке пользователь разлогинен». Добавьте один факт, который можно проверить: лог, скрин ошибки, точный endpoint.

Шаг 2: зафиксируйте ограничения до того, как просить код

Ограничения лучше давать списком, чтобы они не потерялись в тексте:

• Какие файлы можно менять (и какие нельзя).
• Какие API и версии использовать (например, конкретная версия React или Go).
• Запреты: не добавлять новые зависимости, не менять публичные интерфейсы.
• Границы задачи: только багфикс, без улучшений UI и без оптимизаций.
• Стиль: следовать существующим правилам линтера и форматирования.

После этого добавьте маленький пример контекста: фрагмент текущего кода или сигнатуры функций. Так меньше шанс получить «идеальный» вариант, который не встраивается в проект.

Шаг 3: задайте формат ответа

Если не задать формат, вы получите либо полотно текста, либо сразу код без плана. Удобный порядок такой:

1. План изменений на 5-8 пунктов
2. Патч (только измененные файлы)
3. Список рисков и что могло пойти не так

Шаг 4: требуйте самопроверку и критерии готовности

Попросите модель явно подтвердить, что она не трогала лишнее, и дать команды или шаги проверки.

Контекст: <2-3 предложения о проблеме + наблюдение/ошибка>
Цель: <что должно стать true после изменений>
Ограничения:
- Менять только: <файлы/модули>
- Не менять: <файлы/контракты>
- Без новых зависимостей
- Следовать линтеру/форматтеру проекта
Формат ответа:
1) План
2) Патч
3) Риски
Самопроверка:
- Что изменено и почему
- Что не тронуто
- Как проверить локально (шаги)

Такой шаблон полезен и в обычной разработке, и в vibe-coding среде вроде TakProsto, где скорость высокая, а цена лишнего диффа в продакшене особенно заметна.

Ошибки 5-8: качество кода, чистота диффа и управляемость изменений

Дальше все упирается в дисциплину изменений. В продакшене чаще горят не из-за «плохого кода», а из-за того, что дифф невозможно нормально проверить и откатить.

Ошибка 5: игнор линтера и форматтера

Модель может написать рабочее, но неровное: лишние импорты, разные стили, предупреждения компилятора, мелкие нарушения правил проекта. На ревью это превращается в спор про пробелы, а не про логику.

Правило простое: перед тем как показывать PR людям, прогоните автоформат и исправьте предупреждения. Если линтер ругается, ревьюер будет прав, даже если фича «уже работает».

Ошибки 6-8: смешанные цели, огромный дифф и забытые контракты

Ошибка 6 - смешивать рефакторинг и фичу. Когда в одном PR и новая кнопка, и переезд на новые утилиты, проверка становится лотереей. Разделяйте: один PR только «перестановка мебели» без изменения поведения, второй - только фича с минимальными касаниями.

Ошибка 7 - слишком большой дифф. Модель охотно «улучшит» соседние файлы, переименует сущности и заодно поменяет архитектуру. Дробите изменения по понятному принципу: по endpoint, по экрану, по слою (UI отдельно, API отдельно). Так легче тестировать и легче откатывать.

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

Как держать изменения управляемыми:

• В каждом PR одна цель: либо рефакторинг, либо фича.
• Дифф по возможности до уровня «можно прочитать за 10 минут».
• Перед пушем: форматтер, линтер, сборка (или компиляция), базовые тесты.
• Если меняете контракт: обновите типы и места использования.
• Делайте понятные коммиты: чтобы было видно, где правка логики, а где косметика.

Пример: вы добавляете поле phone в профиль. Практично сначала сделать отдельный PR с обновлением типов и контракта API (и миграцией, если нужна), а во втором - UI и обработку ошибок. Тогда ревьюер видит, что именно меняется, и не ищет смысл в стоге «попутных улучшений».

Ошибки 9-10: тестирование и ревью перед мерджем

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

Ошибка 9: нет тестов под изменение

Если изменения без тестов, вы проверяете не код, а удачу. Минимум, который почти всегда окупается: один позитивный и один негативный кейс. Например, добавили обработку промокода: позитивный тест проверяет корректную скидку, негативный - что неверный код дает понятную ошибку и не меняет сумму.

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

Ошибка 10: доверие без ручной проверки

Читать дифф нужно как чужой код, даже если вы сами писали промпт. Смотрите не только на новые строки, но и на побочные эффекты: изменения поведения по умолчанию, новые зависимости, обработку ошибок, логи.

Быстрый набор вопросов перед approve:

• Где может поменяться поведение без явного изменения интерфейса?
• Не стало ли больше точек отказа (таймауты, ретраи, паники)?
• Есть ли места, где данные могут быть потеряны или задвоены?
• Не появилась ли лишняя сложность ради «красоты»?

Чеклист перед мерджем: 10 минут, которые экономят дни

Если проблемы уже случались, почти всегда рядом была одна причина: код смержили без короткой, но честной проверки. «Идеальный процесс» не нужен. Нужны 10 минут дисциплины.

Минимум, который стоит прогнать локально

Начните с того, что проверяется быстро и однозначно. Если это не проходит, остальное обсуждать рано.

• Сборка проекта (или хотя бы затронутых пакетов) без предупреждений, которые вы не понимаете.
• Линтер и форматирование: исправьте замечания, а не «потом разберемся».
• Ключевые тесты: минимум те, что покрывают измененный код, плюс один-два быстрых смоук-теста.
• Запуск приложения в режиме, близком к обычному: откройте экран, дерните ручку, пройдите основной сценарий.
• Проверка конфигов: переменные окружения, флаги, значения по умолчанию.

После этого быстро посмотрите на дифф глазами человека, который будет разбираться с багом через неделю.

Быстрый просмотр диффа: что ищем

Не пытайтесь читать все строки подряд. Ищите «дорогие» изменения, которые могут сломать окружение или пользователей: появились ли новые зависимости, изменились ли публичные методы, добавились ли миграции. Если видите миграцию, убедитесь, что есть план отката и понятно, что будет с данными при частичном деплое.

Отдельно проверьте поведение в ошибках. Добавили новый запрос к внешнему сервису? Посмотрите, что будет при таймауте, 500-ке, пустом ответе. Есть ли понятные сообщения в логах, не утекут ли в них токены, пароли, персональные данные. Если добавили ретраи, убедитесь, что они ограничены и не создают лавину запросов.

Иногда полезно открыть PR как «мини-инцидент»: что будет, если эта фича начнет падать, и как быстро вы поймете причину.

Когда PR лучше остановить и переделать

Есть сигналы, что продолжать review бессмысленно. Не ругайте автора, просто фиксируйте факт и возвращайте в доработку.

• Слишком много файлов и разных тем в одном PR (фича + рефакторинг + форматирование).
• Нет понятного результата: что должно работать и как это проверить.
• Нет тестов там, где они ожидаются, и нет объяснения, почему.
• Дифф «шумный»: переименования, перестановки и правки стиля мешают увидеть смысл.
• Появились новые риски (зависимости, миграции, доступы), но они не описаны.

Если вы генерируете код в TakProsto, этот чеклист особенно полезен: модель быстро пишет много, а ваша задача перед мерджем - сделать изменения управляемыми и проверяемыми.

Пример из жизни: добавляем фичу и не превращаем PR в рулетку

Сценарий: в существующем сервисе нужно добавить маленькую фичу - кнопку «Повторить заказ» в личном кабинете. Кнопка должна создать новый заказ с теми же позициями и вернуть пользователя на страницу оформления. Звучит просто, но именно на таких задачах чаще всего появляется хаос: модель «улучшает» соседние части кода, меняет стили, трогает схему БД без просьбы и раздувает PR.

Запрос формулируйте так, будто вы пишете мини-ТЗ для коллеги. Нужны рамки и проверяемый результат.

Пример запроса, который обычно дает предсказуемый дифф:

• Цель: добавить кнопку «Повторить заказ» на странице заказов и endpoint, который создает копию заказа.
• Ограничения: не менять схему БД, не трогать дизайн-систему, не переименовывать функции и файлы без необходимости.
• Критерии приемки: кнопка видна только для завершенных заказов, копия заказа содержит те же позиции, покрыто тестами, линтер без ошибок.
• Файлы: перечислите 3-6 конкретных файлов, которые можно менять, и отдельно укажите, какие трогать нельзя.
• Формат ответа: «сначала план, затем патч по файлам, затем список проверок для запуска локально».

Дальше разбейте работу на 2-3 маленьких PR, чтобы каждый был понятным и откатываемым. Например: сначала только backend (endpoint и тесты), потом UI (кнопка и состояние загрузки), потом интеграция и аналитика, если она нужна. После каждого PR проверяйте одно и то же: дифф маленький, логика локальна, поведение можно быстро вернуть назад.

Ориентиры хорошего результата:

• Чистый дифф: изменения только там, где нужна фича, без массового форматирования и «попутных улучшений».
• Тесты: минимум один тест на создание копии и один на запрет для неподходящего статуса заказа.
• Понятный rollback-план: фича за флагом или легко отключаемая проверкой на конфиг, чтобы откат был не «вернуть весь релиз», а «выключить кнопку и endpoint».

Такой подход не делает работу медленнее. Он делает PR скучным. А скучный PR почти всегда безопаснее, чем «красивый» PR на тысячу строк.

Как встроить генерацию кода в командный процесс без хаоса

Генерация кода начинает помогать только тогда, когда у команды есть понятные границы ответственности. Иначе получается так: модель быстро пишет, а люди потом долго разбирают, что именно изменилось, почему и как это откатывать.

Роли и правила, которые снимают 80% проблем

Разделите ответственность заранее. Это особенно важно в продакшене.

• Автор задачи формулирует требования: что должно работать, какие ограничения, как проверить результат (сценарии, edge cases, критерии готовности).
• Исполнитель делает изменения (в том числе с помощью генерации), но отвечает за читаемый дифф и за то, чтобы код был проверяемым.
• Ревьюер отвечает за качество решения и риски: безопасность, совместимость, миграции, производительность, обратная совместимость.
• Релиз-ответственный принимает решение о выпуске: когда это можно катить и нужен ли откатный план.

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

Как фиксировать договоренности в задаче и PR

Вместо длинных обсуждений удобно держать два коротких шаблона.

В задаче: цель, нецели (что не трогаем), ограничения (версии, архитектура, зависимости), сценарии проверки. В PR: краткое описание подхода, список затронутых файлов, как протестировано, и заметка про риски (что может сломаться и как откатить).

Пример: нужно добавить фильтр в списке заказов. В задаче явно пишете: не менять схему БД, не трогать API контракт, фильтр должен работать по статусу и дате, проверка - 3 конкретных сценария. Моделью можно сгенерировать черновик UI и обработку параметров, но границы удерживают дифф маленьким и понятным.

Как мерить качество, а не спорить на ощущениях

Выберите 3-4 метрики и посмотрите динамику 2-3 спринта:

• Размер PR (количество файлов и строк) и доля правок не по теме.
• Время ревью: от открытия PR до мерджа, и сколько итераций правок.
• Откаты и хотфиксы после релиза: сколько и по каким причинам.
• Баги, найденные после релиза: особенно регрессии в соседних модулях.

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

Следующие шаги: закрепляем практики и выбираем удобный инструмент

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

Чтобы проблемы не повторялись, полезно превратить удачные подходы в стандарт команды. Самый простой путь - завести два артефакта: шаблон промпта и короткий чеклист приемки. Шаблон задает рамки (что менять, что не трогать, какие файлы можно править, какой результат ожидается). Чеклист заставляет делать одно и то же каждый раз, даже когда вы спешите.

Минимальный набор правил, который обычно дает быстрый эффект:

• Просьба к модели всегда включает границы: объем изменений, запреты, критерий готовности.
• Любой результат проходит те же проверки, что и обычный код: сборка, тесты, линтер, форматирование.
• Рефакторинг и новая фича не смешиваются в одном PR.
• Дифф должен быть маленьким и читаемым: лучше 2-3 понятных коммита, чем один огромный.

Дальше встает вопрос инструмента. Если вам нужен более управляемый поток разработки через чат, удобнее, когда платформа поддерживает процесс, а не только генерацию. В TakProsto (takprosto.ai) для этого есть planning mode, снапшоты и откат, а еще экспорт исходников, деплой и хостинг, если нужно быстро поднять стенд и проверить изменения.

И держите простое правило: результат модели - это обычный код. Он либо соответствует стандартам продакшена, либо не попадает в основную ветку.