agent/_process/04. Analitycs artefacts.md at 5d77ab1a882160d811967e64fae70d8ec5d6e412

sber/agent

Fork 0

Files

T

alex 0bff171936 ййй

2026-03-27 15:51:10 +03:00

30 KiB

Raw Blame History

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

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

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

Ключевые принципы:

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

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

На первом этапе логично сохранить текущую семантику типов документов, но перенести ее в файловую модель.

Базовые типы:

ui_page
api_method
logic_block

Позже могут добавиться:

architecture_overview
integration_doc
domain_entity
glossary_item
index_page

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

Один устойчивый объект — один документ

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

Примеры:

отдельная UI-страница;
отдельный API endpoint;
отдельный блок логики;
отдельный интеграционный сценарий.

Документы не должны пересекаться по смыслу

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

Примеры:

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

Use case и детальные правила живут раздельно

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

Это важно и для RAG-индексации:

сценарии индексируются как workflows;
отдельные правила — как facts;
сущности и блоки — как entities.

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

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

Пример верхнего уровня:

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

Пример организации:

docs/
  ui/
    order-create-page.md
    order-edit-page.md
  api/
    orders-create.md
    orders-get.md
  logic/
    order-validation.md
    order-enrichment.md
  architecture/
    system-overview.md
    integration-landscape.md
  errors/
    catalog.yaml

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

Связи должны быть явными и поддерживаемыми агентом.

Примеры:

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

Именно эта сеть ссылок затем индексируется в слоях:

D1_DOCUMENT_CATALOG
D3_ENTITY_CATALOG
D4_WORKFLOW_INDEX
D5_REFERENCE_GRAPH
D6_DOC_CODE_LINKS

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

Основной формат технической документации — Markdown.

Каждый документ состоит из двух частей:

YAML frontmatter — структурные метаданные;
Markdown body — основное содержимое по шаблону.

3.7. YAML frontmatter

Frontmatter нужен для:

определения типа документа;
идентификации документа;
определения его места в иерархии;
фиксации связей с кодом и другими документами;
выделения сущностей и тегов;
упрощения построения слоев D1, D3, D5, D6.

Базовый frontmatter

---
id: ui-order-create-page
title: Страница создания заказа
doc_type: ui_page
domain: orders
status: draft
related_docs:
  - api-orders-create
  - logic-order-validation
entities:
  - Order
  - CreateOrder
tags:
  - ui
  - orders
  - creation
#owner: system-analyst
#source_of_truth: code
#related_code:
#  - src/orders/ui/create_page.tsx
#  - src/orders/api/orders_controller.py
---

Обязательные поля

id — стабильный уникальный идентификатор документа;
title — человекочитаемый заголовок;
doc_type — тип документа;
related_docs — ссылки на связанные документы;
status — статус документа;
domain - домен фичи (Карточка клиента, Задачи, Сделки, Предложения)
sub_domain - поддомен внутри основной сущности (Счета, ЗДА, ECM)

