Codex помогает искать ошибки, когда получает наблюдаемые факты: шаги воспроизведения, ожидаемый результат, реальный результат и ограничения проекта. Запрос «ничего не работает, исправь» вынуждает начинать с догадок. Чем лучше описан дефект, тем меньше риск получить косметическое изменение вместо устранения причины.
Хороший процесс состоит из нескольких этапов: воспроизвести, сузить область, проверить гипотезу, внести минимальное исправление и повторить сценарий. Его стоит сохранить даже тогда, когда предполагаемая причина кажется очевидной.
Подготовьте карточку ошибки
Где: страница настроек, тестовое окружение.
Шаги: включить уведомления, нажать «Сохранить»,
перезагрузить страницу.
Ожидается: переключатель остается включенным.
Фактически: появляется «Сохранено», затем значение сбрасывается.
Частота: повторяется после каждого обновления.
Последнее известное рабочее состояние: указать, если известно.
Ограничения: не менять другие настройки и формат API.
Данные: использовать тестовую учетную запись.Приложите безопасный фрагмент лога, код ответа сервера или скриншот. Уберите токены, cookies, пароли и клиентские данные. Для браузерной ошибки важны версия приложения и условия: роль пользователя, конкретный маршрут, последовательность действий. Само слово «иногда» лучше заменить описанием, когда именно сбой удалось увидеть.
Не выдавайте предположение за причину
«Наверное, кэш» — это гипотеза. «После сохранения сервер возвращает старое значение» — наблюдение. Их полезно записывать отдельно. Иначе агент может начать очищать кэш, хотя запрос вообще не дошел до обработчика или изменение не сохранилось в базе.
Попросите Codex сначала найти путь данных: действие пользователя, запрос, обработчик, запись и повторное чтение. На каждом шаге нужен факт. Для примера с настройкой можно проверить тело запроса, ответ сервера и значение после повторного чтения в тестовом окружении.
Проверяйте одну гипотезу за раз
Если одновременно изменить компонент, API и схему хранения, успешный результат не объяснит, где был дефект. Небольшой диагностический шаг помогает отделить причину от совпадения. Например, сначала подтвердить, что запрос содержит новое значение, затем проверить сохранение на сервере.
Временное журналирование допустимо в безопасной среде, но не должно выводить секреты или оставаться бесконтрольно в рабочем коде. Используйте идентификатор операции и минимальные технические поля. После диагностики удалите ненужные записи либо переведите их в согласованный механизм наблюдения.
Запрос на диагностику без лишних правок
Воспроизведи описанную ошибку на тестовых данных.
Сначала проверь путь от формы до повторного чтения.
Раздели подтвержденные факты и гипотезы.
Не обновляй зависимости и не меняй архитектуру без причины.
После установления причины внеси минимальное исправление.
Добавь регрессионный тест и повтори исходные шаги.
Отдельно сообщи, что не удалось проверить.Шаги воспроизведения и ограничения также используются в примерах официального руководства Codex. Сам агент не заменяет доступ к фактам: если нужный сервис недоступен, причина может оставаться неподтвержденной. Такой статус нужно сохранить в отчете.
Что считать минимальным исправлением
Это не обязательно одна строка. Исправление должно устранять причину и не менять независимое поведение. Если проблема в том, что интерфейс показывает успех до подтверждения записи, может понадобиться изменить обработку результата и добавить состояние ошибки. Просто скрыть уведомление недостаточно.
Не смешивайте исправление с массовым форматированием, переименованием каталогов и обновлением библиотек. Такие изменения затрудняют review и откат. Когда обновление зависимости действительно необходимо, объясните связь с дефектом и отдельно проверьте совместимость.
Добавьте защиту от повторения
Регрессионный тест должен повторять условие, на котором проявлялся дефект. Для проблемы с настройкой важно проверить сохранение и последующее чтение, а не только вызов функции. Если ошибка находится на стыке компонентов, одного unit-теста может быть мало: понадобится интеграционная или пользовательская проверка.
Полезно проверить соседний отрицательный сценарий. Например, при отказе сервера интерфейс должен показывать ошибку и не утверждать, что настройка сохранена. Но не превращайте каждый багфикс в полный аудит системы: расширяйте набор по найденным рискам.
Если ошибка плавающая
Для редких сбоев собирайте условия: последовательность запросов, роль пользователя, время, идентификатор операции, состояние сети. Гонки и повторные отправки трудно поймать одним ручным кликом. Нужен воспроизводимый тест, который управляет порядком событий, задержкой или повтором запроса.
Не добавляйте случайную паузу только потому, что она скрыла проблему. Такая мера может уменьшить частоту проявления, но оставить причину. Для повторных операций часто нужно корректное управление состоянием или идемпотентность, а не ожидание фиксированного количества секунд.
Приемка и выпуск
Перед публикацией повторите исходные шаги, выполните релевантные тесты и изучите diff. Проверьте, что диагностические данные не раскрывают секреты. Если изменение касается базы или интеграции, подготовьте план отката и убедитесь, что тестирование не затронуло реальные заявки.
В итоговом отчете должны быть причина, исправление, выполненные команды и оставшиеся риски. Фраза «похоже, заработало» может быть честным промежуточным наблюдением, но не достаточной приемкой. Если воспроизвести ошибку не удалось, результат лучше назвать диагностикой, а не подтвержденным исправлением.
Подробнее о проверках: критерии готовности и unit-тесты с Codex. Когда сайт теряет заявки или интеграция работает нестабильно, начнем с воспроизведения конкретного сбоя: это надежнее полной переделки по предположению.
