Roadmap в Spec Kit: как я изобрёл велосипед

В прошлый раз я писал о переходе на Spec-Driven Development и честно оговорился: над спеками у меня надстроен слой roadmap, и это не канон Spec Kit. В коробке верхний уровень — спека, ничего выше не предусмотрено.

Потом я открыл concepts/spec-of-specs.html в официальной документации. Далее по тексту — “Дока”.

Там черным по белому описано ровно то, что я делал последние недели. С той же мотивацией, с той же структурой, местами теми же словами. Разница есть, но она косметическая.

Ситуация обычная и от этого не менее неприятная. Либо задача имеет одно естественное решение, и все, кто в неё упирается, приходят к одному и тому же. Либо я это где-то прочитал, забыл, и мозг предъявил мне чужую мысль как свою. Криптомнезия называется, и надёжного способа самопроверки у неё нет.

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

Проблема, из которой всё растёт

Формулировка простая: контекстное окно кончается раньше, чем фича.

Практически это выглядит так. Спека написана, план построен, задачи нарезаны, всё выглядит прилично. Запускаешь /speckit.implement, первые тридцать задач идут нормально. Потом агент начинает игнорировать пункты плана, придумывать несуществующие функции и переписывать то, что уже написал сам. Обычно это происходит рядом с компактификацией контекста.

Документация Spec Kit ставит диагноз так же: деградация в середине длинного прогона вызвана исчерпанием контекстного окна, а лечится сужением области каждого отдельного запуска.

Дальше начинается развилка, и вот здесь я в своё время свернул сразу в самый тяжёлый вариант, не заметив трёх более дешёвых.

Три дешёвые опции, которые я проскочил

Дока предлагает лестницу из четырёх ступеней, и декомпозиция стоит на ней последней. /speckit.implement принимает свободный текст, который агент обязан учесть перед началом работы, и этого достаточно для первых двух опций.

Опция 1. Ограничить объём одного прогона.

/speckit.implement only execute tasks T001-T010, then stop and report progress

или по фазам:

/speckit.implement only execute the Setup phase, then stop

Выполненные задачи помечаются [X] в tasks.md, поэтому следующий запуск подхватывает с места остановки. Никакого тулинга, только дисциплина.

Опция 2. Делегирование сабагентам.

/speckit.implement delegate each parallel [P] task to a sub-agent

Каждый сабагент получает узкий контекст: одна задача плюс релевантный кусок плана. Основная сессия при этом не пухнет и до компактификации не доходит.

Опция 3. Комбинация.

/speckit.implement execute only the Core phase, delegate [P] tasks to sub-agents

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

Забавная деталь. Моё любимое «сделай сразу спеки с первой по десятую», которым я хвастался в прошлой статье, это опция 1, поднятая на уровень выше. Ограничение объёма прогона, только единицей измерения выступает не задача, а спека. Я, получается, воспроизвёл всю лестницу целиком, просто в другом порядке и не поняв, что это лестница.

Что предлагает дока

Один проход декомпозиции, на выходе roadmap. Это не спека, а короткий планировочный разговор с агентом:

1. Сформулировать эпик одним-двумя предложениями, чтобы у агента сразу была полная картина.
2. Попросить нарезать его на срезы, каждый из которых даёт связный кусок эпика и специфицируется самостоятельно. Критерий: срез должен быть независимо тестируемым, то есть после реализации одного среза должно остаться что-то демонстрируемое.
3. Для каждого среза написать строчку намерения и явную границу области: что входит, что отложено соседнему срезу. Именно резкость границ удерживает подспеки в размере, который влезает в контекст.
4. Проставить зависимости и упорядочить так, чтобы предпосылки шли первыми. Независимые срезы можно гнать параллельно в отдельных worktree, чтобы состояние активной фичи не пересекалось.
5. Записать результат в файл под версионным контролем, чтобы каждая последующая подспека могла на него сослаться.

Ключевая мысль, которую я бы вынес в рамочку: roadmap намеренно мелкий. Он называет и упорядочивает срезы, но не проектирует их. Проектирование происходит внутри каждого /speckit.specify.

