Отладка с 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 без доказательства: они уменьшают видимость и усложняют следующую диагностику.
Сколько гипотез достаточно?
Столько, чтобы не принять первое правдоподобное объяснение за факт. Обычно две-три причины, различаемые дешёвыми экспериментами, дают хороший баланс.