Руководство: Исправление ошибок
Когда использовать рабочий процесс отладки
Используйте /debug (или скажите «fix bug», «fix error», «debug» на естественном языке) при наличии конкретной ошибки для диагностики и исправления. Рабочий процесс обеспечивает структурированный, воспроизводимый подход, избегающий типичной ловушки — исправления симптомов вместо корневых причин.
Поддерживает всех вендоров (Gemini, Claude, Codex, Qwen). Шаги 1-5 выполняются инлайн. Шаг 6 (сканирование похожих паттернов) может делегировать субагенту debug-investigator при широком объёме (10+ файлов или мульти-доменные ошибки).
Шаблон отчёта об ошибке
При составлении отчёта об ошибке укажите как можно больше из перечисленного ниже. Каждое поле помогает рабочему процессу отладки быстрее сузить область поиска.
Обязательные поля
| Поле | Описание | Пример |
|---|---|---|
| Сообщение об ошибке | Точный текст ошибки или стек-трейс | TypeError: Cannot read properties of undefined (reading 'id') |
| Шаги воспроизведения | Упорядоченные действия | 1. Войти как admin. 2. Перейти на /users. 3. Нажать «Delete». |
| Ожидаемое поведение | Что должно происходить | Пользователь удалён и убран из списка. |
| Фактическое поведение | Что происходит на самом деле | Страница падает с белым экраном. |
Рекомендуемые поля
| Поле | Описание | Пример |
|---|---|---|
| Окружение | Браузер, ОС, версия Node | Chrome 124, macOS 15.3, Node 22.1 |
| Частота | Всегда, иногда, только первый раз | Всегда воспроизводимо |
| Недавние изменения | Что менялось перед появлением бага | Слияние PR #142 |
| Связанный код | Подозрительные файлы/функции | src/api/users.ts, deleteUser() |
| Логи | Серверные/консольные логи | [ERROR] UserService.delete: user.organizationId is undefined |
| Скриншоты/записи | Визуальные подтверждения | Скриншот экрана ошибки |
Чем больше контекста вы предоставите заранее, тем меньше уточняющих вопросов потребует рабочий процесс отладки.
Триаж по серьёзности (P0-P3)
Серьёзность определяет порядок обработки бага и срочность исправления.
P0 — Критический (немедленный ответ)
Определение: Продакшн не работает, данные теряются/повреждаются, активная брешь безопасности.
Ожидание по реагированию: Бросить всё. Это единственная задача до момента разрешения.
Примеры:
- Система аутентификации обходится — все пользователи имеют доступ к admin-эндпоинтам
- Миграция БД повредила таблицу пользователей — аккаунты недоступны
- Обработка платежей списывает дважды
- API-эндпоинт возвращает персональные данные других пользователей
Подход к отладке: Пропустить полный шаблон. Предоставить сообщение об ошибке и стек-трейс. Рабочий процесс начинает сразу с Шага 2 (Воспроизведение).
P1 — Высокий (в текущей сессии)
Определение: Ключевая функция сломана для значительной части пользователей. Обходной путь может существовать, но неприемлем в долгосрочной перспективе.
Ожидание по реагированию: Исправить в текущей рабочей сессии. Не начинать новые фичи до устранения.
Примеры:
- Поиск не возвращает результаты для запросов со спецсимволами
- Загрузка файлов не работает для файлов > 5MB (лимит должен быть 50MB)
- Мобильное приложение падает при запуске на Android 14
- Письма сброса пароля не отправляются (интеграция с почтовым сервисом сломана)
Подход к отладке: Полный 5-шаговый цикл. QA-ревью после исправления рекомендуется.
P2 — Средний (этот спринт)
Определение: Функция работает, но с деградацией. Влияет на юзабилити, не на функциональность.
Ожидание по реагированию: Запланировать на текущий спринт. Исправить до следующего релиза.
Примеры:
- Сортировка таблицы чувствительна к регистру («apple» после «Zebra»)
- Тёмная тема: нечитаемый текст в панели настроек
- Время ответа API /users — 8 секунд (должно быть < 1 сек)
- Пагинация показывает «Страница 1 из 0» для пустого списка
Подход к отладке: Полный 5-шаговый цикл. Включить в набор регрессионного тестирования QA.
P3 — Низкий (бэклог)
Определение: Косметическая проблема, граничный случай, незначительное неудобство.
Ожидание по реагированию: Добавить в бэклог. Исправить при удобном случае или в пакете с похожими изменениями.
Примеры:
- Опечатка в тултипе: «Delet» вместо «Delete»
- Предупреждение в консоли о deprecated API React
- Смещение футера на 2 пикселя при ширине 768-800px
- Спиннер загрузки продолжает крутиться 200 мс после появления контента
Подход к отладке: Полный цикл может не потребоваться. Достаточно прямого исправления с регрессионным тестом.
5-шаговый цикл отладки в деталях
Рабочий процесс /debug выполняет эти шаги в строгом порядке. На протяжении всего процесса используются инструменты MCP для анализа кода — не прямое чтение файлов и не grep.
Шаг 1: Сбор информации
Рабочий процесс запрашивает: сообщение об ошибке, стек-трейс, шаги воспроизведения, ожидаемое vs фактическое поведение, окружение. Если ошибка уже в промпте — сразу к Шагу 2.
Шаг 2: Воспроизведение
Инструменты: search_for_pattern с ключевыми словами ошибки, find_symbol для точного файла и функции.
Трансформирует пользовательский симптом («страница падает») в кодовое расположение (src/api/users.ts:47, deleteUser() throws TypeError).
Шаг 3: Диагностика корневой причины
Инструменты: find_referencing_symbols для трассировки пути выполнения назад от точки ошибки.
| Паттерн | На что смотреть |
|---|---|
| Null/undefined доступ | Отсутствие null-проверок, optional chaining |
| Состояние гонки | Async-операции вне порядка, отсутствие await |
| Отсутствие обработки ошибок | Нет try/catch, необработанный promise rejection |
| Неверные типы | Строка вместо числа, неверная схема |
| Устаревшее состояние | React state не обновляется, замыкание со старым значением |
| Отсутствие валидации | Несанитизированный ввод, непроверенные границы |
Ключевая дисциплина: диагностировать корневую причину, а не симптом.
Шаг 4: Предложение минимального исправления
Рабочий процесс представляет: корневую причину (с доказательствами из трассировки кода), предложенное исправление (минимальное), объяснение почему это исправляет причину. Блокируется до подтверждения пользователя.
Шаг 5: Применение исправления и регрессионный тест
- Реализация исправления — утверждённое минимальное изменение
- Регрессионный тест — должен: проваливаться без исправления, проходить с исправлением, предотвращать повторение
Шаг 6: Сканирование похожих паттернов
Инструменты: search_for_pattern с корневым паттерном по всей кодовой базе.
Например: если баг вызван доступом user.organization.id без проверки null — поиск всех аналогичных обращений к organization.id.
Критерии делегирования субагенту — рабочий процесс запускает субагент debug-investigator, когда:
- Ошибка охватывает несколько доменов (например, затронуты и фронтенд, и бэкенд).
- Объём сканирования похожих паттернов охватывает 10+ файлов.
- Требуется глубокая трассировка зависимостей для полной диагностики.
Вендор-специфичные методы запуска:
| Вендор | Метод запуска |
|---|---|
| Claude Code | Agent tool с .claude/agents/debug-investigator.md |
| Codex CLI | Запрос субагента через модель, результаты в JSON |
| Gemini CLI | oma agent:spawn debug "scan prompt" {session_id} -w {workspace} |
| Antigravity / Fallback | oma agent:spawn debug "scan prompt" {session_id} -w {workspace} |
Все обнаруженные уязвимые места включаются в отчёт. Подтверждённые экземпляры исправляются в рамках той же сессии.
Шаг 7: Документирование
Запись в память: симптом, корневая причина, исправление, изменённые файлы, расположение регрессионного теста, найденные похожие паттерны.
Шаблон промпта для /debug
При запуске рабочего процесса отладки можно использовать структурированный промпт:
/debug
Error: TypeError: Cannot read properties of undefined (reading 'id')
Stack trace:
at deleteUser (src/api/users.ts:47:23)
at handleDelete (src/routes/users.ts:112:5)
Steps to reproduce:
1. Log in as admin
2. Navigate to /users
3. Click "Delete" on a user whose organization was deleted
Expected: User is deleted
Actual: 500 Internal Server Error
Environment: Node 22.1, PostgreSQL 16
Почему эта структура работает:
- Ошибка + стек-трейс позволяет Шагу 2 немедленно найти код (
search_for_patternпо «deleteUser» находит функцию;find_symbolточно определяет расположение). - Шаги воспроизведения с конкретным условием срабатывания («пользователь, чья организация была удалена») подсказывают корневую причину (null foreign key).
- Окружение исключает ложные следы, связанные с версиями.
Для простых багов достаточно краткого промпта:
/debug Страница логина показывает «Invalid credentials» даже при правильном пароле
Рабочий процесс запросит дополнительные данные по мере необходимости.
Сигналы эскалации
Сигнал 1: Одно и то же исправление дважды
Если исправление применено и та же ошибка повторяется — проблема глубже. В рабочих процессах с поддержкой — активация цикла исследования: 2-3 альтернативные гипотезы, тестирование каждой, оценка, выбор лучшего.
Сигнал 2: Мульти-доменная корневая причина
Ошибка фронтенда вызвана изменением бэкенда, вызванным миграцией БД. Эскалация в /work или /orchestrate.
Сигнал 3: Отсутствие среды воспроизведения
Баг проявляется только в продакшене и не воспроизводится локально. Признаки:
- Различия конфигурации, специфичные для окружения.
- Состояния гонки, проявляющиеся только под продакшн-нагрузкой.
- Различия в поведении сторонних сервисов между staging и продакшеном.
Действие: Собрать продакшн-логи, запросить доступ к мониторингу продакшена и рассмотреть добавление инструментации/логирования до попытки исправления.
Сигнал 4: Сбой тестовой инфраструктуры
Регрессионный тест нельзя написать из-за проблем с тестовой инфраструктурой. Действие: сначала исправить инфраструктуру.
Чек-лист валидации после исправления
- Регрессионный тест проваливается без исправления
- Регрессионный тест проходит с исправлением
- Существующие тесты всё ещё проходят
- Сборка успешна
- Похожие паттерны просканированы (Шаг 6 выполнен)
- Исправление минимально — без нерелевантного рефакторинга
- Корневая причина задокументирована в файле памяти
Критерии завершения
- Корневая причина определена и задокументирована (не только симптом)
- Минимальное исправление применено с одобрения пользователя
- Регрессионный тест существует
- Кодовая база просканирована на похожие паттерны
- Отчёт записан в память
- Все существующие тесты проходят