Capstone: rebuilding a feature spec-first

Капстоун повторяет самый частый реальный сценарий внедрения SDD: не новый проект в чистом поле, а запутанная фича, которую страшно трогать. Выбирайте цель по трём критериям: фича ограничена (один модуль, понятные входы и выходы — не «переписать биллинг»), болезненна (её правки регулярно что-то ломают) и наблюдаема (можно запустить и посмотреть поведение). Идеальные кандидаты: экспорт, нотификации, расчёт скидок, парсер импорта.

Первая фаза — археология: восстановить, что фича делает на самом деле. Источники, в порядке надёжности: сам код (агент строит карту веток поведения — попросите перечислить все условия, при которых функция ведёт себя по-разному); тесты, если есть (что команда когда-то считала важным); баг-трекер (закрытые баги — это негласные критерии: «не должно повторяться»); логи продакшена (какие ветки реально исполняются, а какие мертвы).

Параллельно строится сеть безопасности — characterization-тесты: тесты, фиксирующие текущее поведение как есть, включая странности. Не «как должно быть», а «как есть»: если функция на пустом входе возвращает null вместо ошибки — тест фиксирует null. Агент генерирует такие тесты быстро: дайте ему функцию и попросите покрыть все ветки утверждениями о фактических выходах. Эта сеть — то, что отличает переписывание от азартной игры.

Вторая фаза — два документа, и их принципиально не смешивать. Спека as-is описывает фактическое поведение, восстановленное археологией, — включая всё некрасивое: «при отчёте без строк возвращается null и фронтенд показывает вечный спиннер», «даты форматируются в трёх местах по-разному». Пишется она быстро и без оценок: это фотография, а не проект.

Дальше — самый содержательный шаг капстоуна: разбор as-is построчно с вердиктом по каждому пункту. Вердикта три. Контракт: поведение правильное, переносится в to-be как есть — таких обычно большинство. Баг: поведение ошибочно, в to-be записывается исправленный критерий (null на пустом отчёте → файл с одними заголовками), а сам факт фиксируется в списке намеренных изменений. Случайность: поведение — артефакт реализации, на который никто не полагается; в to-be не переносится, но честный ответ на вопрос «точно никто не полагается?» иногда требует проверки потребителей — законы Хайрама никто не отменял.

Спека to-be собирается по полному шаблону второго урока: намерение, ограничения, критерии с идентификаторами. К ней прикладывается список намеренных изменений поведения — он потом ляжет в changelog и в коммуникацию с потребителями. Типичный результат разбора: из сорока пунктов as-is тридцать — контракт, шесть — баги, четыре — случайности. Эти цифры сами по себе аргумент: фича, где 10% поведения — незамеченные баги, оправдывает вложенные в капстоун часы.

Третья фаза — знакомый конвейер, теперь на реальном материале и без поблажек. Если constitution ещё нет — напишите перед стартом: переписывание — худший момент для молчаливых смен стека и стандартов. Затем /specify на основе спеки to-be, и обязательно полный /clarify: на легаси-материале он особенно урожайный, потому что археология всегда оставляет дыры («а что с отчётами, созданными до миграции 2023 года?»). Правило прежнее: implement не стартует, пока есть открытые маркеры.

На шаге plan проверьте два специфичных для переписывания пункта: план обязан включать стратегию совместимости (форматы, API, данные — что обещаем не менять) и стратегию переключения (фиче-флаг, параллельный прогон или прямая замена — для ограниченной фичи обычно достаточно флага). На шаге tasks проследите, чтобы первой группой задач шёл перенос characterization-тестов на новый модуль: сеть безопасности должна быть натянута до, а не после генерации кода.

Контрольные точки фиксируйте после каждого шага: спека to-be апрувнута (гейт из шестого урока), план отревьюен, задачи нарезаны, каждая задача — коммит. Дисциплина чекпойнтов здесь не бюрократия: капстоун — самая длинная работа курса, и возможность прерваться и продолжить без потери контекста — тоже часть отрабатываемого навыка. Ведите короткий журнал решений: он станет основой отчёта в финальной фазе.

Финальная фаза — доказательная приёмка. Три слоя проверки, каждый закрывает свой класс рисков. Критерии to-be: каждый AC-N проходится с вердиктом и ссылкой на тест — это доказательство, что новое поведение реализовано. Characterization-тесты: всё, что было помечено «контракт», обязано пройти на новом коде без изменений теста; упавший тест — либо найденное нарушение совместимости (чинить код), либо пункт, ошибочно не попавший в список намеренных изменений (обновить спеку и список — осознанно). Намеренные изменения: каждое воспроизводится руками — старое поведение ушло, новое соответствует критерию.

Отчёт капстоуна — одна страница: что было (ссылка на as-is и цифры разбора: сколько контракта, багов, случайностей), что стало (ссылка на to-be, список намеренных изменений), доказательства (протокол приёмки, прогон тестов), метрики (размер модуля до и после, время полного цикла, число возвратов на доработку) и инструкция переключения с планом отката.

Этот отчёт — не учебная формальность, а шаблон для взрослой практики: именно так выглядит аргумент «давайте внедрим SDD» для вашей команды — на её собственном коде, с её собственными цифрами. И последний штрих курса: модуль, у которого есть полная спека, тесты по критериям и протокол приёмки, — это модуль, который можно смело отдавать агентам на развитие. Вы построили не только фичу, но и инфраструктуру доверия вокруг неё.