---
doc_id: REF-CK8S-0002
type: governance
title: "kodex — правила ведения документации в программе рефакторинга"
status: active
owner_role: KM
created_at: 2026-04-21
updated_at: 2026-04-25
related_issues: [488]
related_prs: []
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-21-refactoring-wave0"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-21
---

# Правила ведения документации в программе рефакторинга

## Канонические зоны
### 1. `refactoring/**`
Рабочий источник истины новой версии платформы до тех пор, пока соответствующий домен не будет перенесён в `docs/**`.

### 2. `docs/**`
Боевой каталог канонической документации продукта после завершения и принятия соответствующего refactoring-среза.
После reset перед wave 7 активными внутри `docs/**` остаются `docs/design-guidelines/**`, `docs/templates/**`, `docs/media/**`, `docs/index.md` и новая структура wave 6.1.

Новая структура:
- `docs/platform/**` — сквозная продуктовая, архитектурная каноника платформы, а также правила поставки и эксплуатации;
- `docs/domains/**` — самодостаточные пакеты доменов, которые позже можно вынести в отдельные репозитории или пакеты документации;
- `docs/catalogs/**` — каталоги плагинов, пакетов руководящей документации, ролей и шаблонов промптов;
- `docs/delivery/issue-map/**` — раздельная карта связей `Issue/PR ↔ документы` по доменам и волнам;
- `docs/research/**` — новые исследовательские материалы, если они нужны для текущей каноники.

Плоские каталоги старой модели `docs/product`, `docs/architecture`, `docs/ops` и единый `docs/delivery/issue_map.md` не восстанавливаются.

### 3. `deprecated/**`
Архив старых документов, кода и инфраструктурных каталогов, которые были явно вытеснены новой каноникой.
Внутри него сохранены исходные корневые пути: `deprecated/docs/**`, `deprecated/services/**`, `deprecated/deploy/**`, `deprecated/proto/**`, `deprecated/libs/**`, `deprecated/cmd/**` и `deprecated/tools/**`.

### 4. Репозитории-источники руководящей документации
Отдельные руководящие пакеты документации могут иметь свой источник истины в репозиториях-источниках.

Для них действуют правила:
- канонический текст живёт в целевом репозитории руководящего пакета;
- в рабочий контур проекта, сервиса или самой платформы такой пакет попадает локальным checkout или импортом;
- агент всегда работает с локально доступной копией документации, а не с "виртуальным" внешним каталогом;
- задача самоулучшения руководящего пакета должна запускаться против целевого репозитория этого пакета.

## Правило вытеснения старых документов
- Нельзя держать два активных документа, которые описывают одну и ту же предметную область по-разному.
- После согласования нового домена:
  - новая версия переносится в `docs/**`;
  - старая версия уходит в `deprecated/**`;
  - индексы и ссылки обновляются в том же PR.
- Для reset-итераций применяется более жёсткий вариант: старая доменная документация и старая реализация физически вынесены в `deprecated/**` заранее, а активные доменные каталоги создаются заново по `docs/templates/**`.

## Языковая политика
- Документация и PR на русском языке.
- Там, где мысль можно выразить по-русски без потери точности, используется русский язык.
- Английский оставляется только для:
  - имён файлов, каталогов, API и протоколов;
  - нативных сущностей и полей провайдера (`provider-native`), если важно не потерять точный технический смысл;
  - model ids, env names, code identifiers.
- Смешивание русского текста с лишними англицизмами считается дефектом документа.

## Политика статусов и согласования
- Документ, который публикуется в PR на принятие, должен отражать целевое финальное состояние.
- Для таких документов не используется режим "на согласовании" внутри самого документа.
- Merge PR считается фактом согласования и фиксирует:
  - принятие текста;
  - принятие frontmatter-статуса;
  - принятие связанных решений и ссылок.

## Правило frontmatter для approval PR
- Для документов, которые входят в approval PR, допускается сразу указывать:
  - `status: active`;
  - `approvals.status: approved`.
- Источником факта согласования считается merge этого PR, а не дополнительная ручная правка документа после merge.

## Политика индексов и шумоподавления
- Каждый новый документ сразу добавляется в индекс своей зоны.
- Исторические справочные пакеты должны иметь явную пометку, что они нужны только для справки.
- Документы без роли в текущей канонике не переносятся вперёд механически; они либо архивируются, либо переоформляются в новый домен.
- Для пакетов руководящей документации и каталогов пакетов обязательно поддерживать индекс пакетов, их область применения и статус проверки, чтобы локальный импорт не превращался в хаотичный набор файлов из разных репозиториев.
- Для карты `Issue/PR ↔ документы` запрещён один быстрорастущий файл на весь проект. Обновлять нужно доменный файл `docs/delivery/issue-map/domains/<domain>.md` и файл активной волны `docs/delivery/issue-map/waves/<wave>.md`; общий индекс остаётся навигацией.

## `README.md` и `AGENTS.md` в документации
- `README.md` в каталогах документации является навигационной картой для людей: что лежит в разделе, какие документы доступны и куда идти дальше.
- `AGENTS.md` в каталогах документации является локальной инструкцией для агентов: что читать перед правками, куда класть новые документы и какие индексы обновлять.
- `README.md` не должен превращаться в процессную инструкцию для агентов.
- `AGENTS.md` не должен заменять человекочитаемую карту раздела.
- Новые локальные `AGENTS.md` добавляются только в зоны, где есть собственные правила размещения или приёмки документов.
- Если добавляется новый домен, агент должен следовать `docs/domains/AGENTS.md` и обновить доменный индекс, доменную карту связей и активную волновую карту.

## Минимальный ритуал при завершении доменного среза
1. Утвердить refactoring-версию документации.
2. Создать новую канонику в `docs/**` по шаблонам, не восстанавливая старые документы переносом из архива.
3. Архивировать старые конфликтующие документы.
4. Обновить индексы.
5. Обновить backlog и карту зависимостей.
