Агент сломал работавшее: 7 шагов разбора от симптома до отчёта

Что такое Claude Code и зачем он нужен?

Репозиторий Anthropic описывает Claude Code так:

Запуск начинается из каталога проекта:

claude

Для новичка это полезно в момент, когда проект уже существует, но его устройство непонятно. Агент может пройти по файлам, сопоставить документацию с кодом и помочь восстановить последовательность событий. Команды Anthropic применяют Claude Code для совместного размышления и генерации кода.

Security Engineering передаёт ему stack trace и документацию и просит проследить control flow через кодовую базу. Ручной поиск, который занимал 10-15 минут, в описанном примере стал занимать примерно 5 минут. Такой темп нельзя обещать для любого проекта. Скорость зависит от того, какие файлы доступны и насколько точный вопрос задан.

Актуальный релиз на 10 августа 2026 года - 2.1.227. Я не сверяюсь с номером версии при разборе ошибки: он не объясняет, почему агент ошибся в конкретном случае. Для расследования важнее другое: что он прочитал, какие выводы сделал и чем подтверждён результат.

Как Claude Code работает с проектом?

При использовании claude code я держусь рабочей схемы Anthropic:

1. Исследовать кодовую базу.
2. Составить план.
3. Внести изменения.
4. Проверить результат.

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

Потом я прошу составить план. claude code plans нужны ради ясного списка действий: они показывают, какую причину агент считает вероятной и какие места собирается менять. Как и в Plan Mode, если план уходит в сторону, его проще остановить до правки, чем откатывать половину проекта.

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

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

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

Если хочешь собрать такую же цепочку на своём проекте и проверить её руками - приходи на практикум:

Что Claude Code может сделать при разборе инцидента?

При разборе инцидента агент может:

• восстановить хронологию по временным отметкам, логам и истории изменений;
• пройти по control flow от stack trace к участкам кода;
• сопоставить появление ошибки с известными изменениями;
• сформулировать несколько возможных причин;
• показать, какие данные подтверждают или опровергают каждую гипотезу;
• подготовить план исправления.

Я разделяю здесь две вещи. Агент может быстро построить рабочую версию объяснения. Версия объяснения становится фактом только после проверки данными.

Например, stack trace указывает путь, по которому ошибка дошла до пользователя. Он не доказывает, что первая строка в этом пути и есть причина. Причина могла появиться раньше, в данных, конфигурации или изменении, которое не попало в первый просмотр.

Поэтому после хронологии я прошу сформулировать несколько гипотез. Для каждой нужны:

• подтверждающие факты;
• факты против;
• проверка, которая различит гипотезы;
• ожидаемый результат этой проверки.

Так агент превращается из генератора ответа в помощника по расследованию. Он помогает сузить поиск. Решение о причине остаётся за наблюдаемыми данными.

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

Какие команды нужны для навигации и анализа проекта?

Запусти Claude Code из каталога проекта:

claude

Внутри сессии пригодятся:

/usage

Показывает сведения о лимитах плана.

/rewind

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

Ctrl-R

Ищет по истории сообщений.

Я бы держал эти действия в голове как три разные кнопки:

• /usage отвечает на вопрос о расходе и доступном лимите;
• /rewind нужен, когда изменения пошли не туда;
• Ctrl-R помогает найти прежнюю постановку или важный фрагмент разговора.

Я не добавляю сюда полный список команд. В фактуре для этой инструкции подтверждены именно эти возможности. Остальные команды навигации, анализа файлов и Git лучше сверять с официальным справочником Claude Code, потому что поведение и набор команд зависят от версии.

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

Как провести разбор инцидента по шагам?

1. Передай исходные факты.

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

   Контекст для расследованияСкопировать промпт

   Помоги расследовать инцидент в текущем проекте.
   
   Симптом:
   Ожидаемое поведение:
   Фактическое поведение:
   Время появления:
   Stack trace:
   Изменения перед инцидентом:
   
   Сначала изучи доступные файлы, документацию и историю изменений. Ничего не исправляй. Составь хронологию и перечисли факты, которые удалось подтвердить.

2. Попроси восстановить цепочку.

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

   Восстановление цепочкиСкопировать промпт

   Восстанови цепочку событий от известного изменения до наблюдаемого сбоя.
   
   Для каждого шага укажи:
   - факт и его источник;
   - файл или участок кода;
   - что произошло по времени;
   - что пока остаётся предположением.
   
   Не вноси изменения и не предлагай исправление на этом этапе.

3. Сформулируй несколько гипотез.

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

   ГипотезыСкопировать промпт

   На основе подтвержденной хронологии сформулируй несколько независимых гипотез причины.
   
   Для каждой гипотезы укажи:
   - что её подтверждает;
   - что ей противоречит;
   - какую проверку можно выполнить;
   - какой результат подтвердит или опровергнет гипотезу.
   
   Не называй гипотезу доказанной без результата проверки.

4. Проверь гипотезы наблюдаемыми данными.

   Используй логи, тест или воспроизведение сбоя. Если проверки нет, зафиксируй это как пробел, а уверенное объяснение не используй вместо неё.

   На этом месте я останавливаю агента, если он сразу переходит к коду. Сначала нужна проверка. Красивый рассказ о причине не заменяет лог, тест или повторяемый сбой.

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

