6 уровней защиты от багов в Claude Code — pipeline, после которого AI-код можно коммитить спокойно

6 уровней защиты от багов в Claude Code — pipeline, после которого AI-код можно коммитить спокойно

Claude Code Opus 4.6 генерирует код быстрее, чем ты успеваешь его прочитать. И в этом проблема.

Анализ 470 open-source репозиториев на Stack Overflow показал: AI создаёт в 1.7 раз больше багов, чем человек. На 75% больше логических ошибок, в 3 раза больше проблем с читаемостью, в 8 раз больше лишних I/O-операций. И чем дольше агент работает автономно — тем хуже: ошибки накапливаются и "запекаются" в код.

Но разработчик, который ведёт проект на 350K строк кода в одиночку, с 80%+ изменений от Claude Code, деплоит 28 раз в неделю — и не тонет в багах. Разница — не в модели, а в pipeline вокруг неё.

TL;DR: 6 уровней защиты — plan mode, TDD, hooks, subagent-ревью, checkpoints и управление контекстом — которые превращают Claude Code из генератора багов в надёжного напарника. Каждый уровень ловит свой класс ошибок, вместе они закрывают почти всё.

Уровень 1: Plan Mode — думай, потом кодь

Главная причина багов от AI — модель решает не ту задачу. Ты просишь "добавить OAuth", а Claude бросается писать код, не разобравшись в твоей архитектуре сессий. Результат — 200 строк, которые нужно переписать.

Официальная документация Claude Code рекомендует четырёхфазный подход:

Explore → заходишь в Plan Mode, Claude читает файлы и отвечает на вопросы, ничего не меняя:

read /src/auth and understand how we handle sessions.
also check how environment variables for secrets are managed.

Plan → просишь план, который можно отредактировать через Ctrl+G:

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

Implement → переключаешься в Normal Mode и работаешь по плану:

implement the OAuth flow from your plan.
write tests for the callback handler,
run the test suite and fix any failures.

Commit → коммит и PR.

Для сложных архитектурных решений добавляй think harder в промпт — это включает расширенное мышление с бюджетом ~32K токенов, и Claude реально глубже анализирует варианты, прежде чем предложить решение.

Что ловит: решение не той задачи, неучтённые зависимости, архитектурные промахи.

Уровень 2: TDD — тесты ДО кода, по одному

TDD с AI-агентом работает иначе, чем с человеком. Без явного принуждения Claude пишет реализацию первой, а тесты — потом. Это катастрофа, потому что тесты начинают тестировать реализацию, а не поведение. Если баг в реализации — тесты его пропустят.

Правильный цикл — vertical slicing:

RED → пишешь ровно ОДИН падающий тест:

Write a FAILING test for email validation.
Do NOT write implementation yet.

GREEN → минимальный код, чтобы тест прошёл. Ничего лишнего:

Write minimal code to pass this test only.
Nothing speculative.

REFACTOR → убираешь дублирование, не ломая тесты.

И так по кругу: один тест → одна реализация → рефакторинг → следующий тест.

Самый продвинутый подход — изоляция фаз через subagents. Три отдельных агента: tdd-test-writer, tdd-implementer и tdd-refactorer. Каждый работает в своём контексте, и test writer физически не может "подсмотреть" реализацию. Без изоляции активация TDD-дисциплины — ~20%, с hooks-принуждением — ~84%.

Быстрый старт — установить готовый TDD-скилл:

npx skills add mattpocock/skills/tdd

Что ловит: логические ошибки (те самые +75% из исследования), регрессии, тесты-заглушки, которые ничего не проверяют.

Уровень 3: Hooks — автоматические проверки после каждого действия

CLAUDE.md — рекомендация. Hooks — гарантия. Линтер в CLAUDE.md Claude может проигнорировать; hook выполнится всегда.

Настройка в .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix $CLAUDE_FILE_PATH && npx tsc --noEmit",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Этот hook срабатывает после каждого редактирования файла: прогоняет ESLint с авто-фиксом и TypeScript type-check. Если type-check падает — Claude видит ошибку и исправляет до того, как пойдёт дальше.

Для pre-commit проверки:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --bail",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Если тесты падают — коммит блокируется. Claude получает вывод тестов и чинит код до повторной попытки.

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

Уровень 4: Subagent Code Review — 9 рецензентов за 30 секунд

Главная проблема код-ревью AI-кода — огромные диффы. AI генерирует большие коммиты, и серьёзные логические ошибки тонут в массе изменений. Человеку сложно ревьюить 500-строчный дифф. Девяти параллельным агентам — нет.

Подход с 9 subagents запускает параллельные проверки, каждая со своим фокусом:

• Test Runner — прогоняет тесты, репортит падения
• Linter & Static Analysis — линтер + IDE-диагностика типов
• Code Reviewer — до 5 улучшений, ранжированных по impact/effort
• Security Reviewer — инъекции, auth-проблемы, секреты в коде
• Quality & Style — сложность, дублирование, соответствие стилю проекта
• Test Quality — покрытие, поведенческие тесты, flaky-риски
• Performance — N+1 запросы, блокирующие операции, утечки памяти
• Dependency Safety — breaking changes, совместимость зависимостей
• Simplification — можно ли сделать проще и атомарнее

Каждый агент работает в своём контексте — свежем, без привязки к процессу написания кода. Это критично: Claude не предвзят к коду, который сам только что написал.

