# Cqrs Application Documentation Writing > Проектирование и ведение аналитической документации application-слоя с CQRS в сервисах с гексагональной архитектурой: пользовательских и системных команд, запросов, входных и выходных DTO, портов, авторизации, транзакционных границ, application-ошибок и составных сценариев. Использовать для сбора требований и создания или дополнения Markdown-спецификаций application-операций и пайплайнов. Не использовать для описания доменных инвариантов, транспортных контрактов, реализации кода или восстановления требований из кода. - Skill: `nemagu/cqrs-application-documentation-writing` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add nemagu/cqrs-application-documentation-writing` - Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/cqrs-application-documentation-writing/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: Nemagu (https://skillmd.com/u/nemagu) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/nemagu/cqrs-application-documentation-writing --- # Документирование прикладного слоя с CQRS Собирать подтверждённые требования и превращать их в спецификации команд, запросов и составных сценариев. Описывать application композитором доменных операций: получение данных через порты, авторизацию, порядок действий, транзакционную границу, сохранение, публикацию и возвращаемый результат. ## Архитектурная граница Application может использовать публичные контракты domain и объявляет необходимые ему порты. Не использовать в application-документах модели presentation, транспортные envelope, HTTP-статусы, конкретные брокеры, SQL, реализации репозиториев и другие структуры внешних слоёв. Presentation и infrastructure могут ссылаться на публичные application-команды, запросы, DTO, ошибки и порты без повторного определения. Application-документ не должен зависеть от документов внешних адаптеров. При необходимости внешнего ресурса описывать требуемый порт и его контракт, а не реализацию. ## Статус сведений Различать подтверждённое требование, принятое проектное решение, предложение и открытый вопрос. Не требовать отдельный раздел со статусами для полностью согласованного документа. Предложения и предположения помечать явно и не включать в нормативные таблицы как принятые решения. ## Размещение и навигация Размещать документы в слоте `application/`: общие DTO и порты — в `contracts`, канонические команды и запросы — в `operations`, составные сценарии — в `scenarios`. Не создавать параллельный корневой раздел `pipelines`, если принят слот `application`. Считать команды, запросы, DTO и порты контрактами для реализации application- слоя. Составные сценарии предназначать для человека: ими объяснять путь к пользовательской или системной цели через несколько канонических операций. Не считать сценарий контрактом для реализации и не вводить ради него машинные статусы, входы или результаты, отсутствующие у участвующих операций. Получение справочных данных документировать как query. Размещать такие операции по тем же правилам, что и остальные запросы: учитывать бизнес-возможность, инициатора, авторизацию и источник данных. `reference_data` использовать только для самостоятельной устойчивой группы справочных запросов. Формировать только поддерево раздела «Прикладной слой». Индекс `application/README.md` предшествует контрактам, операциям и сценариям; каждый документ включается в навигацию один раз. ## Рабочий процесс ### Стабильные обозначения Строить обозначение из отдельных смысловых сегментов. Для операций использовать `<контекст>.application.operations...<ресурсы>.<действие>`, например `projects.application.operations.commands.user.projects.update`. Для входного DTO использовать `<контекст>.application.contracts.input.<ресурс>.<действие>`, например `projects.application.contracts.input.project.update`. Не склеивать ресурс и действие (`update_member_role`) и не пропускать ресурс (`input.update_project`). Одинаковый контракт во всех документах имеет одно обозначение независимо от имени файла. 1. Определить цель, инициатора и вид документа: команда, запрос или составной сценарий. 2. Изучить согласованные domain-документы и структуру документации, не восстанавливая отсутствующие требования из кода. 3. Провести интервью по [application-interview.md](references/application-interview.md). 4. Отделить application-решения от доменных правил и транспортной политики. 5. Отделить подтверждённые требования и принятые решения от предложений и открытых вопросов. 6. Назначить стабильное обозначение переиспользуемому контракту, если на него ссылаются другие документы. 7. Зафиксировать минимальные входные и гарантированные выходные сведения, требуемые возможности портов, порядок действий, исходы и границы согласованности. 8. Создавать или дополнять один согласованный документ за шаг. 9. После ручного дополнения перечитать документ целиком и продолжить интервью с наиболее значимых противоречий или пробелов. 10. Проверить ссылки, владельцев контрактов, направление зависимостей и отсутствие дублирования domain-документов. 11. Оценить готовность документа к реализации и отметить, какие открытые вопросы блокируют всю реализацию, отдельную её часть или могут быть отложены. Для команд, запросов и составных сценариев читать [cqrs-pipelines.md](references/cqrs-pipelines.md). Для входных границ, DTO, исходящих портов, авторизации, совместимости, внешних значений, транзакционных границ, публикации и ошибочных исходов читать [application-boundaries.md](references/application-boundaries.md). ## Владение требованиями - Domain владеет поведением, инвариантами, состояниями, доменными ошибками и событиями; ссылаться на его документы, не копируя их содержание. - Application владеет DTO операций, авторизацией, оркестрацией, портами, транзакционными границами, сохранением, публикацией и публичными исходами операций. - Presentation и transport владеют разбором внешнего ввода, сериализацией, транспортными ответами и политикой доставки. - Infrastructure владеет реализацией портов и техническими механизмами. ## Открытые вопросы Каждый содержательный документ должен завершаться разделом `## Открытые вопросы`. Закрытое решение переносить в основной раздел и удалять из списка. Если нерешённых вопросов нет, писать: ```markdown ## Открытые вопросы Открытых вопросов нет. ``` ## Ограничения - Не сверять требования с кодом без отдельной явной просьбы. - Не выдавать предположение или возможный технический механизм за принятое решение. - Не включать предложения и предположения в нормативные таблицы как принятые решения. - Не переносить доменную логику и классификацию доменных ошибок в application-документ; наблюдаемые результаты выражать application-исходами. - Не разделять одну application-операцию только из-за разных транспортов. - Не использовать составной сценарий как спецификацию реализации или отдельную входную границу application. - Не выносить получение справочных данных из раздела запросов и не использовать transport-доступность `public` как критерий application-размещения. - Не объединять разные контракты необязательным инициатором или флагом обхода прав. - Не описывать конкретную реализацию порта. - Не закреплять имена классов и методов, языковые типы, сигнатуры или структуру модулей. - Писать документацию на языке пользователя или целевого репозитория. ## Проверка Перед завершением убедиться, что: - операция имеет однозначные цель, инициатора, вход и результат; - зафиксированы только минимально необходимые входные и гарантированные выходные сведения; - DTO и порты принадлежат application, а не внешнему адаптеру; - входная операция отделена от используемых ею исходящих портов; - исходящие возможности разделены по смысловой ответственности без навязывания структуры интерфейсов; - для каждого входа и результата порта однозначно указана смысловая форма: существующий domain VO, неизменяемый application DTO или обоснованное техническое значение; - закрытое объединение существующих DTO описано без инфраструктурного перечисления типов, а постоянный порядок и переходы состояния принадлежат соответствующему порту; - при раздельных портах состояния, истории и outbox каждая изменяющая команда явно вызывает все требуемые возможности в одной согласованной транзакционной границе; - определены инициатор, область и порядок application-авторизации; - для переиспользуемых контрактов указаны потребители и смысловые гарантии; - общий ожидаемый результат порта и операции принадлежит application DTO, а не внутреннему контракту адаптера; - все возможности портов представлены таблицами с единым набором обязательных колонок; - команды, пользовательские запросы, справочные запросы, системные команды и сценарии используют закреплённые структуры и порядок разделов; - раздел ссылок на доменные и application-контракты в операциях называется `Используемые контракты`; - стабильные обозначения содержат отдельные сегменты вида операции, инициатора, ресурса и действия без склеивания ресурса с действием; - выходной раздел операции ссылается на DTO и доменный источник, но не дублирует конкретные значения доменного состояния; - переиспользуемые контракты имеют стабильные обозначения; - неподтверждённые сведения имеют однозначный статус; - определены влияющие на результат внешние значения и их поведение при повторе; - определены связь публикации с сохранением и её влияние на завершение операции; - успешные и ошибочные исходы сведены в итоговую таблицу; - каждый наблюдаемый доменный отказ преобразован в публичный application-исход; - реализация не требует придумывать отсутствующие application-требования; - для каждого открытого вопроса указано его влияние на готовность реализации; - application-документ использует domain-контракты только в направлении зависимости `application → domain`; - документы не содержат моделей или политик presentation и infrastructure; - доменное поведение заменено ссылками на документы владельцев; - относительные ссылки разрешаются; - документы расположены внутри `application/`, а навигационный фрагмент не меняет порядок глобальных разделов; - документ завершается обязательным разделом `Открытые вопросы`, включая `Открытых вопросов нет.` при отсутствии вопросов.