# Presentation Layer Documentation Writing

> Координация аналитической Markdown-документации presentation-слоя в сервисах с гексагональной архитектурой: определение внешних точек входа, границ ответственности, владельцев контрактов, связей с application-слоем и выбор специализированного скила для HTTP API или входящих сообщений. Использовать при проектировании presentation-слоя целиком, распределении требований между документами и проверке межтранспортной согласованности. Не использовать как основной скил для подробного описания HTTP endpoint-ов, message consumer-ов, фоновых процессов, исходящих адаптеров или реализации кода.

- Skill: `nemagu/presentation-layer-documentation-writing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add nemagu/presentation-layer-documentation-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/presentation-layer-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/presentation-layer-documentation-writing

---


# Документирование presentation-слоя

Координировать документацию внешних точек входа, сохраняя границы гексагональной
архитектуры. Не дублировать подробные правила специализированных транспортов.

## Архитектурная граница

Presentation зависит от публичных application-контрактов и не обращается к
domain напрямую. Фиксировать направление зависимости:

```text
внешний контракт → presentation → application → domain
```

Presentation владеет внешними моделями, транспортной валидацией, получением
доверенного контекста, преобразованиями и внешними исходами. Application владеет
сценарием, авторизацией и публичными application-исходами. Domain владеет
бизнес-правилами и доменными отказами.

Не публиковать application DTO как внешнюю модель и не преобразовывать доменный
отказ непосредственно во внешний исход.

К presentation также относятся внутренние driving entry points, которые сами
инициируют application-операции по времени или внутреннему условию. Они не имеют
внешней входной модели, но принадлежат тому же направлению зависимости.

## Размещение и навигация

Размещать presentation-документы в едином слоте `presentation/`:

- HTTP API — `presentation/http/`;
- входящие сообщения — `presentation/messages/`;
- фоновые процессы — `presentation/background_processes/`.

Исходящие внешние контракты и паспорта исходящих адаптеров в этот слот не
помещать. Формировать поддерево «Презентационный слой» в порядке: HTTP API,
входящие сообщения, фоновые процессы. Не создавать для этих входов параллельные
корневые разделы.

## Выбор специализированного скила

- Для HTTP API использовать `http-api-documentation-writing`.
- Для входящих сообщений использовать `message-consumer-documentation-writing`.
- Для периодических и постоянно работающих внутренних процессов использовать
  `background-process-documentation-writing`; считать их внутренними driving
  entry points presentation, не смешивая с HTTP и message consumer-контрактами.
- Для нескольких видов входа сначала определить общие требования здесь, затем
  документировать каждый внешний контракт своим скилом.

Исходящие сообщения и технологические клиенты являются адаптерами выходной
стороны и не входят в эти скилы.

## Рабочий процесс

1. Определить потребителей, назначение и виды внешнего взаимодействия.
2. Найти согласованные application-операции, входы, результаты и публичные исходы.
3. Разделить общие требования и транспортно-специфичные контракты.
4. Определить владельца каждой модели, правила и нормативного документа.
5. Выбрать специализированные скилы и структуру документов.
6. Проверить сквозные идентичность, область вызова, корреляцию и совместимость.
7. Проверить отсутствие противоречий между транспортами и application-слоем.

Использовать документацию как основной источник требований. Код изучать только
при адаптации существующей документации, после отдельного разрешения пользователя.

## Общие требования

Для каждой внешней точки входа фиксировать:

- потребителя и назначение;
- публичную application-операцию и ссылки на её контракты;
- собственные presentation-модели;
- источники внешних сведений и доверенного контекста;
- преобразование входа и результата;
- транспортную валидацию отдельно от бизнес-правил;
- внешнее представление публичных application-исходов;
- повтор, совместимость и значимую наблюдаемость;
- готовность и открытые вопросы.

Стабильное обозначение документа строить как иерархию
`<контекст>.<слой>.<уточнения...>`. После слоя количество сегментов не
ограничивать. Для presentation включать вид взаимодействия, область доступности и
версию, когда они различают контракты.

## Согласование решений

### Стабильные обозначения

Каждый сегмент обозначает один уровень смысла: вид взаимодействия, область,
версию, ресурс, действие или модель. Не склеивать ресурс и действие и не
пропускать ресурс. Одинаковый контракт во всех presentation-документах имеет одно
обозначение независимо от имени файла; профильный скил уточняет допустимые
сегменты конкретного взаимодействия.

Предлагать пользователю отсутствующие транспортные ограничения и варианты, но не
делать их нормативными без согласования. За один подход задавать до пяти коротких,
до трёх средних либо один-два крупных связанных вопроса.

Каждый содержательный документ завершать разделом `## Открытые вопросы`. Если
вопросов нет, писать `Открытых вопросов нет.`. Не объявлять документ готовым,
если реализация потребует нового продуктового решения.

## Проверка

- Каждый контракт принадлежит одному владельцу и имеет нормативный документ.
- Внешние модели отделены от application DTO.
- Все внешние значения и результаты трассируются до application-контрактов.
- Domain не зависит от presentation и не раскрывается через него напрямую.
- Общие правила не расходятся между транспортами.
- Специализированные документы созданы соответствующими скилами.
- Навигация и ссылки ведут только к актуальным документам.
- Все входящие и внутренние driving entry points находятся под
  `presentation/` и представлены одним навигационным поддеревом.