Сам артефакт — обычный markdown, никакого тулинга за ним нет. Кладётся либо в specs/<epic-slug>/roadmap.md для эпика в рамках фичи, либо в корневой ROADMAP.md для сквозного.

Строка roadmap несёт стабильный ID, имя, намерение, границу области, зависимости, статус и ссылку на подспеку, когда та появится. ID после первой ссылки на него не меняется никогда: он служит якорем трассируемости.

Пример: мой реальный roadmap

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

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

И ещё одно, важнее первого. Никакой иерархии roadmap-ов у меня нет. Есть каталог, в нём лежат файлы, все на одном уровне, каждый про своё направление. Ни один не родитель другому.

Вот скелет одного файла, roadmaps/anti-collision.md, с вырезанным мясом:

# Контроль сближения стволов - gap analysis & roadmap

Сопоставление продуктового видения с состоянием системы на 2026-07
(спеки 001-014 отгружены). Каждый пункт ниже - самодостаточное зерно
фичи размером ровно в один цикл speckit: абзац **speckit seed**
вставляется в `/speckit.specify` как есть. Номер фиче присваивает
speckit в момент specify, следующий свободный - 015.

**Архитектурная позиция (решено):** расчётное ядро ничего не знает
о сцене и об интерфейсе, обмен только числами. Каталог инструментов
и их погрешностей приходит справочником и никогда не зашивается в код.

## Что переиспользуем как есть (не переписывать)

| Потребность видения | Что уже есть |
|---|---|
| Хранение замеров с версиями | Хранилище артефактов (spec 003) |
| Пересчёт координат между системами | Геодезический слой (spec 006) |
| Отрисовка и навигация по сцене | WebGL-слой (spec 009) |
| Права по месторождениям | Ролевая модель (spec 011) |

## Матрица разрывов

| Требование видения | Сегодня | Статус |
|---|---|---|
| LAS произвольной структуры | Парсер под фиксированный набор кривых одного подрядчика | Partial |
| Стволы куста в общих координатах | Каждая скважина рисуется от своего устья | Missing |
| Позиционная неопределённость замера | Нет | Missing |
| Расчёт сближения между стволами | Нет | Missing |
| Отчёт по сближениям | Только скриншот сцены | Partial |

## Roadmap

Упорядочено по вехам. Внутри вехи пункты упорядочены по зависимостям.

### Веха 0 - факт куста на экране
Цель: инженер видит уже пробуренное, без расчётов. Критический путь: S1 -> S2 -> S3.

#### S1 - Импорт LAS произвольной структуры  ОТГРУЖЕНО, spec 015
#### S2 - Приведение стволов куста к общему устью
#### S3 - Сцена куста

**Выход вехи**: куст из 30 стволов грузится из папки с LAS-файлами
и крутится в сцене без ручной правки данных.

### Веха 1 - контроль сближения
#### S4 - Модель позиционной неопределённости
#### S5 - Расчёт сближения
#### S6 - Подсветка в сцене и отчёт для планировщика

**Выход вехи**: на историческом кусте система находит известный
инцидент сближения и не даёт ложных срабатываний на соседях.

### Веха 2 - прогноз
#### S7 - Экстраполяция незавершённого ствола по плану
#### S8 - Предупреждение до входа в опасную зону

## Явно не в этом roadmap

- **Автоматическая коррекция траектории.** Мы показываем риск,
  решение принимает человек. Пересматривать после пилота.
- **Импорт WITSML.** Контракт парсера сделан форматонезависимым,
  второй формат ждёт спроса от заказчика.
- **Расчёт по нескольким моделям погрешностей сразу.** Нужны данные
  с пилота, чтобы понять, спорят ли модели на реальных кустах.

А вот один пункт целиком, без сокращений, потому что вся суть в нём:

#### S5 - Расчёт сближения

- **Зависит от**: S2, S4.
- **Разрыв**: геометрия стволов есть, эллипсоиды неопределённости есть,
  но никто не считает расстояние между стволами и не выносит вердикт
  о риске.
