agent/_process/04. Analitycs artefacts.md

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

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

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

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

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

```text
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`.

Каждый документ состоит из двух частей:
1. **YAML frontmatter** — структурные метаданные;
2. **Markdown body** — основное содержимое по шаблону.

## 3.7. YAML frontmatter

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

### Базовый frontmatter

```yaml
---
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)

### Рекомендуемые поля
- `owner`
- `entities`
- `tags`
- `parent`
- `children`
- `feature`
- `system_analytics_refs`
- `business_refs`
- `updated_from`
- `reviewers`
- `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`

### Допустимые значения `source_of_truth`
- `code`
- `doc`
- `system_analysis`
- `business_requirements`
- `mixed`

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

У каждого типа документа есть:
- **общие поля**;
- **тип-специфичные поля**.

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

```yaml
---
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 строк;
- без длинных пояснений;
- только ключевые факты.

Пример:

```md
## 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;
- integrations;
- ошибки;
- НФТ;
- связи;
- кодовые привязки.

### Блок `## Integrations`

Если у объекта есть интеграции, они должны быть выделены в отдельный блок `## Integrations`.
Интеграции не нужно дублировать во frontmatter.
Основное описание хранится в body документа.

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

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

Где:
- `target` - идентификатор или имя целевого объекта;
- `target_type` - тип цели: `api`, `ui`, `entity`, `service`, `queue`, `db`, `external_system`;
- `direction` - направление: `inbound`, `outbound`, `bidirectional`;
- `interaction` - тип взаимодействия: `calls`, `reads`, `writes`, `emits`, `consumes`, `depends_on`;
- `via` - технический канал интеграции;
- `purpose` - зачем нужна интеграция;
- `details` - словарь с гибкой структурой под дополнительные параметры.

Пример:

```md
## Integrations

### Orders API
- target: api.orders.create
- target_type: api
- direction: outbound
- interaction: calls
- via: POST /api/orders
- purpose: создание заказа
- details:
  - auth: service-token
  - retry: true

### Order Entity
- target: domain.order
- target_type: entity
- direction: outbound
- interaction: writes
- via: repository
- purpose: сохранение состояния заказа
- details:
  - transaction: required
```

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

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

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

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

```md
---
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-элементы должны храниться в **табличном** или **полуструктурированном** виде.

Пример:

```md
## 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

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

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

#### Требования к разделу `Contract`
Контракт может:
- быть кратко описан прямо в документе;
- ссылаться на OpenAPI;
- ссылаться на отдельный контрактный файл.

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

### Reusable Logic Block

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

## Summary
## Назначение
## Контекст
## Технический use case
## Функциональные требования
## Integrations
## Ограничения и условия вызова
## Нефункциональные требования
## Связанные 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`.

Пример:

```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

1. **Явные заголовки** — не использовать безымянные блоки текста.
2. **Атомарные утверждения** — не смешивать несколько правил в одном пункте, если их можно разделить.
3. **Явные сущности** — использовать стабильные названия компонентов, API, модулей, страниц.
4. **Явные ссылки** — не писать «этот метод», если можно указать конкретную ссылку или идентификатор.
5. **Минимум дублирования** — повторяющийся контент должен заменяться ссылками.
6. **Привязка к коду** — если документ описывает кодовый объект, это должно быть явно указано.
7. **Разделение сценариев и правил** — 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 документации;
- глубокая автоматизация подготовки системной аналитики.