Урок 16.6. Процесс исправления багов

Зачем это нужно

SDD (уроки 16.3, 16.5) отвечает на вопрос «как построить фичу». Но у разработки есть второй контур - когда существующее поведение сломано. Спека тут не помогает: у вас есть симптом, шаги воспроизведения и ожидание. Нужны диагноз, ограниченный ремонт и проверка против исходного репорта.

Bundled, opt-in расширение bug дает такой процесс: три шага assess -> fix -> test, где каждый баг живет в собственном каталоге .specify/bugs/<slug>/ с диагностики, протоколом изменений и результатами тестов. Процесс не требует сначала проходить SDD-workflow фич.

Основная идея

Расширение bug разделяет работу над багом на три агентные команды с четкими режимами записи:

flowchart LR A["/speckit.bug.assess<br/>только читает код"] -->|assessment.md| B["/speckit.bug.fix<br/>единственный, кто правит код"] B -->|fix.md| C["/speckit.bug.test<br/>только пишет отчет"] C -->|test.md| D{"verdict"} D -- verified --> E["ревью патча и подтверждений"] D -- partial --> F["добавить окружение/данные,<br/>тестировать снова"] D -- failed --> G["вернуться к диагнозу или фиксу"]

Один баг - один slug: имя каталога под .specify/bugs/. Все три команды принимают slug=<name>; если опустить, /speckit.bug.assess спросит (или сгенерирует уникальный в автоматическом режиме). Slug нормализуется в lowercase kebab-case. Если assessment для slug уже существует, интерактивный запуск спросит перед перезаписью; автоматический откажется и выберет новый уникальный slug.

Установка

Расширение bundled и opt-in. Сначала установите Spec Kit и инициализируйте репозиторий с багом (для репозитория с кодом - гайд существующих проектов, урок 16.17). В терминале в корне проекта:

bash
specify extension add bug

Затем запустите coding-агент в этом каталоге. Примеры используют skills-режим GitHub Copilot (/speckit-bug-*); другие агенты дают те же шаги своим синтаксисом (урок 16.10). Каждую команду вызывайте отдельно и ревьюйте вывод до продолжения: это навыки агента, а не терминальные команды; терминал нужен только для установки расширения.

Шаг 1: `/speckit.bug.assess` - оценить баг

Триажирует баг-репорт - вставленный текст (например, stack trace) или URL (например, GitHub issue) - против кодовой базы: суждение, реальный ли это баг; поиск подозрительных путей кода; предложение remediation. Команда read-only: пишет только assessment.md, исходный код не модифицирует.

Передайте симптом, шаги воспроизведения и ожидаемое поведение; выберите короткое, переиспользуемое имя бага:

/speckit-bug-assess "Submitting the login form with an empty password crashes the app instead of showing a validation error." slug=login-crash

Другие формы входа:

/speckit.bug.assess "TypeError: cannot read properties of undefined (reading 'token') at /auth/callback"

/speckit.bug.assess https://github.com/example/repo/issues/1234 slug=callback-token

Выход: .specify/bugs/<slug>/assessment.md. Отревьюйте диагноз и предложенное remediation до запроса фикса. Не продолжайте с неподтвержденным диагнозом или репортом, который не является багом, - это человеческое решение процесса.

Шаг 2: `/speckit.bug.fix` - починить оцененную причину

Применяет remediation, описанное в assessment, и протоколирует, что именно изменилось. Это единственная команда процесса, правящая исходный код; она остается внутри файлов, перечисленных в assessment, если новые подтверждения не требуют расширить охват (расширение фиксируется в секции Deviations from Assessment).

/speckit-bug-fix slug=login-crash

Выход: .specify/bugs/<slug>/fix.md.

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

Шаг 3: `/speckit.bug.test` - протестировать фикс

Повторно запускает воспроизведение и релевантные тесты, затем записывает результат верификации:

/speckit-bug-test slug=login-crash