- **Speckit seed**: Сервис расчёта сближения поверх существующего
  расчётного слоя. Для пары стволов ищет точки ближайшего сближения
  сканированием по глубине опорного ствола с уточнением на найденном
  минимуме, считает расстояние центр-центр и коэффициент разделения
  как отношение этого расстояния к комбинированному радиусу
  неопределённости из S4. Пороги вердикта приходят конфигом
  (по умолчанию: ниже 1.0 - пересечение вероятно, 1.0-1.5 - опасное
  сближение, выше - норма) и версионируются вместе с расчётом, потому
  что заказчики трактуют пороги по-разному. На выходе список эпизодов
  сближения: глубины по обоим стволам, расстояние, коэффициент,
  вердикт, версия модели погрешности и версия порогов. Результат
  кешируется по паре (ствол, версия замеров) и инвалидируется при
  загрузке новых замеров. API отдаёт как эпизоды, так и профиль
  коэффициента по глубине - профиль нужен S6 для подсветки.
- **Приёмка**: на историческом кусте с задокументированным инцидентом
  расчёт находит эпизод на той же глубине с расхождением в пределах
  допуска; на паре заведомо разнесённых стволов эпизодов нет;
  загрузка нового замера в один ствол инвалидирует кеш только по
  парам с его участием; смена порогов конфигом меняет вердикт, но не
  меняет расстояния; расчёт куста из 30 стволов укладывается
  в бюджет времени.
- **Не в объёме**: подсветка и отчёт (S6); учёт скорости бурения
  и прогноз (S7); коррекция траектории (не в roadmap вообще).

Три вещи в этом формате стоят отдельного разговора.

Пункт roadmap — это готовое зерно для /speckit.specify. Абзац seed вставляется в команду как есть, без переписывания. Это не описание намерения, это уже постановка: с решениями, с именами сущностей, с порогами по умолчанию. Ровно то, чего канон делать не велит, и об этом ниже.

Приёмка написана до спеки, а не после плана. Формулировки вида «находит эпизод на той же глубине», «инвалидирует кеш только по парам с его участием» появляются в момент планирования, когда я ещё думаю про задачу, а не про код. Позже, внутри цикла, они превращаются в критерии в spec.md почти дословно. Это единственная часть документа, которую я пишу медленно и с удовольствием: она же потом работает тестом на то, что агент сделал не то.

Раздел «Явно не в этом roadmap» оказался важнее, чем я думал. Он не про планирование, он про то, чтобы каждые две недели не возвращаться к одному и тому же спору с самим собой. Дока такого раздела не предусматривает вовсе, а зря: у среза есть граница, а у направления в целом её негде записать.

Два пространства номеров

Отдельная неприятность, о которой дока молчит. Идентификаторы в roadmap мои: S1, S5, S8. Номера фич присваивает speckit в момент /speckit.specify, последовательно и по факту запуска. Соответствия между ними нет никакого: пункт S1 в реальном файле уехал в спеку 022, потому что отгрузился позже соседей.

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

Двусторонние ссылки

Дока предлагает конвенцию, которую я делал наполовину. У неё связь двусторонняя: подспека ссылается на свою строку roadmap, roadmap ссылается на подспеку. У меня работало только одно направление, от roadmap к спеке, той самой пометкой об отгрузке с номером.

Обратной ссылки не было, и это ощущалось. Открываешь specs/022-well-separation/spec.md через пару недель и видишь постановку без контекста: почему именно так, что было отложено соседу, кто на этот кусок опирается. Всё это лежит в roadmap, но чтобы туда попасть, надо сначала вспомнить, что roadmap вообще есть, а потом угадать, в каком из файлов каталога искать.

Конвенция из доки лечится одной строкой в шапке спеки:

# Feature Specification: Расчёт сближения стволов

**Input**: Parent roadmap: `roadmaps/anti-collision.md` -> пункт **S5**.
Расчёт коэффициента разделения между стволами и вердикт о риске.