Результаты агрегируются по severity: Critical/High — чинить обязательно, Medium — стоит поправить, Low — по желанию. Финальный вердикт: Ready to Merge, Needs Attention или Needs Work. По оценке автора, ~75% замечаний полезны, а Critical/High — "почти всегда".

Ещё проще — паттерн Writer/Reviewer из документации: одна сессия Claude пишет код, вторая — ревьюит в чистом контексте.

Что ловит: логические ошибки в больших диффах, security-проблемы, performance-регрессии, нарушения архитектуры.

Уровень 5: Checkpoints + Git — откат за секунды

Claude Code автоматически создаёт checkpoint перед каждым редактированием файла. Каждый промпт — новая точка сохранения. Esc + Esc или /rewind — и ты видишь все точки, на которые можно откатиться.

Варианты отката:

• Restore code and conversation — полный откат
• Restore code — файлы назад, но Claude помнит, что делал (полезно для "попробуй иначе")
• Restore conversation — контекст назад, файлы на месте
• Summarize from here — сжать хвост разговора, не трогая код

Правильная стратегия — checkpoints для экспериментов, git для истории. Пока Claude работает — checkpoints защищают. Когда кусок готов и проверен — git commit. Следующий кусок — снова под защитой checkpoints.

Оптимальная частота коммитов — каждая атомарная единица работы. На практике это ~50 коммитов в неделю вместо 25-30 — чаще, но мельче. Каждый коммит — точка, на которую можно вернуться без потерь.

Что ловит: любые ошибки, которые прошли предыдущие уровни — можно откатить и попробовать иначе.

Уровень 6: Контекст — не дай модели забыть

Исследование Stack Overflow прямо говорит: ошибки AI накапливаются по мере работы. Чем длиннее сессия — тем больше контекст заполнен мусором, и модель начинает "забывать" ранние инструкции.

Противоядие — агрессивное управление контекстом:

/clear между задачами. Закончил фичу — /clear — начинай следующую с чистого листа. Не "а ещё поправь вот это" в конце сессии про OAuth.

.claudeignore для тяжёлых файлов. Один package-lock.json — это 30-80K токенов. bundle.js — ещё 100K. Хорошо настроенный .claudeignore экономит до 50% контекста.

Модуляризация кода. Файл на 2000 строк заставляет Claude держать всё в памяти. Разбиение на 5 модулей по 400 строк снижает "контекстный шум" на 40% — и ответы становятся точнее.

Задачи в рамках контекстного окна. Принцип из production-воркфлоу: каждая задача должна уместиться в контекстное окно целиком. Если не умещается — декомпозируй на подзадачи. Автор проекта на 350K строк использует два режима: /workflows:fast для мелочей и /workflows:full с подзадачами D-1, D-2, D-3 для крупных фич.

Вложенные CLAUDE.md. Корневой файл — общие правила. В каждом модуле — свой CLAUDE.md с контекстом, который подгружается автоматически, когда Claude работает с файлами этой директории.

Что ловит: деградацию качества на длинных сессиях, "забывание" инструкций, засорение контекста нерелевантными файлами.

Подводные камни

Checkpoints не трекают bash-команды. Если Claude выполнил rm, mv или cp через Bash — эти изменения не откатишь через /rewind. Только git поможет, если файлы были закоммичены.

TDD требует явного принуждения. Без специальных инструкций Claude пишет реализацию первой, потом тесты — и часто переписывает тесты, чтобы они проходили, вместо того чтобы чинить код. Одного CLAUDE.md правила мало — нужен скилл или subagent-изоляция фаз.

Hooks-принуждение меняет всё. Эксперимент с Vue-проектом показал: без hooks TDD-скилл активируется в ~20% случаев, с UserPromptSubmit hook — в ~84%. Скилл сам по себе не гарантирует, что Claude его применит.

Subagent-ревью не заменяет человека на 100%. ~75% замечаний полезны — по оценке автора подхода. Medium/Low-замечания иногда пропускают специфику проекта, которую агент не знает. Critical/High — почти всегда в точку.

.claudeignore не работает ретроактивно. Если Claude уже прочитал файл в сессии — добавление его в .claudeignore не уберёт из контекста. Нужен /clear для перезагрузки.

Вердикт

Из шести уровней три дают основной эффект: TDD, hooks и subagent-ревью. TDD ловит логические ошибки на этапе написания. Hooks не дают коммитить сломанный код. Subagent-ревью находит то, что пропустили первые два. Вместе они адресуют ту самую проблему ×1.7 из исследования Stack Overflow.

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

Разработчик с проектом на 350K строк показывает, что pipeline работает: 80%+ кода от Claude, 2.4× рост выработки, 28 деплоев в неделю. При этом кодовая база здоровая — потому что каждый уровень ловит свой класс ошибок.

Как попробовать

1. Установи TDD-скилл: npx skills add mattpocock/skills/tdd — и в начале задачи пиши "Let's use TDD for this feature"

2. Добавь PostToolUse hook в .claude/settings.json — чтобы линтер и type-check запускались после каждого редактирования:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "npx eslint --fix $CLAUDE_FILE_PATH && npx tsc --noEmit", "timeout": 30 }]
    }]
  }
}

3. Создай команду /code-review в .claude/commands/ с 9 параллельными subagents по шаблону от hamy.xyz

4. Настрой .claudeignore — исключи lock-файлы, бандлы, node_modules, .git

5. Используй plan mode для любой задачи крупнее одного файла — Ctrl+G для редактирования плана перед началом кодинга