Настройка процесса генерации документации
This commit is contained in:
@@ -0,0 +1,289 @@
|
||||
## 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`.
|
||||
- Не допускать хаотичной вложенности заголовков.
|
||||
- Вместо дублирования использовать ссылки на связанные документы.
|
||||
- Сценарии, правила, ограничения и кодовые привязки держать раздельно.
|
||||
Reference in New Issue
Block a user