Обе ссылки — обычный текст, поэтому трассировка делается грепом, без метаданных и схем. rg "S5" по репозиторию за секунду показывает и пункт roadmap, и спеку, и всё, что на неё сослалось.

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

Где я всё-таки отличаюсь

Расхождений пять, и ни одно не отменяет совпадения.

Первое. Roadmap у меня по умолчанию, у доки по необходимости. Дока предлагает заводить roadmap, когда фича не влезает в цикл, и рекурсировать, если срез не влезает и после этого. У меня roadmap появляется сразу, независимо от размера, и живёт не как вспомогательный документ конкретного эпика, а как постоянный список направлений в отдельном каталоге.

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

Второе. Мой roadmap начинается не с декомпозиции, а с разрыва. В каноне roadmap смотрит вперёд: вот эпик, вот срезы, поехали. У меня половина документа смотрит назад: что уже есть и переиспользуется как есть, что есть частично, чего нет вовсе. Только после этого идёт список пунктов.

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

Третье. Мой roadmap проектирует, и это прямое нарушение. Дока говорит буквально: roadmap намеренно мелкий, он называет и упорядочивает срезы, но не проектирует их, проектирование происходит внутри /speckit.specify. Мысль здравая: не надо принимать решения раньше, чем набрал контекст для них.

У меня в каждом пункте лежит абзац seed, который вставляется в /speckit.specify как есть, и в нём уже есть решения: способ поиска ближайшей точки, состав возвращаемой структуры, стратегия инвалидации кеша, пороги по умолчанию. Формально я проектирую в roadmap.

Почему я на это иду. Абзац seed пишется в тот момент, когда я держу в голове весь эпик целиком и вижу соседей. Именно там становится очевидно, что профиль коэффициента по глубине нужен не самому расчёту, а подсветке из соседнего пункта. Если не записать это сразу, через две недели, внутри /speckit.specify по одному пункту, я про соседа не вспомню, а агент тем более. Канон предлагает решать это резкими границами. Мои границы, видимо, недостаточно резкие, чтобы заменить решения.

Плата понятна и я её вижу: часть решений в seed написана до того, как я разобрался в задаче, и часть из них потом оказывается неверной. Спасает clarify, который эти решения оспаривает.

Четвёртое. Пакетный запуск. Дока описывает работу по одному пункту: взял следующий с закрытыми зависимостями, прогнал полный цикл, пометил done. Я регулярно запускаю пачками. Это работает при двух условиях: пункты в пачке не зависят друг от друга, и по каждому уже пройден clarify. Когда я нарушал любое из двух, получал десять аккуратных, консистентных и одинаково неверных реализаций.

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

Но есть класс задач, где вертикальная нарезка обходится дороже. Модель позиционной неопределённости из S4 — это математика с проверяемым результатом: есть эталонные расчёты, есть допуски, есть случаи, где ответ известен заранее. Если размазать её по трём пользовательским сценариям, она будет написана трижды, слегка по-разному, и разойдётся на четвёртом. Проверять её при этом придётся через сцену, а не через набор тестов на числа.

Поэтому я разрешаю себе горизонтальные пункты, но по узкому правилу: только когда у пункта есть собственный проверяемый контракт, независимый от интерфейса. Не «слой репозиториев», не «базовые модели», не «инфраструктура», а конкретный вычислимый результат, который можно накрыть тестами и потом не трогать. S4 под это правило подходит, у него на выходе числа, которые сверяются с эталоном.

Цена честная. Такой пункт не показать заказчику, и на демо придётся объяснять, почему на экране ничего не изменилось. В одиночном проекте я эту цену плачу спокойно. Как только в схеме появится PO, придётся либо объяснять ему устройство расчётного ядра, либо вернуться к канонической нарезке. Подозреваю, что второе.

Собственно, это главный риск конструкции. Roadmap не проходит через /speckit.analyze. Спеки между собой валидируются, roadmap не валидируется ничем, кроме здравого смысла автора. Ошибка в нарезке размножается по всем срезам без сопротивления, и чем лучше работает автоматика, тем быстрее.

Так гении сошлись или я переизобрёл колесо

Честный ответ: скорее ни то ни другое.

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