Допустимые значения `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

Допустимые значения `source_of_truth`

code
doc
system_analysis
business_requirements
mixed

1.8. Typed frontmatter для разных типов документов

У каждого типа документа есть:

общие поля;
тип-специфичные поля.

Пример для `api_method`

---
id: api.create_invoice
doc_type: api_method
domain: billing
title: Создание инвойса

endpoint: POST /api/v1/invoices
auth: USER
idempotent: false
timeout_ms: 3000

links:
  called_by:
    - ui.invoice_form
  uses_logic:
    - logic.invoice_validation
  writes_db:
    - db.invoices
    - db.invoice_items
  integrates_with:
    - int.crm_sync

related_docs:
  - ui.invoice_form
  - logic.invoice_validation
related_code:
  - services/billing/api/create_invoice.py
entities:
  - Invoice
  - CreateInvoice

tags:
  - invoice
  - create
  - billing
status: active
version: 1.3
source_of_truth: code
---

Для `api_method` полезно поддерживать

endpoint
sup_parameters
role_model_actions
monitoring_actions
audit_actions
idempotent
timeout_ms
links.called_by
links.uses_logic
links.writes_db
links.integrates_with

Для `ui_page` позже полезно поддерживать

calls_api
user_analitycs_actions
sup_parameters
role_model_actions
entry_points
uses_logic

Для `logic_block` полезно поддерживать

called_from
uses_logic
reads_db
writes_db
integrates_with

1.9. Двухслойная структура документа: `Summary` + `Details`

LLM не должна каждый раз тонуть в полном документе. Поэтому каждый документ должен содержать два уровня представления.

`Summary`

Короткая, строго структурированная спецификация. Это слой быстрого контекста.

Рекомендуемый объем:

примерно 30–60 строк;
без длинных пояснений;
только ключевые факты.

Пример:

## Summary
- Purpose: создание инвойса из формы
- Actor: пользователь
- Trigger: Submit
- Main API: POST /api/v1/invoices (api.create_invoice)
- Validation: required fields, amount > 0, date <= today
- Errors: 400(field errors), 409(duplicate), 503(retryable)
- Analytics: event invoice_submit, invoice_error

`Details`

Полное раскрытие объекта:

use case;
функциональные требования;
UI;
API;
ошибки;
НФТ;
связи;
кодовые привязки.

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

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

1.11. Базовый каркас markdown-документа

---
id: api-orders-create
title: Метод создания заказа
doc_type: api_method
domain: orders
status: draft
source_of_truth: code
related_docs:
  - logic-order-validation
  - ui-order-create-page
related_code:
  - src/orders/api/create_order.py
entities:
  - Order
  - CreateOrder
tags:
  - api
  - orders
---

# Метод создания заказа

## Summary
- Purpose: создание заказа
- Actor: пользователь
- Trigger: submit формы
- Main API: POST /orders

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


## 3.13. Специализированные шаблоны документов

### UI Page

```md
# <Название страницы>

## Summary
## Назначение
## Контекст
## Технический use case
## Описание UI
## UI Elements
## Функциональные требования
## Нефункциональные требования
## Связанные API
## Связанные блоки логики
## Связанный код
## Связанные документы
## История изменений

Требования к разделу `Описание UI`

Для каждого элемента желательно описывать:

тип элемента;
назначение;
источник данных;
default / placeholder;
правила активации;
поведение при взаимодействии;
валидацию.

Требования к разделу `UI Elements`

UI-элементы должны храниться в табличном или полуструктурированном виде.

Пример:

## UI Elements

| id     | type   | label   | data_source | validation | behavior |
|--------|--------|---------|------------|------------|----------|
| amount | input  | Amount  | local      | >0         | enables submit |
| submit | button | Create  | -          | -          | calls api.create_invoice |

Если модель UI сложная, допустим sidecar-файл ui_elements.yaml или ui_elements.json рядом с основным документом.

API Method

# <Название API метода>

## Summary
## Назначение
## Контекст
## Технический use case
## Функциональные требования
## Contract
## Errors
## Нефункциональные требования
## Связанные блоки логики
## Связанный код
## Связанные документы
## История изменений

Требования к разделу `Contract`

Контракт может:

быть кратко описан прямо в документе;
ссылаться на OpenAPI;
ссылаться на отдельный контрактный файл.

Для REST API целевым источником истины должен становиться OpenAPI.

Reusable Logic Block

# <Название блока логики>

## Summary
## Назначение
## Контекст
## Технический use case
## Функциональные требования
## Ограничения и условия вызова
## Нефункциональные требования
## Связанные API / UI / integration points
## Связанный код
## Связанные документы
## История изменений

3.14. Машинно-читаемые API-контракты

Для API контрактов источником истины должен становиться:

OpenAPI — предпочтительно;
либо временно строгий markdown/yaml-контракт, если OpenAPI еще нет.

Минимальный набор для API-контракта:

endpoint
method
request fields
required / optional
constraints
response
errors
idempotency
retry
timeout
auth

3.15. Каталог ошибок

Ошибки, HTTP-коды, retry-правила и клиентское поведение не должны размазываться по разным документам.

Нужен единый каталог ошибок, например docs/errors/catalog.yaml.

Пример:

