# Assemble > Шаг 2 пайплайна разработки приложений: по утверждённому docs/00-exploration.md собирает BRD, TRD (требования в EARS), SAD, SDD, DDD — по одному, с паузой на утверждение после каждого. Триггеры: /assemble, «/assemble TRD», «собери проектную документацию», «напиши требования к приложению». - Skill: `oastashev/assemble` (Agent Skill) - Install (CLI): `npx skillmds@latest add oastashev/assemble` - Raw SKILL.md: https://api.skillmd.com/api/skills/oastashev/assemble/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: oastashev (https://skillmd.com/u/oastashev) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/oastashev/assemble --- # /assemble — сборка проектных документов На входе — `docs/00-exploration.md` (результат `/explore`). На выходе — пять документов в `docs/`, собранных строго по очереди, каждый на основе утверждённого предыдущего: | # | Файл | Документ | Отвечает на вопрос | |---|---|---|---| | 1 | `docs/01-brd.md` | Business Requirements Document | Зачем и для кого, что считается успехом | | 2 | `docs/02-trd.md` | Technical Requirements Document | Что система должна делать (EARS) и с какими ограничениями | | 3 | `docs/03-sad.md` | Solution Architecture Document | Из чего система состоит и почему так | | 4 | `docs/04-sdd.md` | Solution Design Document | Как компоненты устроены и взаимодействуют | | 5 | `docs/05-ddd.md` | Detailed Design Document | Как это реализовать — до уровня модулей, схем и задач | Документы — по-русски. Идентификаторы, формулировки требований в 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, когда на него сослались: | Собираешь | Читаешь | |---|---| | BRD | exploration целиком | | TRD | BRD §5–§8; exploration §7 (карта capabilities) | | SAD | TRD §3 (заголовки CAP и ID требований), §4, §6, §7; BRD §5 | | SDD | SAD §3–§6; TRD §3 затрагиваемых capabilities, §5 | | DDD | SDD целиком; SAD §4, §7; TRD §4 (NFR); TRD §3 — только колонки ID и Приоритет (для распределения Must/Should по changes в §7) | Если выяснилось, что нужного в прочитанных секциях нет — дочитай недостающую секцию, а не документ целиком. ## Как работать над каждым документом Не изобретай факты о бизнесе пользователя. Всё, чего нет в exploration и утверждённых документах, — либо вопрос пользователю (`AskUserQuestion` с вариантами ответа, пачками по 2–4, только по-настоящему важное), либо явная пометка `[ДОПУЩЕНИЕ A-xx]` / `[TBD Q-xx]` с продолжением нумерации из exploration. Технические решения, наоборот, предлагай сам — с обоснованием и альтернативой, чтобы пользователю было что утверждать. Каждый документ начинается с шапки: ```markdown # <Тип документа>: <название проекта> Версия: 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` ```markdown ## 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//spec.md` почти дословно. Поэтому каждое функциональное требование записывай по одному из шаблонов EARS (Easy Approach to Requirements Syntax), по-английски, с одним `SHALL` и одним действием: | Паттерн | Шаблон | Когда использовать | |---|---|---| | Ubiquitous | `The SHALL .` | Всегда действующее свойство | | Event-driven | `WHEN , the SHALL .` | Реакция на событие | | State-driven | `WHILE , the SHALL .` | Пока система в состоянии | | Unwanted behaviour | `IF , THEN the SHALL .` | Ошибки, отказы, нежелательные ситуации | | Optional feature | `WHERE , the SHALL .` | Опциональная функциональность | | Complex | `WHILE , WHEN , the 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`); `` — конкретное имя системы или компонента. Каждое FR получает 1–3 сценария приёмки в формате `WHEN … THEN …` — они станут `#### Scenario:` в OpenSpec. ```markdown ## 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` ```markdown ## 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` ```markdown ## 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 — выполнил их без новых архитектурных решений. ```markdown ## 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` ```markdown | Шаг | Артефакт | Статус | Дата | | 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`.