290 lines
12 KiB
Markdown
290 lines
12 KiB
Markdown
## 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`.
|
||
- Не допускать хаотичной вложенности заголовков.
|
||
- Вместо дублирования использовать ссылки на связанные документы.
|
||
- Сценарии, правила, ограничения и кодовые привязки держать раздельно.
|