Шесть месяцев назад в чате была одна строка: 'нужен streaming для ответов модели'. Сегодня в репозитории - связанный набор из шести файлов, помеченных как активные, с измеренной надёжностью и явными условиями пересмотра. Капстон серии: путь от строки до решения через семь шагов на одной задаче.
Контекст
Шесть месяцев назад в чате команды Vault появилось одно сообщение: «нужен streaming для ответов модели». Контекст - пользователи жалуются, что ответы LLM приходят за 5-10 секунд, и интерфейс выглядит мёртвым. Конкуренты уже стримят токены по мере генерации, у нас - пользователь сидит и смотрит в индикатор загрузки.
Сегодня в репозитории - связанный набор из шести файлов: PRD-018, Spec-012, RFC-007, ADR-012, EVID-001 и DDR-014. Все помечены как активные. У каждого - измеренная надёжность по логике предыдущих постов серии. У ADR-012 - явное условие пересмотра, которое уже однажды сработало.
Я хочу пройти этот путь по шагам и показать, как методы из предыдущих семи постов серии складываются в один связный процесс на одной реальной задаче. Это не теория, это разбор семи шагов и одной невидимой границы - между «активно» и «протухло».
Шаг 1. Маршрутизация
Менеджер проекта берёт сообщение из чата и формулирует задачу: «Добавить streaming-эндпойнт GET /query/stream для ответов модели, чтобы первый токен приходил пользователю за 800 мс».
forgeplan route "Add streaming endpoint GET /query/stream for model responses, first token under 800ms".
Команда возвращает: «уровень deep, нужны PRD, Spec, RFC, ADR. ADI (трёхверсионный анализ) обязателен».
Эта рекомендация занимает полсекунды. Без неё команда бы тратила час на обсуждение «нужен ли тут отдельный ADR или хватит RFC». С ней - обсуждение закрывается, и работа двигается.
Маршрутизация - это первый шаг, и он короткий. Не «попытка угадать истину», а «избавление от спора, который не двигает работу».
Шаг 2. Оформление PRD
forgeplan new prd "Streaming endpoint for model queries". Создаётся файл PRD-018 с 13 разделами и заметками «заполнить».
Менеджер за 30-40 минут заполняет:
- Цель: первый токен ответа модели приходит пользователю за 800 мс в 95-м процентиле; полный ответ - за 5 секунд в среднем.
- Аудитория: пользователи Vault, делающие запросы к модели через интерфейс заметок.
- Метрики успеха: p95 первого токена ≤ 800 мс на staging; p95 первого токена ≤ 1000 мс в прод-нагрузке; снижение метрики «отказы во время ожидания ответа» с текущих 12% до 4%.
- Функциональные требования: десять штук, каждое в формате «при X система делает Y».
- Крайние случаи: что происходит при разрыве соединения на середине стрима; что при превышении 30 секунд тайм-аута; что при перегрузке поставщика модели.
- Не-цели: не делаем кэширование стриминга в MVP; не делаем сохранение частичного ответа при разрыве; не делаем стриминг через WebSockets.
- Риски: медленный поставщик модели может задерживать первый токен; неравномерная нагрузка на серверы может ломать p95.
Шаг 3. Проверка PRD
forgeplan validate PRD-018. Три проверки запускаются автоматически.
Первая - формат документа. Все 13 разделов заполнены? Метрики выражены числами? Нет утечки реализации в требования?
Вторая - согласованность с существующими спецификациями. Не противоречит ли что-то из новых требований текущей схеме API?
Третья - достаточность альтернатив (для ADI на следующем шаге). Сейчас этой проверки нет, она будет на этапе ADR.
Команда возвращает одно замечание: «PRD-018: функциональное требование FR-7 содержит фразу ‘обрабатывать ошибки разумно’ без указания, что значит “разумно”». Менеджер открывает раздел, заменяет на «при ошибке поставщика модели возвращать пользователю сообщение “Сервис временно недоступен, попробуйте через минуту” с кодом ответа 503».
Повторный запуск forgeplan validate PRD-018 - все три проверки зелёные.
Это та самая защита от ситуации «по документу всё сделано, а пользователь говорит - не работает». Проверка не пропускает фразы, которые можно интерпретировать двумя способами.
Шаг 4. Трёхверсионный анализ архитектуры
forgeplan reason PRD-018. Команда генерирует три варианта реализации с проверяемыми следствиями.
- Версия 1: SSE (Server-Sent Events) через стандартный HTTP. Проверяемое следствие: если выбираем SSE, p95 первого токена должен быть ≤ 800 мс на staging при текущей нагрузке. Замер: сделать прототип на 100 строк кода, прогнать нагрузочный тест.
- Версия 2: WebSockets. Проверяемое следствие: если выбираем WebSockets, p95 первого токена должен быть сравним с SSE, но добавится сложность управления соединениями (heartbeat, reconnect). Замер: тот же прототип, но через WebSocket-библиотеку.
- Версия 3: HTTP/2 server push. Проверяемое следствие: если выбираем HTTP/2 push, p95 первого токена может быть ниже SSE на 50-100 мс, но потребуется HTTP/2 на всём пути от клиента до сервера. Замер: прототип + проверка инфраструктуры.
Команда тратит полдня на три прототипа. Результаты:
- SSE: p95 первого токена 180 мс. Реализация - 80 строк. Нет дополнительной инфраструктуры.
- WebSockets: p95 первого токена 170 мс. Реализация - 250 строк (включая reconnect-логику).
- HTTP/2 push: p95 первого токена 140 мс. Но прокси перед нашими серверами обрезает push. Без него - нет push.
Версия 1 (SSE) выигрывает по соотношению результата и сложности. Версия 3 (HTTP/2 push) теоретически быстрее, но требует переделки инфраструктуры - не оправдано при разнице в 40 мс. Версия 2 (WebSockets) не быстрее SSE, но втрое сложнее - нет смысла.
Шаг 5. Запись архитектурного решения
forgeplan new adr "Use SSE for streaming model responses". Создаётся ADR-012 с шестью секциями.
- Контекст: нужен streaming для ответов модели; целевая метрика - p95 первого токена ≤ 800 мс; команда из 4 инженеров, инфраструктура - стандартный HTTP-стек.
- Рассмотренные варианты: SSE; WebSockets; HTTP/2 server push.
- Доказательства: три замера на staging (по одному на вариант), все с CL3 (свой замер на нашей нагрузке).
- Принятое решение: используем SSE для streaming model responses.
- Отвергнутые альтернативы: WebSockets - втрое сложнее реализация при том же результате; HTTP/2 push - требует переделки прокси-инфраструктуры, экономия 40 мс не оправдана.
- Условия пересмотра: пересмотреть, если p95 первого токена превысит 600 мс в прод-нагрузке (запас 200 мс к целевой метрике); ИЛИ если трафик к стриминговой конечной точке вырастет в пять раз; ИЛИ через 12 месяцев в любом случае.
Шаг 6. Реализация и сбор доказательств
Разработчик берёт ADR-012, RFC-007 (где описана реализация в этапах) и Spec-012 (где описано поведение конечной точки). За три дня пишет код, тесты, документацию API.
После выхода в работу - нагрузочный тест в проде. Замер: p95 первого токена - 220 мс. p99 - 380 мс. p99.9 - 750 мс. Метрика «отказы во время ожидания ответа» падает с 12% до 3% за две недели.
forgeplan new evidence "SSE streaming endpoint production benchmark". Создаётся EVID-001 с тремя осями оценки:
- F = 8 (формулировка строгая, метрики чётко определены).
- G = 9 (детальные числа, разбивка по процентилям).
- R = 8 (свой замер в проде, нет мотивации преувеличивать).
- CL3 - без штрафа, замер в нашем проде на нашей нагрузке.
forgeplan link EVID-001 ADR-012 --relation informs. Доказательство связывается с решением.
Шаг 7. Активация и точка невозврата
forgeplan score ADR-012. Команда показывает: R_eff = 0.89. Все три проверки качества - зелёные.
forgeplan activate ADR-012. Файл переходит в активное состояние. Прямое редактирование заблокировано - изменения возможны только через forgeplan supersede.
Тот же файл, но теперь с метками: статус «активный», дата активации, ссылка на доказательство, ссылка на условие пересмотра. Запись становится частью официальной истории решений проекта.
forgeplan health - показывает: 87 решений в проекте, 0 без доказательств, 0 без условий пересмотра, 0 сирот (записей без связей). Здоровый граф. Этот же отчёт через шесть месяцев покажет, какие решения близки к пересмотру.
Через шесть месяцев
Прошло шесть месяцев. Трафик к стриминговой конечной точке вырос в семь раз. p95 первого токена постепенно вырос с 220 мс до 580 мс. Условие пересмотра ADR-012 близко к срабатыванию (порог - 600 мс).
forgeplan stale - команда показывает ADR-012 как «приближается к условию пересмотра». Менеджер проекта получает уведомление в чате.
Команда садится, открывает ADR-012, читает старые альтернативы. Сейчас они выглядят иначе:
- WebSockets - всё ещё сложнее, не помогут с латентностью.
- HTTP/2 push - за полгода прокси-инфраструктура была обновлена для других задач, теперь поддерживает push. Экономия 40 мс может дать запас.
- SSE - текущий вариант, но требует оптимизации горячего пути.
Два решения: либо forgeplan renew ADR-012 (продлеваем с обновлённым условием пересмотра и оптимизированной реализацией), либо forgeplan supersede ADR-012 --by ADR-019 (создаём ADR-019 с переходом на HTTP/2 push, ADR-012 помечается как «заменён ADR-019»).
Команда выбирает первый путь - обновить реализацию SSE с оптимизированным горячим путём. Замер показывает p95 первого токена 280 мс. ADR-012 обновляется через forgeplan renew с новым условием пересмотра (порог 700 мс) и ссылкой на новое доказательство.
Цикл замыкается. Решение, принятое полгода назад, не превратилось в памятник. Оно само открылось на пересмотр, было обновлено, и снова стало живым.
Что осталось за кадром
Я описал семь шагов и одну невидимую границу - переход от «активно» к «приближается к пересмотру». Это полный цикл одной задачи.
Что я не показал в этом капстоне:
- Параллельную работу нескольких команд над разными PRD одного Epic.
- Конфликты, когда два разработчика берут связанные ADR - и как механика claim/release их разводит.
- Случаи, когда решение приходится обнулять и принимать заново (через
forgeplan reopen). - Случаи, когда условие пересмотра было неправильным, и команда учится формулировать триггеры точнее.
Эти ситуации - реальная жизнь, которая не помещается в один пост. Но базовый цикл из семи шагов на одной функции - это та основа, на которую вся остальная сложность опирается. Если этот цикл не пройден на отдельной задаче - никакая «организация работы команды» поверх не сработает.
Что отдать AI-агенту, что - себе
Каждый из семи шагов имеет долю работы для AI и долю работы для человека.
- Шаг 1 (маршрутизация): AI рекомендует уровень глубины. Человек проверяет, что рекомендация совпадает с реальной задачей.
- Шаг 2 (PRD): AI делает первый черновик из 13 разделов. Человек заполняет содержание, метрики, рамки.
- Шаг 3 (проверка): полностью автоматическая. Человек чинит замечания.
- Шаг 4 (ADI): AI генерирует три гипотезы с проверяемыми следствиями. Человек прогоняет замеры и интерпретирует результаты.
- Шаг 5 (ADR): AI заполняет структуру шести секций. Человек пишет настоящую причину отказа от альтернатив (часто внутренний контекст команды).
- Шаг 6 (доказательства): AI шаблонизирует evidence-файл. Человек проставляет F/G/R и уровень контекста.
- Шаг 7 (активация): полностью автоматическая. Человек подтверждает финальный шаг.
Если AI делает все семь шагов на 100% - у вас не цикл решения, у вас семь красивых файлов, в которых через год никто не разберётся. Если AI делает 0% - вы тратите два дня на работу, которая может занять час. Базовое правило: AI генерирует структуру и черновики, человек добавляет содержание и контекст.
Что почитать дальше
Это финальный, восьмой пост в серии «Цикл одного решения».
Полный список:
- Кладбище решений - почему через полгода никто не помнит мотивировку
- Перед тем как чинить - выпишите три версии - приём диагностики
- Среднее обманывает - как оценивать доказательства
- Мотивировочная часть для архитектурного решения - шесть секций DDR
- Архитектор не начинает с чертежей - четыре фазы BMAD
- Спецификация - это не PRD, это контрольный вкус - намерение vs поведение
- POS-терминал для методологий - что такое Forgeplan
- Этот пост (капстон серии)
Серия закончена. На сайте есть десять интерактивных разборов, которые ведут глубже по каждому шагу: 3D-граф артефактов одного проекта, калькулятор уровня глубины задачи, шаблон DDR, дельта-формат для спецификаций, формула R_eff в действии. Главная страница разборов - /guides. Там навигация по типу «если ищете про X - начните с Y».
Если хотите попробовать Forgeplan на своей задаче - он лежит на GitHub под открытой лицензией. Локально, без облака, без подписки. Один бинарный файл, ставится за минуту. Каталог .forgeplan/ живёт в репозитории кода, синхронизация - через git, как у всего остального.
Спасибо, что прошли серию до конца.