Assemble

/assemble — сборка проектных документов

На входе — docs/00-exploration.md (результат /explore). На выходе — пять документов в docs/, собранных строго по очереди, каждый на основе утверждённого предыдущего:

Документы — по-русски. Идентификаторы, формулировки требований в EARS, названия capabilities, API, полей, кода — по-английски: они дословно переедут в спецификации OpenSpec и в код, который будет писать Claude Code, а валидатор openspec и EARS-шаблоны рассчитаны на английский.

Два правила остановки

1. После каждого документа — пауза. Сохранил документ → показал краткое содержание (что решено, какие допущения, что осталось открытым) → спросил через AskUserQuestion: «Утвердить», «Внести правки» (с полем для замечаний), «Остановиться здесь». Следующий документ начинай только после «Утвердить». Правки вноси точечно через Edit в тот же файл, поднимая версию в шапке, — не перезаписывай документ целиком: перегенерация TRD ради одной формулировки стоит столько же токенов, сколько его первая сборка. После правок спрашивай снова. Так каждый документ строится на утверждённом предыдущем и ошибка BRD не размножается в четыре документа ниже.
2. После DDD — стоп. Не запускай /audit, не создавай openspec/, не пиши AGENTS.md/CLAUDE.md. Заверши итогом и фразой «Когда будешь готов — запусти /audit».

Как задавать вопросы

Любой вопрос пользователю — только через AskUserQuestion, с готовыми вариантами ответа: 2–4 конкретных варианта, рекомендуемый — первым с пометкой «(Recommended)», до 4 вопросов за один вызов. Вопрос обычным текстом в ответе («утверждаешь?», «какую папку?») — нарушение: пользователь ждёт кликабельные варианты. Это касается всех развилок этого скила: утверждение документа, выбор папки, подтверждение draft/stale, уточнение фактов о бизнесе, решение о перезаписи. Свободный текст пользователь введёт через «Другое», которое интерфейс добавляет сам.

Где живут файлы

Тот же порядок, что и у остальных шагов пайплайна:

1. Подключённая папка проекта на компьютере пользователя — docs/ в ней. Несколько папок → AskUserQuestion, какая проектная (варианты — имена папок).
2. Папки нет → AskUserQuestion: «Подключу папку проекта сейчас (Recommended)» («Add folder» или device_request_folder_access) / «Работать в документах claude.ai Project».
3. Подключить нельзя → документы claude.ai Project текущего проекта под теми же путями (project_read / project_write) плюс SendUserFile.

Состояние — в docs/STATUS.md (создан /explore; формат см. в конце). Обновляй строку документа при каждом изменении статуса.

Вход и возобновление

