# Message Consumer Documentation Writing

> Проектирование, создание, адаптация и ревью аналитической Markdown-документации входящих сообщений presentation-слоя: источника и адресации, envelope и payload, доверия, преобразования в application-вход, исходов обработки, повторной доставки, идемпотентности, порядка, свежести и совместимости. Использовать для NATS, Kafka, очередей и других message consumer-контрактов без привязки к клиентской библиотеке. Не использовать для publisher-адаптеров, runtime фонового процесса, application/domain-контрактов или реализации consumer-а.

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

---


# Документирование входящих сообщений

Документировать сообщение как внешнюю точку входа presentation, а не как цикл
воркера или конфигурацию брокерного клиента.

Перед работой читать [consumer-contract.md](references/consumer-contract.md) и
[review-checklist.md](references/review-checklist.md).

## Граница

Одно сообщение по умолчанию вызывает одну публичную application-операцию.
Envelope и payload являются внешними моделями и не передаются как application DTO.
Application-результат не публикуется автоматически; исходящее сообщение имеет
собственный контракт и адаптер.

Не описывать подключение, пул соединений, параллелизм runtime, библиотеку,
хранилище дедупликации или жизненный цикл процесса.

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

Размещать документы входящих сообщений внутри `presentation/messages/`.
Группировать по внешнему источнику или устойчивой группе контрактов, когда это
помогает навигации. Исходящие сообщения сюда не помещать: они принадлежат
`external-contracts/outgoing/`.

Формировать только поддерево «Входящие сообщения», начиная с
`presentation/messages/README.md`. Не создавать общий корень `messages` или
`external-contracts/messages`, смешивающий направления.

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

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

Использовать схему
`<контекст>.presentation.messages.<источник>.<ресурс или факт>.<действие или версия>`.
Источник, ресурс и действие являются отдельными смысловыми сегментами; не
склеивать их и не пропускать ресурс. Одинаковый контракт сообщения во всех
документах имеет одно обозначение независимо от адреса и имени файла.

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

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

## Готовность

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

Разделы `Назначение`, `Источник` и `Доверие` оформлять отдельно. Один файл
описывает один ресурс или одно семейство однородных фактов с одной моделью;
проекции разных объектов и команды создания агрегатов не объединять в файл.