## 1. Формат ведения технической документации агентом

## 1.1. Общие принципы

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

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

## 1.2. Требования к заголовкам

- Заголовок должен отражать только суть раздела.
- Заголовок не должен содержать метаданные (`id`, `doc_type`, `application`, `platform`, `domain`, `sub_domain`).
- Метаданные указываются отдельными строками в теле раздела или в YAML frontmatter.

Пример:
- правильно: `## 6.2 Метод UFS получения списка заказов`
- неправильно: `## 6.2 Блок api_method (id=..., platform=ufs)`

## 1.3. Базовые типы документных единиц

Базовые типы:
- `ui_page`
- `api_method`
- `logic_block`

Дополнительно могут использоваться:
- `architecture_overview`
- `integration_doc`
- `domain_entity`
- `glossary_item`
- `index_page`

## 1.4. Принцип декомпозиции страниц / файлов

### Один устойчивый объект - один документ
Если объект можно переиспользовать или на него могут ссылаться другие документы, его нужно выносить в отдельный файл.

### Документы не должны пересекаться по смыслу
Если описание повторяется в нескольких местах, нужно выделять общий документ и ссылаться на него.

### Use case и детали живут раздельно
Сценарий описывает поток работы, а детали выносятся в функциональные требования, отдельные блоки логики или контрактные описания.

## 1.5. Иерархическая организация документации

Документация должна быть организована как иерархическое дерево каталогов и файлов.

Пример:

```text
docs/
  ui/
  api/
  logic/
  domains/
  integrations/
  architecture/
  glossary/
  errors/
```

## 1.6. Учет связей между документами

Связи должны быть явными.

Примеры:
- UI-страница ссылается на вызываемые API;
- API-документ ссылается на используемые блоки логики;
- логический блок ссылается на интеграции;
- документ по коду ссылается на системную аналитику, инициировавшую изменения.

## 1.7. Формат markdown-документов

Каждый документ состоит из:
1. YAML frontmatter;
2. Markdown body.

## 1.8. YAML frontmatter

### Обязательные поля
- `id`
- `title`
- `doc_type`
- `status`
- `domain`
- `sub_domain`
- `related_docs`

### Рекомендуемые поля
- `owner`
- `entities`
- `tags`
- `feature`
- `system_analytics_refs`
- `source_of_truth`
- `related_code`

### Допустимые значения `doc_type`
- `ui_page`
- `api_method`
- `logic_block`
- `architecture_overview`
- `integration_doc`
- `domain_entity`
- `glossary_item`
- `index_page`

### Допустимые значения `status`
- `draft`
- `in_review`
- `approved`
- `outdated`
- `generated`
- `active`

## 1.9. Синхронизация с системной аналитикой

Техническая документация строится на основе системной аналитики (features).

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

Если атрибуты или детали отсутствуют в аналитике:
- определить их из текста аналитики;
- дополнить данными из репозитория (код, контракты, существующие документы);
- зафиксировать итог в документации как явные метаданные и требования.

## 1.10. Формат body-разделов для блока изменений

Для секции изменений (по аналогии с разделом `6` в аналитике) использовать единый формат.

Под корнем секции изменений указывать общие атрибуты:
- `domain`
- `sub_domain`

Для каждого подраздела `X.Y` указывать метаданные строками сразу после заголовка:
- `id`
- `doc_type`
- `application`
- `platform`

## 1.11. Различие аналитики и документации

- Аналитика - концептуальный уровень, упрощенный use case.
- Документация - детальный инженерный уровень.

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

Источник правил:
- `src/app/core/agent/processes/v2/doc_rules_v2/common-elements/tech-use-case.md`
- `src/app/core/agent/processes/v2/doc_rules_v2/common-elements/fr.md`

## 1.12. Требования к `ui_page`

Обязательная структура:
- `### Технический use case`
- `### Требования к UI`
- `### Функциональные требования`
- `### Нефункциональные требования`

### Требования к UI
Внутри обязательно отдельно описывать каждую форму UI:
- табличное представление;
- пустой список (empty state);
- ошибка (error state).

Обязательные правила:
- если есть интеграция, обязательно описать показ ошибки;
- если показывается список, обязательно описать показ отсутствия данных.

### UI-элементы
UI-поля и элементы в документации описываются строго в таблицах.

Обязательные колонки (заполнять там, где применимо):
- `Код элемента`
- `Название и описание`
- `Данные`
- `Поведение`
- `Валидация`

## 1.13. Пользовательская аналитика для `ui_page`

События пользовательской аналитики оформляются таблицей:
- `Название события`
- `Описание`
- `Точка вызова`
- `Payload`

## 1.14. Требования к `api_method`

Обязательная структура:
- `### Технический use case`
- `### Функциональные требования`
- `### Нефункциональные требования`
- `### Контракт`

### Технический use case
Оформляется детально по правилам `tech-use-case.md`.

Обязательные части:
- название
- предусловия
- триггер
- основной сценарий
- альтернативный сценарий
- обработка ошибок
- постусловие

### Функциональные требования
Оформляются по правилам `fr.md`:
- формат `FR.<номер>. <Название>`;
- FR расширяют use case;
- FR не дублируют шаги сценария без дополнительной ценности;
- для интеграционных шагов FR обязательны.

## 1.15. Нефункциональные требования для `api_method`

Разделять на подразделы:
- `#### Аудит` (если применимо)
- `#### Мониторинг`

### Мониторинг
Оформлять таблицей:
- `Метрика`
- `Описание`
- `Условие срабатывания`

Правила:
- в условиях указывать, при каких состояниях фиксируется событие;
- не использовать формулировку вида «точка измерения = метод»;
- базово закладывать метрики:
  - `<METRIC_NAME>_SUCCESS`
  - `<METRIC_NAME>_FAIL`
  - `<METRIC_NAME>_BUSINESS_ERROR`

## 1.16. Распределение ответственности по слоям

- Проверка ролевой модели пользователя обычно выполняется в `ufs`.
- Для `pprb` аудит может не фиксироваться, если это согласовано правилами домена.
- Если проверка ролей вынесена в `ufs`, не дублировать этот шаг в use case `pprb`.

## 1.17. Контракты API

Контракт может быть:
- в markdown-таблицах;
- в OpenAPI;
- в отдельном контрактном файле.

Для markdown-контракта минимум:
- endpoint/method;
- request fields;
- required/optional;
- constraints;
- response;
- errors;
- auth;
- retry;
- timeout;
- idempotency.

## 1.18. Integrations-блок

Если у документа есть интеграции, выделять отдельный `## Integrations`.

Рекомендуемые атрибуты интеграции:
- `target`
- `target_type`
- `direction`
- `interaction`
- `via`
- `purpose`
- `details`

## 1.19. Общие требования к markdown body

- В документе должен быть один `H1`, совпадающий с `title`.
- Основные разделы - `H2`, подразделы - `H3`.
- Не допускать хаотичной вложенности заголовков.
- Вместо дублирования использовать ссылки на связанные документы.
- Сценарии, правила, ограничения и кодовые привязки держать раздельно.