• Прочитай docs/STATUS.md и docs/00-exploration.md целиком — остальные документы читаются по секциям (см. «Что читать под каждый документ»). Если exploration отсутствует — остановись и предложи запустить /explore. Если пользователь настаивает работать по описанию из чата — можно, но тогда BRD берёт на себя то, чего не будет в exploration: в §1 явная фраза «шаг exploration пропущен по решению пользователя», в §5 — выбранное направление и non-goals, в §6–§7 — карта capabilities с ID CAP-xx, kebab-case-именами и описаниями (их потом возьмёт init-kickoff для ## Purpose). Везде, где ниже сказано «exploration §7», в этом режиме читай BRD §5–§7. Ожидай больше уточняющих вопросов; /audit поставит за пропуск Major, а не Blocker, только если всё перечисленное в BRD есть.
• Если exploration в статусе draft — AskUserQuestion: «Утвердить exploration и начать BRD», «Сначала доработать через /explore»; работать по неутверждённому нельзя, иначе пауза на утверждение теряет смысл.
• Возобновление: начинай с первого документа, у которого статус не approved. Утверждённые документы перечитай — они источник для следующих, но по таблице «Что читать под каждый документ», а не целиком. Документ со статусом stale не пересобирай молча: перечитай его на фоне изменившихся документов выше, покажи пользователю, что расходится, и спроси через AskUserQuestion — «Подтвердить как есть» (→ approved, версия та же) или «Пересобрать».
• /assemble TRD (или BRD/SAD/SDD/DDD) — пересобрать один документ. Предупреди, что документы ниже по цепочке после этого нужно перепроверить, и пометь их в STATUS как stale.
• Уже существующий документ не перезаписывай молча: покажи, что изменится, спроси через AskUserQuestion («Перезаписать с новой версией» / «Оставить как есть») и подними версию.

Что читать под каждый документ

Утверждённые документы — источник для следующих, но читать их целиком не нужно: к моменту DDD это около 28 000 токенов, которые пересчитываются на каждом вызове до конца шага. Читай только нужные секции (Read с offset/limit, sed -n), остальное подтягивай по ID, когда на него сослались:

Если выяснилось, что нужного в прочитанных секциях нет — дочитай недостающую секцию, а не документ целиком.

Как работать над каждым документом

Не изобретай факты о бизнесе пользователя. Всё, чего нет в exploration и утверждённых документах, — либо вопрос пользователю (AskUserQuestion с вариантами ответа, пачками по 2–4, только по-настоящему важное), либо явная пометка [ДОПУЩЕНИЕ A-xx] / [TBD Q-xx] с продолжением нумерации из exploration. Технические решения, наоборот, предлагай сам — с обоснованием и альтернативой, чтобы пользователю было что утверждать.

Каждый документ начинается с шапки:

# <Тип документа>: <название проекта>
Версия: 1 · Дата: YYYY-MM-DD · Статус: draft | approved · Основан на: docs/00-exploration.md v1, docs/01-brd.md v2

Каждый документ заканчивается разделом «Журнал изменений» (таблица | Версия | Дата | Что изменилось | Кто |): первая строка — «1 · создан»; каждая правка после утверждения — новая строка и версия +1. Сюда же пишет /audit, исправляя Minor-находки. В шаблонах ниже этот раздел не повторяется — он есть у всех пяти документов.

Идентификаторы сквозные и не переиспользуются: BR-xx (бизнес-требования), US-xx (пользовательские сценарии), FR-xxx / NFR-xxx (функциональные / нефункциональные), CAP-xx (capabilities из exploration), C-xx (компоненты, SAD), ADR-xx (архитектурные решения), M-xx (модули, SDD), IF-xx (интерфейсы/API), E-xx (сущности данных), CH-xx (изменения/changes, DDD), T-xxx (задачи, DDD), A-xx / R-xx / Q-xx (допущения, риски, вопросы). Каждое требование и компонент указывают, откуда выросли: это цепочка трассируемости BR → FR/NFR → C → M/IF/E → T, которую потом проверит /audit.

Размер: документ должен быть достаточно полным, чтобы /kickoff мог сгенерировать из него спецификации и задачи без возврата к пользователю, но без воды — таблицы предпочтительнее прозы, повторять содержимое предыдущих документов не нужно, достаточно ссылки по ID. Это не стилистика: каждый документ потом перечитывают следующие шаги /assemble, затем /audit и /kickoff, поэтому лишний абзац оплачивается четыре раза.

Шаблоны

1. BRD — docs/01-brd.md

## 1. Резюме
## 2. Бизнес-контекст и проблема
## 3. Цели и KPI            | ID | Цель | Метрика | Целевое значение | Срок |
## 4. Заинтересованные стороны   | Роль | Интерес | Влияние |
## 5. Область (scope)       В MVP / После MVP / Non-goals — из exploration, уточнённые
## 6. Бизнес-требования     | ID | Требование | Приоритет (MoSCoW) | Источник (US-xx/CAP-xx) | Критерий приёмки (бизнес) |
## 7. Пользовательские сценарии  US-xx, уточнённые, со ссылками на BR-xx
## 8. Бизнес-правила и ограничения   (законодательство, данные, локализация, бюджет, сроки)
## 9. Допущения, риски, открытые вопросы  (A/R/Q, продолжение нумерации)
## 10. Критерии успеха проекта

2. TRD — docs/02-trd.md (требования в EARS)

Здесь рождаются формулировки, которые init-kickoff перенесёт в openspec/changes/*/specs/<capability>/spec.md почти дословно. Поэтому каждое функциональное требование записывай по одному из шаблонов EARS (Easy Approach to Requirements Syntax), по-английски, с одним SHALL и одним действием:

Правила: одно требование — одно поведение (никаких «and/or» с двумя действиями); измеримо и проверяемо (не «быстро», а «within 2 seconds at p95»); без слов-маркеров неоднозначности — should, may, might, could, appropriate, adequate, user-friendly, fast, easy, etc., and/or, as needed, if possible, TBD внутри требования (тот же список проверяет /audit); <system> — конкретное имя системы или компонента. Каждое FR получает 1–3 сценария приёмки в формате WHEN … THEN … — они станут #### Scenario: в OpenSpec.

## 1. Введение и ссылки   (BRD версия, глоссарий терминов)
## 2. Границы системы и контекст   (внешние системы, актёры)
## 3. Функциональные требования — по capabilities
### CAP-01 user-registration
| ID | EARS statement (en) | Пояснение (ru) | Приоритет | Источник | Сценарии приёмки |
| FR-001 | WHEN a visitor submits the sign-up form with a valid e-mail and password, the system SHALL create an account and send a verification e-mail. | … | Must | BR-03 | S1: WHEN … THEN …; S2: IF … THEN … |
## 4. Нефункциональные требования   NFR-xxx, тоже в EARS, по категориям: развёртываемость (запуск и обновление в целевом окружении — на них опирается walking skeleton CH-00), производительность, надёжность, безопасность, масштабируемость, доступность, локализация, наблюдаемость, сопровождаемость
## 5. Требования к данным   (сущности верхнего уровня, хранение, ПДн, ретеншн)
## 6. Требования к интеграциям   | Внешняя система | Назначение | Протокол | Ограничения |
## 7. Технические ограничения   (стек-предпочтения, платформы, лицензии, бюджет инфраструктуры)
## 8. Матрица трассируемости   BR-xx → FR/NFR
## 9. Допущения, риски, открытые вопросы

Пояснение по-русски — одна строка о смысле требования для читателя-человека, а не пересказ английской формулировки: пересказ удваивает самый крупный раздел пайплайна, который потом читают /assemble (SAD, SDD, DDD), /audit и /kickoff. Термин, который нужно объяснять развёрнуто, идёт в глоссарий §1 один раз.

3. SAD — docs/03-sad.md

## 1. Архитектурные драйверы   (какие FR/NFR определяют архитектуру и почему)
## 2. Контекст системы (C4 L1)   диаграмма в Mermaid + таблица внешних систем
## 3. Контейнеры / компоненты (C4 L2)   | ID | Компонент | Ответственность | Технология | Реализует FR/NFR |
## 4. Выбранный стек и обоснование   язык, фреймворки, БД, хостинг, CI, линтер и форматтер для языка (обязательно), инструмент проверки границ слоёв, если есть для стека — с альтернативами, которые отклонены
## 5. Архитектурные решения (ADR)   ADR-xx: контекст → решение → последствия. ADR-01 — всегда Clean Architecture (требование пайплайна, не выбор): четыре слоя domain / application / adapters / infrastructure, зависимости только внутрь, привязка слоёв к компонентам C-xx
## 6. Сквозные аспекты   аутентификация, авторизация, логирование, обработка ошибок, конфигурация, секреты
## 7. Развёртывание и окружения   dev / staging / prod, схема; какое окружение — целевое для walking skeleton (CH-00) и каким путём в него попадает сборка
## 8. Соответствие NFR   | NFR | Как обеспечивается | Как проверяется |
## 9. Риски архитектуры и планы отступления

4. SDD — docs/04-sdd.md

## 1. Декомпозиция на модули   | ID | Модуль | Компонент (C-xx) | Ответственность | Зависимости | Реализует FR |
## 2. Модель данных   сущности E-xx, атрибуты, связи (Mermaid erDiagram), инварианты
## 3. Реестр интерфейсов   | IF-xx | Тип (REST/GraphQL/событие/CLI) | Назначение | Модуль M-xx | Реализует FR | — только реестр; полные контракты (тела, ошибки, авторизация, примеры) живут в DDD §4 и здесь не дублируются
## 4. Ключевые сценарии взаимодействия   sequence-диаграммы для 3–7 главных FR
## 5. Состояния и бизнес-процессы   state-диаграммы там, где есть жизненный цикл (заказ, подписка)
## 6. Обработка ошибок и граничные случаи   таблица: ситуация → поведение → FR (IF/THEN)
## 7. Безопасность   модель угроз в 1 страницу, роли и права
## 8. Конфигурация и переменные окружения
## 9. Стратегия тестирования   уровни, что покрываем автотестами, тестовые данные

5. DDD — docs/05-ddd.md

Последний документ должен быть настолько конкретным, чтобы /kickoff разложил его на задачи OpenSpec, а Claude Code — выполнил их без новых архитектурных решений.

## 1. Структура репозитория   дерево каталогов с назначением, разложенное по слоям Clean Architecture (SAD ADR-01): для каждого каталога — слой и модули M-xx в нём
## 2. Детальный дизайн модулей   **только для модулей changes CH-00–CH-02** (скелет, каркас, первый функциональный срез): файлы, публичный интерфейс (сигнатуры), внутренние типы, алгоритмы нетривиальных частей, ошибки. Для остальных changes — строка в §7: дизайн достроит Claude Code перед началом change по реально написанному коду, а упреждающий дизайн к тому моменту всё равно устареет
## 3. Схема БД / хранилища   DDL или схема миграций, индексы, сиды
## 4. Спецификации API   единственное место с полными контрактами: OpenAPI-фрагменты или таблицы, примеры запросов/ответов, ошибки, авторизация — для интерфейсов CH-00–CH-02; остальные описываются, когда до них дойдёт очередь
## 5. UI (если есть)   карта экранов, состояния экранов, компоненты, привязка к FR
## 6. Инфраструктура и CI/CD   пайплайн, скрипты, деплой, окружения
## 7. План реализации   упорядоченный список изменений (changes) для OpenSpec:
   | ID | Change (kebab-case, en) | Цель | Capabilities | FR/NFR | Зависит от | Оценка |
   | CH-00 | walking-skeleton | минимальное приложение, запущенное в целевом окружении | platform | NFR-005 (развёртываемость) | — | S |
   | CH-01 | project-foundation | каркас, CI, БД, тесты | platform | NFR-001…NFR-004 (сквозные) | CH-00 | S |
   | CH-02 | user-registration | … | CAP-01 | FR-001…FR-006, NFR-007 | CH-01 | M |
   Нулевой change — всегда walking skeleton: минимальное приложение (один эндпоинт или стартовая страница, ответ на `/start`, установка и `--version` — по типу платформы), развёрнутое в целевое окружение из SAD §7 и проверенное там, без БД, auth и CI. Он доказывает путь до целевого окружения раньше, чем в каркас вложено много работы. К нему относятся NFR развёртываемости. Первый change — каркас проекта; к нему относятся остальные сквозные NFR (CI, тесты, наблюдаемость, безопасность платформы). Оба — под служебной capability `platform`. Каждый следующий — законченный вертикальный срез, который можно проверить. Каждое Must/Should FR/NFR попадает ровно в один change.
## 8. Задачи по изменениям   T-xxx с описанием, файлами, критерием готовности, ссылкой на FR — **только для CH-00–CH-02**. Задачи дальних changes устареют ровно так же, как их дизайн, и `/kickoff` для них `tasks.md` намеренно не генерирует
## 9. Definition of Done   (тесты, линтер, документация, spec обновлён)
## 10. Соглашения кодовой базы   обязательно: правила слоёв Clean Architecture (что в каком слое, что запрещено импортировать) и линтер/форматтер из SAD §4 с конфигурацией и командой запуска; далее стиль, именование, коммиты, ветки — то, что попадёт в AGENTS.md

Пауза на утверждение — как она выглядит

После записи файла:

1. Обнови docs/STATUS.md (draft, дата).
2. Покажи 5–10 строк: что в документе главное, какие решения приняты тобой (и какие альтернативы были), список A/Q, требующих внимания.
3. AskUserQuestion: «Утвердить документ и перейти к <следующий>» / «Внести правки» / «Остановиться, вернусь позже».
4. Утверждено → approved в STATUS, переходи к следующему. Правки → исправь, версия +1, строка в журнал изменений, снова п. 2–3. Остановка → STATUS остаётся draft, заверши ответ.

docs/STATUS.md

| Шаг | Артефакт | Статус | Дата |
| assemble/BRD | docs/01-brd.md | draft / approved / stale | YYYY-MM-DD |

stale — документ утверждён, но документ выше по цепочке с тех пор менялся; /audit это заметит.

Чего не делать

• Не собирать несколько документов за один проход «чтобы было быстрее» — пользователь выбрал режим по одному с утверждением.
• Не писать требования прозой или по-русски внутри EARS-таблицы: init-kickoff копирует их в спецификации дословно, валидатор OpenSpec в строгом режиме требует SHALL/MUST в тексте требования, а Claude Code будет писать новые требования по образцу существующих.
• Не заполнять пробелы правдоподобными фактами о бизнесе — только допущение с ID или вопрос.
• Не задавать вопросы обычным текстом — только AskUserQuestion с вариантами.
• Не дублировать содержимое между документами: контракт API описан один раз (DDD §4), требование — один раз (TRD §3), задача — один раз. Ссылка по ID дешевле повтора и не расходится при правках.
• Не расписывать детальный дизайн и задачи для всех changes сразу — только для CH-00–CH-02.
• Не раздувать walking skeleton: в CH-00 нет БД, auth, CI и тестовой инфраструктуры — только то, без чего приложение не запустится в целевом окружении.
• Не перезаписывать документ целиком ради точечной правки.
• Не переходить к /audit.