Flownix
Начать
Разделы
На этой странице

Работать по документу: режим spec-first

Порядок, в котором документ фичи прорабатывается и принимается до того, как под ней появится первая задача. Черновик, раунды ревью, гейт декомпозиции и выходы из него.

В обычном режиме спека догоняет работу: агент разворачивает дерево задач, пишет код и обновляет документ перед закрытием. В spec-first порядок обратный — сначала документ, задачи после его принятия, и это не рекомендация, а поведение сервера: создать задачу под фичей, чей документ не принят, он откажется.

Про сами политики и чем они друг от друга отличаются — объяснение. Здесь порядок работы.

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

Сценарий, из которого режим и вырос: «мы с тимлидом сидим прорабатываем документ, откидываем какие-то решения, переделываем, после этого принимаем изменения и только затем начинаем работу над кодом».

До spec-first так работать было нечем. Чтобы сохранить рабочую редакцию документа, её приходилось предложить, а предложить — значило поставить человеку вопрос: каждая промежуточная формулировка падала ему в очередь ревью. Отказ порождал новую строку, и «что именно мы откинули» приходилось восстанавливать по журналу.

Включить

В шапке проекта — панель политик. Три переключателя: строгий режим, утверждение предложений, spec-first.

Включать по одному не нужно и не получится: spec-first не работает без двух остальных, и сервер отвергает попытку включить его в одиночку. Панель это знает — она отправляет все три настройки одним запросом и перед включением говорит, что включится вместе.

Обратная сторона того же правила: пока spec-first включён, снять предпосылку нельзя. Переключатели строгого режима и утверждения заблокированы, и подсказка предлагает сначала выключить сам spec-first. Он выключается всегда — из режима есть выход.

Агент тоже умеет — set_project_policy с тремя полями сразу, — но кнопка появилась в v0.18.0 и теперь это короче.

Порядок работы

1. Открыть change

Change — это фича. Отдельной сущности для него нет: у фичи уже есть дети-задачи, ссылки на документы, тред комментариев и статус, и заводить рядом второе понятие значило бы протащить его через всё дерево ради группировки, которую фича даёт бесплатно.

Поэтому первый шаг — создать фичу, у которой в content лежит proposal: зачем, что меняется, границы, и какие альтернативы отвергнуты. Больше на этом шаге не создаётся ничего — ни плана, ни задач.

2. Найти документ, а не заводить второй

Менять нужно тот документ, который уже описывает область. Второй документ про тот же предмет хуже устаревшего: читатель находит один из них и не узнаёт, что есть другой. Новый заводится только когда область не покрыта.

3. Черновик

Агент предлагает дельту — полное новое тело документа — от имени этой фичи. В spec-first она рождается черновиком.

Черновик

Рабочая редакция. Не стоит в очереди ревью, не держит ни один гейт, правится на месте сколько нужно. Никого ни о чём не спрашивает.

Предложение

Вопрос, адресованный человеку. Стоит в очереди, держит гейты, на месте не правится — только решением ревьюера.

Разница практическая: черновик — это не «дельта, которую ещё не посмотрели», а дельта, которую никто не просил смотреть. Если агент сообщает, что ждёт вашего одобрения сразу после создания дельты, он ошибается: вопрос ставит отправка, а не создание.

4. Прорабатывать

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

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

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

5. Отправить и остановиться

Отправка на ревью — отдельное действие. С этого момента дельта попадает в очередь, начинает держать гейты и больше не правится на месте.

Дальше агент останавливается. Не «продолжает со смежной задачей, пока ждёт» — именно останавливается: он не может одобрить дельту сам, и работа, сделанная в ожидании, окажется сделанной против документа, который ещё не приняли.

6. Одобрить или отклонить

Решение принимает человек — в интерфейсе. Отказ требует причины: «отклонено» без причины не говорит автору, что переделать.

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

В карточке фичи история показана лентой: раунд, действие, кто это сделал — человек или агент, — и состав изменения относительно предыдущего раунда. Состав, а не построчный дифф: раундов бывает много, и простыня строк превратила бы историю в то, что не открывают.

7. Нарезать задачи

Только теперь. И по принятому документу, а не по замыслу, с которого всё начиналось: если документ в обсуждении разошёлся с первоначальной идеей, прав документ — его и одобрили.

8. Исполнять

Дальше обычный порядок — выполнить задачу. Дельта применяется вместе с закрытием работы, а не раньше: спека говорит, что система делает, и начинает это говорить, когда система действительно делает.

Если гейт отказал

Отказ выглядит так:

shell
FailedPrecondition: spec_first_not_approved: под фичей AF-FEAT-12 нельзя заводить task —
на проекте включён режим spec_first, и задачи нарезаются по ПРИНЯТОМУ документу, а не до него.
у фичи нет ни одной дельты. Сделайте одно из двух: ...

Он называет фичу, состояние её дельт и оба выхода. Выходов ровно два, и оба законные:

  1. Довести документ до одобрения — вернуться к шагам 3–6.
  2. Объявить, что описанное поведение не меняется — на самой фиче, с содержательной причиной.

Второй выход существует для фичи-рефакторинга и для проектов, которые включили режим на готовом дереве. Без него включение сделало бы недекомпозируемым вообще всё.

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

Что меняется для агента

Ничего из перечисленного агент не выводит сам — он читает это в скиллах. plan-feature проверяет политику проекта прежде, чем создать первую ноду, и при включённом spec-first передаёт работу скиллу spec-first-change, который владеет процедурой целиком. Как это устроено — система скиллов.

Отсюда практическое следствие: после включения режима убедитесь, что у агента свежие скиллы. Агент со старым набором пойдёт разворачивать дерево задач и упрётся в отказ — не сломается, но потратит шаг.

Дальше