analysis-kit
Общие правила для агентов product-owner, business-analyst, system-analyst, security-reviewer и для основной сессии, когда она делает их работу сама. Разделы этого файла действуют всегда. Шаблон и чеклист конкретного артефакта лежат в references/: читай файл только того артефакта, с которым работаешь сейчас.
Каталог и имена файлов
Артефакты одной инициативы лежат в docs/analysis/<feature>/ от корня текущего проекта, то есть рабочей директории. Путь к файлу или каталогу из запроса задаёт каталог сразу; относительный путь отсчитывается от рабочей директории сессии, а не от каталога этого скилла. Иначе, если в проекте уже есть каталог с такими артефактами, работай в нём и назови путь в ответе; найти его помогает glob по **/*_brd.md, **/*_user-story.md, **/*_openapi.yaml внутри рабочей директории.
<feature> — slug инициативы латиницей в kebab-case. Ключ задачи из трекера, если пользователь его дал, идёт первым: PAY-123-sbp-refunds. Slug одинаков во всех артефактах инициативы. Если его нет ни в запросе, ни в существующих файлах, выбери короткий slug по сути инициативы и назови его в резюме.
Файл артефакта: docs/analysis/<feature>/<feature>_<тип>.<расширение>, тип и расширение берутся из таблицы владельцев. Отчёт ревью одного файла: docs/analysis/<feature>/reports/<имя проверяемого файла без расширения>_quality-review.md или ..._security-review.md; отчёт ревью всей инициативы: reports/<feature>_quality-review.md или reports/<feature>_security-review.md.
Владельцы
| Артефакт | Файл <feature>_… |
Владелец | Reference |
|---|---|---|---|
| User Story и Acceptance Criteria | _user-story.md |
product-owner | references/po-user-story.md |
| Приоритизация backlog | _backlog-priority.md |
product-owner | references/po-backlog-priority.md |
| Бизнес-кейс | _business-case.md |
product-owner | references/po-business-case.md |
| Роадмап | _roadmap.md |
product-owner | references/po-roadmap.md |
| Карта стейкхолдеров и RACI | _stakeholder-map.md |
product-owner | references/po-stakeholder-map.md |
| Модель процесса AS-IS | _process-as-is.md |
business-analyst | references/ba-process-model.md |
| Модель процесса TO-BE | _process-to-be.md |
business-analyst | references/ba-process-model.md |
| BRD: бизнес-требования и правила | _brd.md |
business-analyst | references/ba-brd.md |
| Use Case | _use-case.md |
business-analyst | references/ba-use-case.md |
| Gap-анализ | _gap-analysis.md |
business-analyst | references/ba-gap-analysis.md |
| Матрица трассируемости | _rtm.md |
business-analyst | references/ba-rtm.md |
| Backend-логика и функциональные требования | _backend.md |
system-analyst | references/sa-backend-logic.md |
| ER-диаграмма и DDL | _erd.plantuml, _ddl.sql |
system-analyst | references/sa-erd.md |
| Sequence-диаграмма | _sequence.plantuml |
system-analyst | references/sa-sequence.md |
| Спецификация REST API | _openapi.yaml |
system-analyst | references/sa-openapi.md |
| Спецификация событий Kafka | _asyncapi.yaml |
system-analyst | references/sa-asyncapi.md |
| Нефункциональные требования | _nfr.md |
system-analyst | references/sa-nfr.md |
| Отчёт ревью качества | reports/…_quality-review.md |
агент, проводивший ревью | references/quality-review.md |
| Отчёт ревью ИБ | reports/…_security-review.md |
security-reviewer | references/security-review.md |
Артефакт создаёт и меняет только его владелец. Остальные ссылаются на него по ID. Нужна правка в чужом артефакте — опиши её в блоке «Передача».
Границы, на которых роли чаще всего пересекаются:
- User Story и Acceptance Criteria пишет product-owner. BRD ссылается на них по ID и добавляет бизнес-требования и правила, которых в историях нет. Пока историй нет, business-analyst даёт каждому
BRкритерий проверки и просит product-owner оформить истории. - Ожидания бизнеса к скорости, доступности и защите данных business-analyst записывает в BRD словами бизнеса как
BRтипа «ожидание качества». system-analyst превращает их в измеримыеNFRсо ссылкой на исходныйBR. - security-reviewer пишет только отчёт. Исправления по замечаниям
SECвносит владелец артефакта. - Ревью качества проводится по прямой просьбе. Свой артефакт проверяет владелец; system-analyst дополнительно проверяет согласованность артефактов всей инициативы.
ID и трассировка
| Сущность | Формат | Где появляется |
|---|---|---|
| Бизнес-цель | BG-1 |
бизнес-кейс, при его отсутствии BRD |
| User Story | US-1 |
user-story |
| Acceptance Criterion | AC-US-1-1 |
user-story |
| Бизнес-требование | BR-1 |
BRD |
| Бизнес-правило | RULE-1 |
BRD |
| Шаг процесса | P-1 |
модели процесса |
| Use Case | UC-1 |
use-case |
| Изменение из Gap-анализа | CHG-1 |
gap-analysis |
| Функциональное требование к системе | FR-1 |
backend |
| Нефункциональное требование | NFR-1 |
nfr |
| Замечание ревью качества | QR-1 |
quality-review |
| Замечание ревью ИБ | SEC-1 |
security-review |
| Открытый вопрос | Q-1 |
любой артефакт |
Нумерация сквозная в пределах <feature>: перед созданием ID найди grep'ом максимальный номер этого типа в каталоге. Шаги процесса нумеруются отдельно в AS-IS и TO-BE и в ссылках пишутся с файлом. Удалённый элемент остаётся в документе зачёркнутым с причиной, ~~BR-4~~ удалено: дублирует BR-2, и его номер больше не используется.
Ссылка между артефактами — это ID, при первом упоминании в документе вместе с файлом: BR-3 (sbp-refunds_brd.md).
Факты и пробелы
Факты берутся из двух источников: слов пользователя в текущем диалоге и файлов проекта. Пробел записывается маркером [GAP: что неизвестно → кто ответит] в том месте артефакта, где нужен факт, и дублируется вопросом Q-n в разделе «Открытые вопросы». Пример: Максимальная сумма возврата: [GAP: лимит на одну операцию → product-owner].
Цифры, названия систем, сроки и номера пунктов нормативных актов пишутся только из источников. Нормативный акт, который ты знаешь без точного номера пункта, указывай без номера пункта.
Раздел шаблона, который не нужен этой инициативе, остаётся с пометкой Не применимо: <причина>. В готовом артефакте каждый раздел заполнен, помечен [GAP] или помечен Не применимо.
Не хватает чужого артефакта — делай свой с [GAP] в зависимых местах и запроси недостающее в «Передаче».
Оформление
- Текст на русском; технические термины, ключи спецификаций и имена полей на английском.
- Даты в ISO 8601 (
2026-09-11), время в UTC. - Абзац markdown пишется одной строкой, переносы делает рендерер.
- Markdown-артефакт из таблицы владельцев начинается с таблицы метаданных и заканчивается разделами «Открытые вопросы» и «История изменений». Отчёт ревью устроен по-своему: его шапка и разделы берутся из «Шаблона отчёта» в
references/quality-review.mdилиreferences/security-review.md.
| Поле | Значение |
|---|---|
| Feature | `<feature>` |
| Владелец | <агент> |
| Статус | draft |
| Версия | 0.1 |
| Обновлён | YYYY-MM-DD |
| Связанные артефакты | `<файл>`, … |
- Статус
draftилиreviewставит агент,approvedставит только человек. Каждое изменение артефакта повышает версию и добавляет строку в «Историю изменений». - В YAML-спецификациях те же метаданные живут в
info, в PlantUML и SQL — в комментарии в начале файла.
Порядок работы
- Определи
<feature>и каталог. Список файлов получи glob'омdocs/analysis/<feature>/**от рабочей директории и прочитай только найденные, включаяreports/; поиск ограничен рабочей директорией. Шаг завершён, когда известно, какие артефакты уже есть, в каком они статусе и какиеQ-nоткрыты. - Для каждого артефакта, который создаёшь, меняешь или проверяешь, прочитай его reference из таблицы владельцев.
- Сделай артефакт по шаблону и правилам reference. Шаг завершён, когда в файле есть каждый раздел шаблона с тем же заголовком и в том же порядке.
- Пройди чеклист качества из reference по результату и исправь найденное. Шаг завершён, когда каждый пункт выполнен или превращён в
Q-nс[GAP]. - Ответь в формате ниже.
Формат ответа
Это финальное сообщение вызывающему. Содержимое файлов артефактов и отчётов задаёт шаблон их reference.
Резюме: <1-3 предложения: что сделано и зачем>
Файлы:
- `<путь>`: создан | изменён | проверен — <что именно>
Находки: <проблемы, риски, противоречия между артефактами; «нет», если их нет>
Открытые вопросы:
- Q-<n> → <кому>: <вопрос>
Передача:
- → <агент>: <что сделать>; входные файлы: `<путь>`, …
- → пользователь: <какое решение нужно>
Работа передаётся только через блок «Передача»: следующего агента запускает тот, кто вызвал тебя, или пользователь. Если передавать нечего, пиши Передача: не требуется.