# Ddd Domain Documentation Writing > Проектирование и ведение аналитической документации доменной модели в сервисах с DDD и гексагональной архитектурой: агрегатов, сущностей, состояний, инвариантов, поведения, value objects, доменных сервисов, проекций, доменных ошибок и событий. Использовать для сбора требований и создания или дополнения Markdown-спецификаций domain-слоя. Не использовать для CQRS-оркестрации, DTO application-слоя, транспортных контрактов, реализации кода или восстановления требований из кода. - Skill: `nemagu/ddd-domain-documentation-writing` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add nemagu/ddd-domain-documentation-writing` - Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/ddd-domain-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/ddd-domain-documentation-writing --- # Документирование доменной модели Собирать подтверждённые требования и превращать их в спецификации domain-слоя. Описывать домен владельцем бизнес-поведения, инвариантов, состояний, доменных отказов и событий, не перенося в него ответственность внешних слоёв. ## Архитектурная граница Domain не зависит от application, presentation и infrastructure. Не использовать в доменных документах команды, запросы, DTO, модели транспорта, схемы хранения, фреймворки и реализации адаптеров как части доменного контракта. Внешние документы могут ссылаться на публичные доменные контракты. Domain-документ не должен ссылаться на структуры внешнего слоя. Если доменному правилу нужны сведения извне, описывать их бизнес-смысл, владельца и минимальный доменный контракт передачи или получения, не предписывая внешний механизм. ## Статус сведений Различать подтверждённое требование, принятое проектное решение, предложение и открытый вопрос. Не требовать отдельный раздел со статусами для полностью согласованного документа. Предложения и предположения помечать явно и не включать в нормативные таблицы как принятые решения. ## Размещение и навигация Размещать документы в слоте `domain/` принятой структуры. Внутренние каталоги `aggregates`, `projections`, `value-objects`, `services` и `events` создавать только при наличии соответствующих документов и пользы для навигации. Формировать только поддерево раздела «Доменная модель»: индекс `domain/README.md` предшествует дочерним группам, каждый документ включается один раз. Не создавать параллельные корневые каталоги `contexts` или `domain-model`, если слот `domain` уже принят. Внутри доменного поддерева располагать общие объекты-значения, проекции, агрегаты, затем доменные события, если структура репозитория не задаёт иной порядок явно. ## Рабочий процесс ### Стабильные обозначения Строить обозначение из отдельных смысловых сегментов по общей схеме `<контекст>.domain.<категория>.<объект>.<уточнение>`. Не склеивать объект и уточнение в одном сегменте и не пропускать объект. Использовать, например, `projects.domain.aggregates.project` и `projects.domain.events.project.created`, а не `projects.domain.events.project_created`. Одинаковый контракт во всех документах имеет одно обозначение независимо от имени файла. 1. Определить документируемый контекст и объект, его владельца и границу. 2. Изучить принятую структуру документации и связанные документы, не восстанавливая отсутствующие требования из кода. 3. Провести предметное интервью по [domain-interview.md](references/domain-interview.md). 4. Отделить подтверждённые требования и принятые решения от предложений и открытых вопросов. 5. Назначить стабильное обозначение контракту, если на него ссылаются другие документы. 6. Создавать или дополнять один согласованный документ за шаг. 7. После ручного дополнения перечитать документ целиком и продолжить интервью с наиболее значимых противоречий или пробелов. 8. Проверить владельца поведения, инварианты, типы, события, ссылки и направление зависимостей. 9. Оценить готовность документа к реализации и влияние каждого открытого вопроса. ## Выбор справочника - Для агрегатов, сущностей, value objects, доменных сервисов и проекций читать [domain-objects.md](references/domain-objects.md). - Для доменных событий читать [domain-events.md](references/domain-events.md). ## Владение требованиями - Агрегат владеет поведением и инвариантами внутри своей границы. - Доменный сервис владеет правилом, которое естественно не принадлежит одному агрегату. - Агрегат не изменяет другой агрегат и не владеет порядком их загрузки или сохранения. - Проекция владеет локальным представлением, но не исходными данными другого контекста. - Доменное событие принадлежит породившему его контексту и доменному источнику. Оно не становится внешним интеграционным контрактом автоматически. - Application владеет оркестрацией, авторизацией, транзакционной границей, сохранением и публикацией; не описывать их доменным поведением. - Domain может владеть бизнес-правилом о полномочии участника модели, если решение следует из доменного состояния и должно соблюдаться независимо от сценария вызова. Не подменять таким правилом application-авторизацию инициатора. ## Готовность к реализации Считать доменный документ готовым, когда разработчик может выбрать техническую реализацию, не придумывая границу модели, бизнес-семантику, инварианты, поведение, отказы или события. Допускать частичную готовность, если граница готовой части указана явно. ## Открытые вопросы Каждый содержательный документ должен завершаться разделом `## Открытые вопросы`. Закрытое решение переносить в основной раздел и удалять из списка. Для каждого вопроса указывать затронутую часть и влияние: блокирует весь документ, блокирует отдельную часть или может быть отложен. Если нерешённых вопросов нет, писать: ```markdown ## Открытые вопросы Открытых вопросов нет. ``` ## Ограничения - Не сверять требования с кодом без отдельной явной просьбы. - Не выдавать предположения и технические предпочтения за бизнес-решения. - Не включать предложения и предположения в нормативные таблицы как принятые решения. - Не навязывать Python-классы, SQL, брокер, transport envelope или структуру модулей. - Не дублировать application-сценарии в доменном поведении. - Не создавать общий объект между контекстами только из-за совпадения структуры. - Писать документацию на языке пользователя или целевого репозитория. ## Проверка Перед завершением убедиться, что: - объект имеет одного владельца и однозначную границу; - для агрегатов и сущностей определена идентичность, для объектов-значений — равенство по значению; - создание нового объекта отделено от восстановления сохранённого состояния; - создание описано ровно один раз в разделе поведения, а общее для агрегатов восстановление сохранённого состояния не продублировано по файлам; - общие объекты-значения используются несколькими доменными объектами, локальные находятся в явном разделе использующего объекта и не содержат его инварианты; - состояния, статусы, роли и другие доменные перечисления классифицированы как объекты-значения, а разделы жизненного цикла не создают для них отдельные типы; - переходы состояний оформлены единообразно и содержат отдельные идемпотентные исходы, когда они предусмотрены; - все заявленные операции поведения и порождаемые события перечислены, а у событий агрегата есть краткая таблица либо явно зафиксировано их отсутствие; - инварианты и бизнес-полномочия отделены от application-авторизации и предусловий сценария; - каждая операция поведения имеет минимальный однозначный доменный контракт; - семантика повторного вызова определена для каждой операции, где повтор возможен; - каждый доменный отказ связан с правилом и имеет определённые последствия; - межагрегатные правила не нарушают границы агрегатов и имеют определённые требования к согласованности; - доменные документы не используют структуры внешних слоёв; - доменные события сформулированы как свершившиеся факты, связаны с источником и отделены от интеграционных контрактов; - переиспользуемые доменные контракты имеют стабильные обозначения; - неподтверждённые сведения имеют однозначный статус; - реализация не требует придумывать отсутствующие доменные требования; - для каждого открытого вопроса определено влияние на готовность; - относительные ссылки разрешаются; - документы расположены внутри `domain/`, а навигационный фрагмент не меняет порядок глобальных разделов; - документ завершается обязательным разделом `Открытые вопросы`, включая `Открытых вопросов нет.` при отсутствии вопросов.