sber/agent
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
agent/_process/04. Analitycs artefacts - documentation.md
T

12 KiB
Raw Permalink Blame History

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. Иерархическая организация документации

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

Пример:

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 View Git Blame Copy Permalink