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

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

Этот файл задаёт общие правила редактирования активной документации в `docs/**`.

`README.md` в каталогах документации используется как карта раздела для людей и быстрой навигации. `AGENTS.md` используется как локальная инструкция для агентов: что читать перед правками, куда класть новые документы и какие индексы обновлять.

## Обязательные источники

- Перед любыми изменениями в `docs/**` читать корневой `AGENTS.md`.
- Перед созданием нового документа читать `docs/templates/index.md` и выбирать подходящий шаблон из `docs/templates/**`.
- Перед изменением доменных документов читать `docs/domains/AGENTS.md`.
- Перед изменением сквозной платформенной документации читать `docs/platform/AGENTS.md`.
- Перед изменением каталогов пакетов, плагинов, ролей или шаблонов читать `docs/catalogs/AGENTS.md`.
- Перед изменением документации поставки или карты связей читать `docs/delivery/AGENTS.md`.
- Перед добавлением исследовательских материалов читать `docs/research/AGENTS.md`.
- Перед изменением шаблонов документации читать `docs/templates/AGENTS.md`.
- Перед изменением документационных submodule-источников читать `docs/external/AGENTS.md`.

## Правила размещения

- Сквозная каноника платформы живёт в `docs/platform/**`.
- Документы конкретного домена живут в `docs/domains/<domain>/**`.
- Документы каталогов пакетов, плагинов, руководящей документации, процессов `flow`, ролей и шаблонов промптов живут в `docs/catalogs/**`.
- Поставка, трассируемость и карты `Issue/PR ↔ документы` живут в `docs/delivery/**`.
- Исследования и исходные материалы, которые ещё не стали каноникой, живут в `docs/research/**`.
- Старые материалы из `deprecated/**` не копируются в активную документацию механически.

## Язык и стиль

- Документы писать по-русски там, где смысл не теряет точность.
- Английский оставлять для имён файлов, каталогов, API, протоколов, env, model id, code identifiers и устойчивых технических терминов без точного русского аналога.
- Не смешивать русский текст с лишними англицизмами.
- В теле продуктовых и руководящих документов не ссылаться на номера волн, Issue, PR, review threads, временные ветки и другие динамические сущности рабочего процесса.
- Динамические ссылки размещать во frontmatter-полях связей, в `docs/delivery/**`, картах `Issue/PR ↔ документы`, самих Issue/PR, QA/ops/SRE отчётах и delivery-планах.
- Если документ публикуется в PR на принятие, он должен отражать целевое состояние; merge PR считается фактом согласования.
- Если merge PR фиксирует согласование документа, перед merge в документе не должно оставаться результата текущего PR со статусом `в PR`, `на ревью` или временными формулировками рабочего процесса.
- Если документ фиксирует вариантную проработку и выбор ещё не сделан, это должно быть оформлено как явный ожидаемый выбор владельца, а не как временный статус текущего PR.

## Индексы и трассируемость

- Каждый новый документ сразу добавлять в индекс своей зоны.
- Не создавать единый большой `issue_map.md`.
- Для доменной работы обновлять `docs/delivery/issue-map/domains/<domain>.md`.
- Для отдельного рабочего среза обновлять только предназначенный для него файл карты, если такой файл уже задан в `docs/delivery/issue-map/**`.
- Общие индексы должны оставаться навигацией, а не местом для растущих таблиц.