Совпало не потому, что кто-то умный, а потому что у задачи одна естественная форма. Люди, делавшие Spec Kit, упёрлись в ту же стену и обошли её тем же способом. Примерно как все независимо изобретают одинаковый формат лога.

Возможность криптомнезии я при этом не отрицаю. Дока в открытом доступе, README и часть концептуальных страниц я читал в самом начале, конкретно spec-of-specs не помню. Это ничего не доказывает: забытое чтение по определению не помнится.

Интереснее другое. Если я действительно реконструировал это сам, реконструкция заняла несколько недель и стоила пары сломанных эпиков. Чтение раздела Concepts заняло бы двадцать минут.

Мораль скучная: прежде чем надстраивать слой над инструментом, стоит прочитать раздел документации, который называется Concepts. Звучит как совет из методички. Тем не менее.

Что дальше: SDD на треке PO — dev — QA

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

Исходная расстановка: product owner (PO)живёт в вики и трекере задач, разработчик живёт в репозитории, QA живёт в трекере и частично в репозитории. Доступ к репозиторию у PO появится, это решённый вопрос, а не пожелание. Нерешённый вопрос другой: будет ли он этим доступом пользоваться. Права выдаются одним движением, привычки не выдаются вообще.

Артефакты Spec Kit при этом лежат в репозитории целиком. Отсюда конфликт: spec.md по природе документ продуктовый, а по месту хранения инженерный.

Гипотеза о распределении, которую я собираюсь проверять:

Здесь есть неприятная деталь, вокруг которой всё и вертится.

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

То есть проблема не в правах. Доступ будет, а вопросы всё равно будут возникать в момент, когда PO занят чем-то другим, и в интерфейсе, который он открывает раз в неделю.

Вариантов вижу три, и все с недостатками.

1) PO работает прямо в репозитории. Раз доступ есть, это самый прямой путь: спека правится там же, где живёт, второго источника истины не возникает. Барьер не в правах, а в инструментах. Терминал и git отпадают сразу, но веб-редактор с правкой через pull request закрывает процентов восемьдесят потребности: markdown в браузере, ревью в комментариях, никаких веток руками. Остаётся то, что через веб не сделать, а именно интерактивный clarify.

И вот здесь напрашивается вопрос, которого я не могу не задать. Если PO уже в репозитории, уже пишет спеку и уже отвечает на clarify, то что мешает ему пройти дальше по цепочке? Команды одинаковые: plan, tasks, implement. Дальше QA проверяет результат по критериям приёмки, которые тот же PO и написал. Разработчик в этой схеме нужен только на ревью.

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

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

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

2) Синхронизация вики и репозитория. Спеки пишутся в вики, автоматически подтягиваются в specs/. Получаем два источника истины и вечный вопрос, какой из них главный. Опыт говорит, что побеждает тот, который ближе к коду, а вики тихо протухает за квартал.

3) Асинхронный clarify через трекер. Агент формирует вопросы, они уезжают задачей в трекер, PO отвечает там, ответы возвращаются в спеку и коммитятся разработчиком. Дольше по времени цикла, но не ломает существующие роли и не требует от PO ничего нового. По сути это тот же human-in-the-loop, который мы делаем для агентов, только человеком в цикле здесь оказывается PO.

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

Отдельный вопрос, к которому я даже не подступался. Что происходит с QA, когда критерии приёмки лежат в spec.md, а тест-кейсы в отдельной системе. Формально spec.md уже содержит проверяемые критерии, то есть частично дублирует тест-план. Либо QA переезжает в репозиторий, либо мы сознательно живём с дублированием и регламентом синхронизации. Первое чище, второе реалистичнее.

Есть и третий вариант, который мне нравится больше остальных, но который я пока не пробовал: генерировать тест-кейсы из спеки как ещё один производный артефакт, наравне с plan.md и tasks.md. Тогда дублирования нет, есть один источник и два потребителя. Ломается это ровно в тот момент, когда QA нужно проверить что-то, чего в спеке нет, а именно этим QA и ценен.

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

Источник