Спецификация наперёд

Также известен как

Big spec up front, Big Design Up Front, спека-водопад, исчерпывающая спецификация.

Контекст

Вы работаете по спецификациям и хотите, чтобы агент сделал всё правильно с первого раза. Поэтому до первой строки кода вы вместе с агентом прописываете всё: состояния, экраны, ошибки, модель данных, крайние случаи. Агент охотно генерирует текст, и документы растут на десятки страниц.

Проблема

Большая часть времени уходит на спецификацию, а рабочей версии всё нет. При этом подробная спецификация не даёт того, ради чего её писали. Что на самом деле нужно, становится понятно, только когда вы видите работающую вещь и пробуете ею пользоваться. Агент всё равно выполняет не все инструкции, а часть выполняет слишком буквально. Ревью сотен строк Markdown даётся тяжелее, чем ревью кода.

Почему так делают

  • Подробная спецификация создаёт ощущение контроля над агентом.
  • SDD-тулкиты предлагают полный процесс для любой задачи, и его проходят целиком.
  • Агент пишет текст быстро, поэтому кажется, что ещё один раздел ничего не стоит.
  • Кажется, что чем детальнее описание, тем точнее результат.
  • Страшно, что агент без полного описания уйдёт не туда.

Последствия

  • ➖ Первая обратная связь от работающего кода приходит через дни, а не через час.
  • ➖ После первого показа значительная часть спецификации переписывается, потому что требования проявились только на прототипе.
  • ➖ Спецификация и код расходятся, и поддерживать приходится оба.
  • ➖ Длинные документы читают по диагонали, поэтому их ревью мало что ловит.
  • ➖ Агент пропускает часть инструкций или увлекается второстепенными.
  • ➖ Небольшие задачи тонут в процессе, который стоит дороже самой работы.

Признаки

  • Спецификация длиннее кода, который из неё получится.
  • После первого дня работы нет версии, которую можно запустить.
  • Вы читаете больше Markdown, чем кода.
  • В спецификации есть разделы «на всякий случай», которые никто не просил.
  • После первой демонстрации половину спецификации пришлось переписать.

Как лучше

Ограничьте спецификацию тем, без чего агент не начнёт: цель, ограничения, критерии готовности и что точно не входит в задачу. Обычно это полстраницы. Затем как можно быстрее получите рабочий прототип — тонкий сквозной срез, который можно запустить и потрогать (см. трассирующие тикеты). Дальше правьте его по тому, что увидели, и дописывайте в спецификацию то, что выяснилось на прототипе. Так спецификация становится не только входом, но и итогом работы.

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

Пример

Было

Распиши полную спецификацию модуля подписок: все состояния, экраны, ошибки, миграции и крайние случаи

Три дня уходят на сорок страниц спецификации и их ревью. На первой демонстрации продакт-менеджер просит, чтобы отмена действовала до конца оплаченного периода, а пробный период не требовал карты. Модель состояний и половина экранов переписываются.

Стало

Сделай рабочий прототип подписок по SPEC.md: оформление и отмена от начала до конца

В SPEC.md полстраницы: цель, ограничения по платёжному провайдеру, критерии готовности и что не входит в первую версию. Через час прототип работает. Вы проходите сценарий сами, показываете продакт-менеджеру и правите по замечаниям:

Отмена должна действовать до конца оплаченного периода. Допиши это в SPEC.md

Спецификация растёт вместе с прототипом и описывает то, что действительно проверили.

Связанные паттерны и антипаттерны

results matching ""

    No results matching ""