Отладка с Codex: от симптома к подтверждённой причине

Быстрое изменение первой подозрительной строки часто маскирует дефект. Надёжная отладка строит причинную цепочку: воспроизведение → наблюдение → гипотеза → различающий…

Краткий ответ

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

Зафиксируйте симптом

До чтения десятков файлов запишите:

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

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

Постройте путь выполнения

Попросите Codex проследить данные от входа до места неверного состояния. Для HTTP-дефекта это может быть route → middleware → controller → service → database → mapper → client cache.

На каждом переходе ответьте:

какое значение вошло;
какая проверка выполнена;
какое состояние изменилось;
где ошибка преобразована;
может ли async-операция завершиться позже более нового запроса.

Трасса должна ссылаться на реальные файлы и символы. Архитектурная схема по названиям каталогов — только гипотеза.

Формулируйте конкурирующие гипотезы

Вместо «это кеш» составьте таблицу:

Гипотеза Подтверждающий сигнал Опровергающий эксперимент

stale response старый request завершается последним изменить порядок deferred promises

неверный auth state store считает гостя user зафиксировать состояние перед render

CSS overlay DOM корректен, элемент скрыт проверить layout и computed styles

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

Минимальная инструментализация

Добавляйте лог или assertion рядом с границей, где расходятся ожидаемое и фактическое состояния. Не печатайте токены, cookies, полные персональные объекты и тела секретных запросов.

После диагностики удалите временный шум либо превратите полезный сигнал в структурированную наблюдаемость. Отладочный console.log не должен случайно попасть в production.

Исправляйте инвариант, а не пример

Если старый async-ответ перезаписывает новый, инвариант звучит: «состояние может менять только актуальный request текущей сессии». Исправление через request id или отмену операции отражает правило. Проверка «добавить 200 ms delay» привязана к одному расписанию.

Регрессионный тест должен управлять порядком:

1. начать гостевой запрос;
2. выполнить вход и начать авторизованный запрос;
3. завершить авторизованный запрос;
4. последним завершить старый гостевой;
5. убедиться, что персональное состояние не перезаписано.

Если проблема в среде Codex

Сначала проверьте, не ожидается ли approval, правильны ли рабочая директория и ветка, выполняется ли базовая команда вроде git status. Возможности могут появляться в CLI и desktop app в разное время из-за разных версий. Перед отчётом о баге соберите версию и очистите логи от чувствительных данных.

Практика: журнал гипотез

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

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

Частые вопросы

Можно ли сразу попросить Codex исправить stack trace?

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

Что делать с невоспроизводимым багом?

Улучшить наблюдаемость и сузить различия окружения. Не вносить случайные задержки или catch-all без доказательства: они уменьшают видимость и усложняют следующую диагностику.

Сколько гипотез достаточно?

Столько, чтобы не принять первое правдоподобное объяснение за факт. Обычно две-три причины, различаемые дешёвыми экспериментами, дают хороший баланс.

Что важно запомнить

Отладка начинается с воспроизводимого симптома, а не с правки.
Стройте реальный путь данных и несколько конкурирующих гипотез.
Эксперимент должен различать причины.
Исправляйте системный инвариант и доказывайте его регрессионным тестом.

https://yadro-code.ru/lessons/without-university/codex-agent-workflows/codex-agent-15