Выход: .specify/bugs/<slug>/test.md. Как и assess, стадия read-only относительно кода: она не редактирует исходники, чтобы заставить падающий тест пройти. Вердикты не завышаются: если assessment содержал воспроизведение, которое фактически не было выполнено, итог понижается до partial, а не отчитывается как verified.

Вердикт	Значение	Что делать
`verified`	требования верификации успешно выполнены	отревьюить патч и подтверждения до мержа
`partial`	часть верификации не удалось выполнить	доставить недостающее окружение или данные воспроизведения и тестировать снова
`failed`	верификация нашла оставшуюся проблему	вернуться к диагнозу или фиксу по этим подтверждениям, затем тестировать снова

Прошедшего тест-сьюта недостаточно, если исходное воспроизведение так и не было выполнено - держите assessment, fix-протокол и test-отчет вместе, чтобы ревьюер мог проследить ремонт от симптома до подтверждения.

Сводка контрактов команд

Команда	Что делает	Пишет	Код
`/speckit.bug.assess`	триаж репорта против кодовой базы	`assessment.md`	не трогает
`/speckit.bug.fix`	применяет оцененное remediation	`fix.md`	правит (в границах assessment; отклонения - в Deviations)
`/speckit.bug.test`	повторяет воспроизведение и тесты	`test.md` (вердикт)	не трогает

Соглашение о написании: страница справочника использует /speckit.bug.*; skills-режим Copilot - /speckit-bug-*; Codex и ZCode - $speckit-bug-*; Kimi - /skill:speckit-bug-*.

Связь с другими процессами

Работа - новая фича, а не ремонт? Идите в SDD-quickstart (урок 16.3).
Нужно исследовать, стоит ли предложенное изменение усилий? Процесс оценки идей - урок 16.7.
Как сам проект Spec Kit чинит баги агентными workflow bug-assess/bug-fix/bug-test (пока без использования этого расширения) - урок 16.4.

Практика

Установите расширение bug в тестовый проект и внесите в код настоящий маленький баг (например, опечатка в условии). Пройдите все три команды со slug и прочитайте все три артефакта.
На шаге assess намеренно дайте неполный диагноз-запрос (только симптом без шагов воспроизведения) - посмотрите, как agent формулирует гипотезы и что он просит уточнить.
Проверьте граничное правило: после failed-вердикта измените диагноз в assessment.md и повторите fix + test. Убедитесь, что fix остался в границах нового assessment.

Краткое резюме

Расширение bug - трехшаговый триаж: assess (read-only диагноз в assessment.md), fix (единственная правящая код стадия, протокол в fix.md, отклонения фиксируются явно), test (read-only верификация в test.md с вердиктом verified / partial / failed). Один баг - один slug и один каталог .specify/bugs/<slug>/, где хранится вся история от симптома до подтверждения.

Главное из урока:

процесс не требует SDD и независим от него; ставится specify extension add bug;
разделение стадий делает каждый шаг проверяемым: диагноз отдельно, ремонт отдельно, верификация отдельно;
вердикты не завышаются: невыполненное воспроизведение понижает итог до partial;
расширение охвата фикса допускается только с записью в Deviations from Assessment;
«зеленые тесты» без исходного воспроизведения - не верификация.

Вопросы для самопроверки

Какие стадии процесса багфикса правят исходный код? Что делают остальные?
Что такое slug, как он нормализуется и как обрабатывается коллизия с существующим assessment?
Опишите разницу между вердиктами verified, partial и failed. Когда partial выдается вместо verified?
Что обязана сделать команда fix, если новые подтверждения требуют правок за пределами assessment?
Почему процесс требует ревьюить assessment.md до запуска fix? Какое решение здесь остается за человеком?
Как связано расширение bug с агентными workflow bug-assess/fix/test самого проекта Spec Kit?

Что дальше

Ремонт - вторая точка входа; третья - решение, заслуживает ли идея вложений до всякой спецификации. Урок 16.7 разбирает расширение assess: пять стадий от intake до вердикта go / needs-clarification / kill.