errors:
  - error_id: invoice_validation_failed
    http_code: 400
    internal_code: BILLING_400_01
    when: invalid request fields
    client_behavior: show field errors
    retry: false
    owner: billing

  - error_id: invoice_duplicate
    http_code: 409
    internal_code: BILLING_409_01
    when: duplicate invoice detected
    client_behavior: show duplicate warning
    retry: false
    owner: billing

  - error_id: crm_sync_unavailable
    http_code: 503
    internal_code: BILLING_503_02
    when: downstream CRM unavailable
    client_behavior: retry later
    retry: true
    owner: billing

В API- и logic-документах лучше ссылаться на error_id, а не заново подробно описывать каждую ошибку.

3.16. Требования к качеству документа для RAG

Явные заголовки — не использовать безымянные блоки текста.
Атомарные утверждения — не смешивать несколько правил в одном пункте, если их можно разделить.
Явные сущности — использовать стабильные названия компонентов, API, модулей, страниц.
Явные ссылки — не писать «этот метод», если можно указать конкретную ссылку или идентификатор.
Минимум дублирования — повторяющийся контент должен заменяться ссылками.
Привязка к коду — если документ описывает кодовый объект, это должно быть явно указано.
Разделение сценариев и правил — workflow и fact-like требования должны быть отделены.

3.17. Как структура markdown помогает RAG

frontmatter + заголовки → D1_DOCUMENT_CATALOG
entities, tags, устойчивые термины → D3_ENTITY_CATALOG
атомарные функциональные и нефункциональные требования → D2_FACT_INDEX
Технический use case → D4_WORKFLOW_INDEX
related_docs, явные ссылки → D5_REFERENCE_GRAPH
related_code, упоминания symbols и файлов → D6_DOC_CODE_LINKS
Summary → быстрый retrieval и short-form context для LLM

3.18. Принципы генерации документации агентом

Когда документ пишет агент, он должен:

сначала извлечь evidence из кода, системной аналитики и существующих документов;
определить тип документа;
заполнить frontmatter;
построить markdown body по шаблону;
явно указать связи с кодом и другими документами;
не дублировать уже существующее описание, если можно сослаться на него.

4.4. Layered RAG

RAG строится как система специализированных слоев для двух основных доменов:

CODE RAG
DOCS RAG

Каждый graph извлекает контекст не из одного общего индекса, а из нужного набора слоев в зависимости от intent.

4.5. Evidence gate

Перед синтезом ответа или документа агент должен проверять, хватает ли опоры.

Примеры:

найден ли symbol;
найдено ли достаточное количество code chunks;
есть ли supporting relations;
есть ли document evidence;
есть ли docs ↔ code mapping.

Если опоры недостаточно, агент должен:

деградировать в упрощенный режим;
честно фиксировать неполноту ответа;
при необходимости уходить в fallback.

4.6. Synthesis layer

На этом этапе LLM:

агрегирует найденные артефакты;
формирует объяснение;
пишет документ;
структурирует результат под нужный шаблон.

LLM не должна быть основным источником фактов. Фактическая основа должна приходить из RAG и диагностируемого pipeline.

4.7. Diagnostics

Система должна сохранять диагностический след:

какой graph был выбран;
какие слои использовались;
что было найдено;
где retrieval был слабым;
почему был выбран fallback;
какие evidence стали основой ответа.

4.8. Сценарии: Target Architecture vs MVP-now

4.8.1. Target Architecture

CODE

OPEN_FILE — открыть конкретный файл;
OPEN_SYMBOL — открыть класс / функцию / метод;
EXPLAIN — объяснить, как работает сущность или фрагмент;
FIND_TESTS — найти релевантные тесты;
FIND_ENTRYPOINTS — найти основные точки входа;
RELATED_CODE — найти связанные сущности и ближайший контекст.

DOCS

DOC_SEARCH — найти релевантный фрагмент документации;
DOC_EXPLAIN — кратко объяснить, что сказано в документации по теме;
DOC_ENTITY_LOOKUP — найти разделы, связанные с сущностью или компонентом;
GENERATE_DOCS_FROM_CODE — сформировать документацию по коду с нуля для модуля, класса, функции, компонента или сценария.