5. Запроси ограниченное исправление.

   После проверки попроси изменить только участки, связанные с подтверждённой причиной. В запросе укажи границы и запрет на несвязанные переписывания.

   Исправление подтвержденной причиныСкопировать промпт

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

6. Повтори исходную проверку.

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

7. Запиши результат в отчёт.

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

   markdown

   Скопировать

   ## Ожидаемое поведение
   
   ## Фактическое поведение
   
   ## Хронология
   - Время:
   - Событие:
   - Источник факта:
   
   ## Права и границы
   - Ожидалось:
   - Фактически было:
   
   ## Действие, вызвавшее ущерб
   
   ## Ущерб
   
   ## Непосредственная причина
   
   ## Системная причина
   
   ## Почему проверки не остановили действие
   
   ## Блокировка повторения
   
   ## Как доказано, что блокировка работает

Эта последовательность не делает агента самостоятельным расследователем. Она не даёт ему права считать предположение фактом. Она просто ставит контрольные точки там, где новичок чаще всего теряет нить: перед исправлением, после исправления и при записи результата.

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

Как проверить исправление и не принять ошибку за решение?

Anthropic формулирует критерий так:

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

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

Ответ «ошибка больше не возникает» без вывода проверки слабее самого вывода команды или результата теста. Я не принимаю слово «проверено» вместо доказательства.

Периодически корректируй Claude Code во время работы. Anthropic описывает схему исследования, плана, изменений и проверки, а также советует не оставлять длинную автономную сессию без контроля. Если после более двух попыток исправления проблема остаётся, очисти сессию и сформулируй задачу заново. Накопившиеся неудачные попытки ухудшают контекст.

Не используй полное отключение подтверждений как обычный способ ускорить работу:

Этот режим не заменяет ручную проверку критичной инфраструктуры. Автономность не отменяет контроль границ, логов и фактического результата.

Что ломается, когда границы проекта кажутся безопасными?

Это не теоретическое предупреждение. В 141 006 кибербезопасностных прогонах обнаружили три инцидента из-за фактически открытого интернета в среде, которую считали изолированной. Надпись или инструкция «среда закрыта» не доказывает, что сеть закрыта.

Есть и более близкие к рабочему проекту случаи.

Текстовое правило равно инструкции, а не техническому запрету. В одном отчёте правило в CLAUDE.md должно было не допустить публикацию API-ключей. Claude Code записал реальные ключи в конфигурацию и отправил их в публичный GitHub-репозиторий. GitGuardian обнаружил три секрета уже после коммита. Ключи пришлось отзывать и перевыпускать.

deny нужно проверять руками. Пользователь сообщил, что протестированные правила deny в settings.json не блокировали доступ к заявленным файлам и инструментам. Практический вывод простой: не считай запрет рабочим, пока не проверил его на безопасном тестовом файле.

Секрет может попасть в транскрипт через обычную команду. В описанном случае grep -n вывел содержимое .env вместе с настоящим токеном. Результат инструмента попал в разговор и историю. Инструкция в CLAUDE.md не предотвращает сам вызов команды.

Не читай секретные файлы через cat, Read, grep -n, head или tail. Если требуется проверить наличие настройки, используй действие, которое возвращает только факт наличия, количество строк или имена ключей, без значений.

Хуки тоже не абсолютная граница. Они появились в версии 1.0.38 и могут реагировать на события Claude Code, проверять команды и блокировать опасные действия. Но практический отчёт о 545+ задачах указывает на слабые места: hook способен молча завершиться с ошибкой, не охватить subagents, быть изменён моделью или обойтись через Bash, MCP и другой путь выполнения.

Соберу эти случаи в таблицу, чтобы было видно разом:

Для каждого инцидента с границами я заполняю такую структуру:

1. Зафиксируй ожидание. Какая среда, инструкция, настройка или правило считались защитой?
2. Опиши фактическое поведение. Что реально прочитал агент, какую команду выполнил и куда попал результат?
3. Раздели права и действие. Какие права были заявлены, какие оказались доступными, какое действие вызвало ущерб?
4. Посчитай ущерб. Какие данные раскрыты, какие изменения внесены, сколько времени ушло на восстановление?
5. Найди причину. Правило не загрузилось, не сработало, не охватило путь или агент не прочитал существующий файл?
6. Заблокируй повторение. Добавь независимую проверку и проведи безопасный тест, который доказывает её работу.

В отчёте также фиксируй расход и состояние сессии. Повторная передача контекста способна влиять на квоту. В одном пользовательском отчёте указаны 3,9 млн рабочих токенов и более 5 млрд cache read tokens. Рекурсивные subagents в другом случае потратили 1,2 млн токенов примерно за 30 минут, а в ещё одном лимит закончился менее чем за пять минут при расходе около 4 млн токенов.

Отдельно записывай расхождение индикаторов. CLI мог сообщать об исчерпанной квоте, пока панель аккаунта показывала 35% оставшегося пятиичасового лимита, а Desktop продолжал работать. Сообщение интерфейса тоже нужно проверять, а не принимать за окончательную причину.

Вопросы и ответы