Отладка: логи, стек-трейсы, гипотезы

В уроке про баги у нас был понятный сценарий: есть шаги воспроизведения, агент чинит и закрепляет тестом. Здесь — случаи потруднее: «иногда падает», «на проде 500, локально всё работает», «приложение тормозит после релиза». Причина неизвестна, и главный риск — что агент найдёт правдоподобное объяснение, починит его и отчитается, а настоящая причина останется. Разберём, как построить отладку так, чтобы агент сначала искал, а потом правил.

Сырые данные вместо пересказа

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

Лог можно отдать прямо через пайп. В codex exec всё, что пришло в stdin вместе с промптом, становится контекстом, а по умолчанию команда работает в режиме только для чтения:

tail -n 300 storage/logs/system.log | codex exec "Найди первую ошибку в этом логе OctoberCMS, объясни цепочку вызовов и назови файл и строку в нашем коде, откуда она пошла. Ничего не меняй."

В интерактивной сессии удобнее !: строка !tail -n 100 storage/logs/laravel.log выполнит команду с текущими настройками песочницы, и её вывод окажется в разговоре. Для мобильных проектов то же самое делается с выводом adb logcat или консолью Xcode: сохраните фрагмент в файл и упомяните его через @.

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

Гипотезы до правок

Когда причина неясна, запретите агенту править код на первом шаге. Пусть сначала думает вслух и проверяет. Хорошо работает режим планирования (/plan) или запуск в режиме только для чтения:

codex --sandbox read-only

Промпт для этой фазы:

Симптом: форма заявки иногда отдаёт 500, примерно в одном случае из десяти.
Стек-трейс и лог — в @tmp/error-2026-10-21.txt.

Не меняй код. Выдвини 3–4 гипотезы о причине, отсортируй по вероятности.
Для каждой: какие факты из лога за неё и против, и как проверить её
без изменения кода — какую команду запустить, какой файл прочитать,
какой запрос отправить. Потом проверь две самые вероятные и доложи результат.

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

Когда гипотеза подтвердилась, переходите к починке по схеме из урока про баги: воспроизвести, починить, закрепить тестом.

Временное логирование

Иногда фактов не хватает, и нужно добавить диагностику. Агент умеет это делать быстро, но такие правки любят оставаться в коде. Договоритесь о правилах заранее, лучше прямо в AGENTS.md:

## Отладка
- Временные логи помечай комментарием `// DEBUG-TMP` и удаляй их до коммита.
- Не логируй персональные данные заявок (телефон, email) даже временно.
- Перед тем как сказать «готово», выполни `git grep -n "DEBUG-TMP"` — результат должен быть пустым.

Пусть агент сам смотрит на систему

Отладка идёт быстрее, когда агент не ждёт, пока вы принесёте очередной кусок лога.

• Терминал. В ChatGPT desktop у каждого чата есть встроенный терминал, привязанный к проекту или worktree, и Codex может читать его текущий вывод: упавшую сборку или ошибки dev-сервера.
• Браузер. Там же встроенный браузер в режиме разработчика даёт агенту доступ к Chrome DevTools Protocol: консоль, сетевые запросы, DOM и стили, трассировка производительности. Этот доступ включается в настройках и требует отдельного одобрения на каждый сайт. Пример запроса из документации — попросить через @Browser снять трассировку и найти узкое место. В CLI похожие возможности дают MCP-серверы Chrome DevTools и Playwright.
• Ошибки с прода. Если в проекте есть Sentry, его MCP-сервер позволит агенту самому найти событие, стек и частоту, а не работать по вашему скриншоту. Подключение — в уроке MCP на практике.

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

В OpenAI в эксперименте с разработкой без ручного кода пошли дальше: на каждый worktree поднимали своё приложение и временный стек логов, метрик и трейсов, чтобы Codex сам воспроизводил баги и проверял исправления (статья о harness engineering). Как строить такую среду, разбираем в уроке Наблюдаемость для агента.

Побочные вопросы и альтернативные версии

Отладка порождает много мелких вопросов: «что делает этот флаг nginx», «почему в PHP 8.3 этот вызов deprecated». Задавать их в основной сессии — значит засорять контекст расследования. Для этого есть /side (он же /btw): временный побочный чат, который не мешает основному.

Если хочется проверить совсем другую версию, не ломая текущую линию рассуждений, сделайте ответвление через /fork. Если агент ушёл не туда два сообщения назад, нажмите Esc дважды на пустом поле ввода: Codex предложит отредактировать прошлое сообщение и ответвится от него. Учтите, что это ветка разговора: не рассчитывайте, что так откатятся файлы на диске. Код откатывайте через git (см. Git как страховка).

Когда агента пора остановить

Признаки, что агент чинит симптом, а не причину:

• оборачивает проблемное место в try/catch и молча глотает исключение;
• увеличивает таймауты, лимиты памяти или число повторов;
• добавляет проверку на null там, где значение не должно быть пустым по логике;
• отключает или помечает как пропущенный тест, который падает;
• в третий раз подряд пишет «теперь должно работать», ничего не запустив.

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