CROSS-DOMAIN

FIND_IMPLEMENTATION_BY_DOC — найти реализацию по описанию;
FIND_DOC_BY_CODE — найти документацию по коду;
COMPARE_DOCS_AND_CODE — базовое сопоставление документации и реализации.

GENERAL / FALLBACK

GENERAL_QA — общий сценарий ответа на вопрос, если домен или интент не удалось определить уверенно.

4.8.2. MVP-now

В текущем цикле фокус на сценариях:

OPEN_FILE
EXPLAIN
FIND_TESTS
FIND_ENTRYPOINTS
GENERAL_QA

DOCS и CROSS_DOMAIN остаются частью target architecture; в текущем цикле они не являются обязательной частью test-first MVP.

5. Структура слоев RAG

5.1. CODE RAG

C0 — Source Chunks

Назначение: базовые фрагменты исходного кода.
Единица: chunk кода.
Как формируется: исходные файлы обходятся и режутся на chunk’и с учетом структурных границ.
Статус в MVP: да.

C1 — Symbol Catalog

Назначение: каталог модулей, классов, функций, методов и других значимых сущностей.
Единица: symbol.
Как формируется: из AST и синтаксического разбора кода.
Статус в MVP: да.

C2 — Symbol Relations

Назначение: связи между symbols.
Единица: relation.
Как формируется: вторым проходом по AST и структурным зависимостям.
Статус в MVP: да, в ограниченном виде.

C3 — Entrypoints

Назначение: каталог точек входа системы.
Единица: entrypoint.
Как формируется: специализированными детекторами entrypoint-паттернов.
Статус в MVP: да, минимально.

C4 — Execution Paths

Назначение: типовые пути исполнения.
Единица: path.
Как формируется: поверх C2 и C3 через производную трассировку.
Статус в MVP: нет.

C5 — Test Mappings

Назначение: связи production code ↔ tests.
Единица: mapping.
Как формируется: по путям, именам, импортам и конвенциям проекта.
Статус в MVP: да, минимально.

C6 — Code Facts

Назначение: нормализованные факты из кода.
Единица: fact.
Как формируется: поверх C1–C3 как производный слой.
Статус в MVP: нет.

5.2. DOCS RAG

D0 — Document Chunks

Назначение: базовые фрагменты документации.
Единица: document chunk.
Как формируется: документы нормализуются и режутся на chunk’и с сохранением section path.
Статус в MVP: да.

D1 — Document Catalog

Назначение: каталог документов и разделов.
Единица: document node / section node.
Как формируется: из структуры документов и их заголовков.
Статус в MVP: да.

D2 — Fact Index

Назначение: атомарные факты из документации.
Единица: fact.
Как формируется: из D0/D1 через правила, шаблоны и при необходимости LLM extraction с валидацией.
Статус в MVP: частично.

D3 — Entity Catalog

Назначение: каталог сущностей и понятий документации.
Единица: entity / concept.
Как формируется: из устойчивых терминов, заголовков, словарей и нормализации повторяющихся сущностей.
Статус в MVP: да, минимально.

D4 — Workflow Index

Назначение: процедуры, сценарии, последовательности шагов.
Единица: workflow.
Как формируется: из use case, процессных разделов и последовательных описаний шагов.
Статус в MVP: нет.

D5 — Reference Graph

Назначение: граф ссылок между документами, секциями, сущностями и фактами.
Единица: reference link.
Как формируется: из явных и неявных cross-links между документами.
Статус в MVP: нет.

D6 — Doc-Code Links

Назначение: мост между документацией и кодом.
Единица: doc artifact ↔ code artifact link.
Как формируется: из имен, aliases, путей, устойчивых терминов и других надежных соответствий.
Статус в MVP: да, минимально.

5.3. Layer scope: Target Architecture vs MVP-now

5.3.1. Target Architecture

Полная карта слоёв:

CODE: C0–C6 (Source Chunks, Symbol Catalog, Symbol Relations, Entrypoints, Execution Paths, Test Mappings, Code Facts)
DOCS: D0–D6 (Document Chunks, Document Catalog, Fact Index, Entity Catalog, Workflow Index, Reference Graph, Doc-Code Links)

