# Инструкции для агентов в `docs/domains/**`

## Назначение

`docs/domains/**` хранит самодостаточные пакеты документации по доменам платформы. Доменный пакет должен быть достаточно независимым, чтобы позже его можно было вынести в отдельный репозиторий или пакет документации.

## Перед изменениями

- Читать `docs/AGENTS.md`.
- Читать `docs/domains/README.md`.
- Читать `refactoring/03-domain-map.md`, если меняется список доменов, границы домена или ответственность домена.
- Читать `docs/templates/index.md` и выбирать шаблон под тип создаваемого документа.

## Куда класть документы

- Все документы конкретного домена размещаются в `docs/domains/<domain>/**`.
- В корне каждого домена должен быть `README.md` с назначением, границами и ссылками на документы домена.
- Продуктовые, архитектурные документы, а также документы поставки и эксплуатации домена создаются внутри каталога домена, если они относятся только к нему.
- Сквозные решения, которые затрагивают всю платформу, не дублируются в домене и должны жить в `docs/platform/**`.
- Каталоги пакетов, плагинов, ролей, процессов `flow` и шаблонов промптов не размещаются в домене, если они описывают общую систему каталогов.

## Как добавить новый домен

1. Проверить, что новый домен действительно нужен, а его ответственность нельзя добавить в существующий домен.
2. Обновить `refactoring/03-domain-map.md`, если домен становится частью канонической карты.
3. Создать `docs/domains/<domain>/README.md`.
4. Обновить `docs/domains/README.md`.
5. Создать или обновить `docs/delivery/issue-map/domains/<domain>.md`.
6. Обновить `docs/delivery/issue-map/index.md`, если появился новый доменный файл карты.
7. Обновить файл активного рабочего среза в `docs/delivery/issue-map/**`, если такой файл уже задан для текущей работы.

## Правила содержания

- Доменный документ описывает ответственность домена, его сущности, процессы, контракты, события, ограничения и связи с другими доменами.
- Междоменные связи описываются через контракты, события и зависимости, а не через прямое копирование чужих моделей.
- Нельзя плодить проектные сущности, если нативные сущности провайдера (`Issue`, `PR/MR`, комментарии, ветки, теги и связи) закрывают потребность.
- Если домен зависит от другого домена, ссылка должна вести на документ другого домена, а не пересказывать его целиком.