5.3.2. MVP-now

Обязательные сейчас:

C0_SOURCE_CHUNKS
C1_SYMBOL_CATALOG
C2_SYMBOL_RELATIONS
C3_ENTRYPOINTS

В облегчённом виде:

C5_TEST_MAPPINGS или C5-lite

Не блокируют текущий этап:

C4_EXECUTION_PATHS
C6_CODE_FACTS
весь docs runtime (слои D0–D6 в исполнении runtime)

Слои документации остаются частью target architecture; docs retrieval пока не обязателен для текущего code-first milestone.

6. Итоговая рамка MVP-now

Сейчас система должна стабильно работать в test-first режиме.

Фокус:

CODE_QA;
через тесты настраиваются:
- intent routing (IntentRouterV2);
- layered retrieval;
- evidence sufficiency;
- answer quality;
- diagnostics.

Не входят в текущий milestone:

UI-интеграция;
docs runtime;
полная интеграция orchestration переносится на следующий этап после стабилизации test pipeline.

В целевой архитектуре по-прежнему заложены:

уверенная работа с кодом, symbols, entrypoints, тестами;
ответ по документации и мост docs ↔ code;
генерация документации по коду;
fallback при неуверенном роутинге.

В MVP-now сознательно не включаются самые дорогие части:

полноценные execution paths для всей системы;
богатые fact-индексы по всем доменам;
полный reference graph документации;
глубокая автоматизация подготовки системной аналитики.

30 KiB Raw Blame History Unescape Escape

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

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

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

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

Один устойчивый объект — один документ

Документы не должны пересекаться по смыслу

Use case и детальные правила живут раздельно

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

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

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

3.7. YAML frontmatter

Базовый frontmatter

Обязательные поля

Рекомендуемые поля

Допустимые значения doc_type

Допустимые значения status

Допустимые значения source_of_truth

1.8. Typed frontmatter для разных типов документов

Пример для api_method

Для api_method полезно поддерживать

Для ui_page позже полезно поддерживать

Для logic_block полезно поддерживать

1.9. Двухслойная структура документа: Summary + Details

Summary

Details

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

1.11. Базовый каркас markdown-документа

Требования к разделу Описание UI

Требования к разделу UI Elements

API Method

Требования к разделу Contract

Reusable Logic Block

3.14. Машинно-читаемые API-контракты

3.15. Каталог ошибок

3.16. Требования к качеству документа для RAG

3.17. Как структура markdown помогает RAG

3.18. Принципы генерации документации агентом

4.4. Layered RAG

4.5. Evidence gate

4.6. Synthesis layer

4.7. Diagnostics

4.8. Сценарии: Target Architecture vs MVP-now

4.8.1. Target Architecture

CODE

DOCS

CROSS-DOMAIN

GENERAL / FALLBACK

4.8.2. MVP-now

5. Структура слоев RAG

5.1. CODE RAG

C0 — Source Chunks

C1 — Symbol Catalog

C2 — Symbol Relations

C3 — Entrypoints

C4 — Execution Paths

C5 — Test Mappings

C6 — Code Facts

5.2. DOCS RAG

D0 — Document Chunks

D1 — Document Catalog

D2 — Fact Index

D3 — Entity Catalog

D4 — Workflow Index

D5 — Reference Graph

D6 — Doc-Code Links

5.3. Layer scope: Target Architecture vs MVP-now

5.3.1. Target Architecture

5.3.2. MVP-now

6. Итоговая рамка MVP-now

30 KiB

Raw Blame History

Допустимые значения `doc_type`

Допустимые значения `status`

Допустимые значения `source_of_truth`

Пример для `api_method`

Для `api_method` полезно поддерживать

Для `ui_page` позже полезно поддерживать

Для `logic_block` полезно поддерживать

1.9. Двухслойная структура документа: `Summary` + `Details`

`Summary`

`Details`

Требования к разделу `Описание UI`

Требования к разделу `UI Elements`

Требования к разделу `Contract`