agent/README.md

# Agent for Code-Aware Technical Documentation and Analysis

## 1. Цели проекта

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

### 1.1. Практическая цель

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

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

### 1.2. Стадии развития

#### Стадия 1
Агент пишет и актуализирует **техническую документацию** на основе:
- кодовой базы;
- существующей технической документации;
- системной аналитики на фичи;
- при необходимости — бизнес-требований.

#### Стадия 2
Агент дополнительно начинает участвовать в подготовке **системной аналитики** на доработки, используя:
- бизнес-требования;
- существующую архитектуру;
- кодовую базу;
- текущую техническую документацию.

### 1.3. Ключевая идея проекта

Агент строится не как «чат над репозиторием», а как **intent-driven система с многослойным RAG**.

Это означает, что:
- код индексируется как `symbols`, `relations`, `entrypoints` и связанные артефакты;
- документация индексируется как `sections`, `entities`, `facts`, `workflows` и `cross-links`;
- между кодом и документацией строятся явные мосты;
- ответы и документы формируются на основе evidence, а не свободной генерации.

### 1.4. Ключевые принципы

- **Evidence-first** — ответ и документ должны опираться на извлеченные артефакты.
- **Intent-driven retrieval** — выбор контекста зависит от домена и сценария.
- **Code и Docs — разные домены** — код и документацию нельзя одинаково индексировать и одинаково извлекать.
- **Явные связи важнее дублирования** — документы должны ссылаться друг на друга и на код, а не пересказывать один и тот же контент.
- **MVP должен быть узким** — сначала покрываются самые полезные сценарии, без попытки сразу построить полную универсальную систему.

### 1.5. Два уровня архитектурного описания

В документе одновременно фиксируются **целевая архитектура** и **текущий практический MVP-now**:

- **Target Architecture** описывает то, к чему проект идёт.
- **MVP-now** описывает то, что реально доводится сейчас через тесты.
- **MVP-now** не включает UI-интеграцию и не требует полного runtime orchestration.
- **MVP-now** фокусируется на:
  - IntentRouterV2;
  - code-first retrieval;
  - evidence gate;
  - LLM answer quality;
  - diagnostics.

**Target Architecture**

- full intent-driven agent;
- code + docs + cross-domain flows;
- runtime orchestration;
- docs generation;
- future support for system analysis generation.

**MVP-now**

- isolated `CODE_QA` test pipeline;
- IntentRouterV2 as canonical router;
- router-driven layered retrieval;
- evidence-first answer synthesis;
- diagnostics-first tuning;
- no UI dependency;
- docs retrieval is postponed.

### 1.6. Структура проекта (src layout)

Код приложения расположен в **`src/app`**. Импорты в коде — `from app.*`. Тесты добавляют `src` в `sys.path` через `tests/conftest.py`. Запуск API из корня: `PYTHONPATH=src uvicorn app.main:app --reload` или после `pip install -e .` — `uvicorn app.main:app --reload`. Запуск тестов: `pytest` из корня репозитория.

---

## 2. Процесс AS IS и TO BE

## 2.1. AS IS

### Общая схема текущего процесса

Сейчас системные аналитики получают на вход **бизнес-требования** и формируют два основных типа артефактов:

1. **Системная аналитика на фичу**
2. **Техническая документация**

Эти артефакты решают разные задачи и живут в разной логике.

### 2.1.1. Артефакт 1 — системная аналитика на фичу

Системная аналитика описывает, **что именно необходимо изменить в системе**, чтобы реализовать инкремент функциональности, заданный бизнес-требованиями.

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

#### Характер системной аналитики в текущем процессе

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

То есть это не полная документация по системе, а **документ на инкремент изменений**, который использует текущий контекст, но не дублирует его полностью.

#### Типовой состав системной аналитики

1. **Цели доработки** — краткое описание цели изменения.
2. **Требования к реализации** — особые требования, которые важно явно подсветить и учесть.
3. **Ограничения и допущения** — рамки, предположения и известные ограничения решения.
4. **Архитектура** — внутренняя структура решения на уровне модулей и интеграций с другими АС.
5. **Функциональные требования к реализации** — перечень изменений, которые необходимо внести в систему.
6. **Нефункциональные требования** — фичетогглы, безопасность, сопровождение, наблюдаемость и другие стандартные НФТ.
7. **Прочее** — дополнительная информация, полезная для реализации или согласования.

### 2.1.2. Артефакт 2 — техническая документация

Техническая документация описывает **то, как система работает**.

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

#### Текущие типы страниц технической документации

Сейчас используются три основных шаблона:
- **Фронтальная страница**
- **Метод API**
- **Переиспользуемый блок логики**

#### Шаблон: фронтальная страница

1. **Технический Use Case** — пошаговое описание процесса работы страницы UI.
2. **Описание UI** — макет с перечислением UI-элементов: кнопок, полей, тогглов и т.д. Для каждого элемента указываются описание, источник данных, дефолтное значение / placeholder, правила активации, поведение при активации, правила валидации.
3. **Функциональные требования** — вынесенные из use case требования, чтобы не перегружать сценарий деталями. Например: вызовы API, обработка ответов, логические блоки.
4. **НФТ** — например: события пользовательской аналитики, фичетогглы.

#### Шаблон: метод API

1. **Технический Use Case** — пошаговое описание работы эндпоинта.
2. **Функциональные требования** — дополнительные требования, вынесенные из основного сценария.
3. **Контракт эндпоинта** — описание контракта на отдельной странице или в составе текущего документа.
4. **НФТ** — например: аудит, мониторинг.

#### Шаблон: переиспользуемый блок логики

1. **Технический Use Case** — описание работы блока логики по шагам.
2. **Функциональные требования** — вынесенные дополнительные требования и правила.

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

### 2.1.3. Ограничения текущего процесса

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

## 2.2. TO BE

### 2.2.1. Общая схема целевого процесса

В целевом процессе формирование **системной аналитики** пока сохраняется в текущем виде, а основной фокус переносится на трансформацию процесса подготовки **технической документации**.

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

### 2.2.2. Что сохраняется без изменений на текущем этапе

На ближайшем этапе сохраняется текущая роль системной аналитики как документа на изменение.

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

### 2.2.3. Что меняется

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

Основной целевой стек представления:
- `Markdown` — основной формат описания;
- `OpenAPI` — для API-контрактов;
- `Mermaid` — для легких схем;
- `PlantUML` — для диаграмм, где это уместно;
- `draw.io` — как дополнительный визуальный формат там, где нужен richer diagramming.

### 2.2.4. Роль агента в целевом процессе

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

### 2.2.5. Следующий этап развития

В дальнейшем агент должен начать участвовать и в подготовке **системной аналитики**.

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

Из этого следуют проектные выводы:
- системная аналитика должна быть пригодна для машинного чтения;
- шаблон системной аналитики желательно постепенно нормализовать;
- в документе должны быть явно выделяемые сущности: цель изменения, точки изменений, затрагиваемые модули, API, UI, НФТ, ограничения, интеграции.

---

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

## 3.1. Общие принципы

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

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

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

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

Базовые типы:
- `ui_page`
- `api_method`
- `logic_block`

Позже могут добавиться:
- `architecture_overview`
- `integration_doc`
- `domain_entity`
- `glossary_item`
- `index_page`

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

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

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

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

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

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

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

## 3.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
```

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

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

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

Именно эта сеть ссылок затем индексируется в слоях:
- `D1_DOCUMENT_CATALOG`
- `D3_ENTITY_CATALOG`
- `D4_WORKFLOW_INDEX`
- `D5_REFERENCE_GRAPH`
- `D6_DOC_CODE_LINKS`

## 3.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
owner: system-analyst
source_of_truth: code
related_docs:
  - api-orders-create
  - logic-order-validation
related_code:
  - src/orders/ui/create_page.tsx
  - src/orders/api/orders_controller.py
entities:
  - Order
  - CreateOrder
tags:
  - ui
  - orders
  - creation
---
```

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

- `id` — стабильный уникальный идентификатор документа;
- `title` — человекочитаемый заголовок;
- `doc_type` — тип документа;
- `status` — статус документа;
- `source_of_truth` — основной источник истины;
- `related_docs` — ссылки на связанные документы;
- `related_code` — ссылки на кодовые артефакты, если они известны.

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

- `domain`
- `owner`
- `entities`
- `tags`
- `parent`
- `children`
- `feature`
- `system_analytics_refs`
- `business_refs`
- `updated_from`
- `reviewers`

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

## 3.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`
- `auth`
- `idempotent`
- `timeout_ms`
- `links.called_by`
- `links.uses_logic`
- `links.writes_db`
- `links.integrates_with`

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

- `route`
- `entry_points`
- `calls_api`
- `uses_logic`
- `feature_toggles`

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

- `called_from`
- `uses_logic`
- `reads_db`
- `writes_db`
- `integrates_with`

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

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

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

## 3.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

## Назначение

## Контекст

## Технический use case

## Функциональные требования

## Нефункциональные требования

## Связанные сущности

## Связанный код

## Связанные документы

## История изменений
```

## 3.12. Требования к разделам внутри документа

### `Назначение`
Коротко отвечает на вопрос: что это за объект и зачем он существует.

### `Контекст`
Описывает только тот контекст, который нужен для понимания документа: место в системе, связь с соседними компонентами, границы ответственности.

### `Технический use case`
Описывает последовательность работы объекта: шаги, ветвления, важные переходы, условия запуска, результаты выполнения.

### `Функциональные требования`
Содержит атомарные требования, правила и проверки, которые не нужно раздувать внутри use case.

### `Нефункциональные требования`
Содержит только НФТ: аудит, мониторинг, события аналитики, feature toggles, безопасность, сопровождение, observability.

### `Связанные сущности`
Нужен для явного перечисления доменных сущностей, API, UI, логических блоков, интеграций, конфигурационных объектов.

### `Связанный код`
Нужен для явной привязки документа к коду: файлы, модули, классы, функции, handlers, entrypoints.

### `Связанные документы`
Нужен для поддержки сети документов без дублирования содержания.

### `История изменений`
На MVP может быть простой: дата, источник изменения, что было обновлено.

## 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
## Errors
## Нефункциональные требования
## Связанные блоки логики
## Связанный код
## Связанные документы
## История изменений
```

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

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

### Reusable Logic Block

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

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

Пример:

```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.1. Общая идея

Агент строится как **intent-driven orchestration system**, а не как один общий prompt над репозиторием.

На верхнем уровне он состоит из следующих блоков:
1. **Router**
2. **Domain-specific graphs / pipelines**
3. **Layered RAG**
4. **Evidence gate**
5. **Answer / document synthesis**
6. **Diagnostics**

### 4.1.1. Укрупненная схема

```mermaid
flowchart TD
    U[User / Analyst Request] --> R[Router]
    R --> G1[Code Graphs]
    R --> G2[Docs Graphs]
    R --> G3[Cross-Domain Graphs]
    R --> G4[General Fallback Graph]

    G1 --> CRAG[CODE RAG]
    G2 --> DRAG[DOCS RAG]
    G3 --> CRAG
    G3 --> DRAG
    G4 --> CRAG
    G4 --> DRAG

    CRAG --> E[Evidence Gate]
    DRAG --> E
    E --> S[Synthesis Layer]
    S --> O[Answer / Generated Docs]
    E --> D[Diagnostics]
    S --> D
```

### 4.1.2. Разделение на Target Architecture и MVP-now

**Target Architecture**

- Router
- Graphs / pipelines для `CODE`, `DOCS`, `CROSS_DOMAIN`, `GENERAL`
- CODE RAG + DOCS RAG
- evidence gate
- synthesis layer
- diagnostics
- генерация технической документации из code / docs / system analysis
- перспектива генерации системной аналитики

**MVP-now**

- изолированный test-first пайплайн;
- цепочка: `user query → IntentRouterV2 → retrieval plan → layered retrieval → evidence gate → LLM answer → diagnostics`;
- основной домен: `CODE`;
- основные сценарии:
  - `OPEN_FILE`
  - `EXPLAIN`
  - `FIND_TESTS`
  - `FIND_ENTRYPOINTS`
  - `GENERAL_QA`
- UI-интеграция не требуется для текущего этапа;
- docs retrieval не обязателен для текущего milestone;
- legacy `RouterService` не считается целевой архитектурой и в перспективе будет заменён.

```mermaid
flowchart TD
    U[User Query] --> R[IntentRouterV2]
    R --> P[Retrieval Plan]
    P --> G[Layered Retrieval]
    G --> E[Evidence Gate]
    E --> A[LLM Answer]
    E --> D[Diagnostics]
    A --> D
```

Текущий milestone — test-first и code-first; этот пайплайн настраивается изолированно до интеграции в полный agent runtime.

### 4.1.3. Канонический test-first пайплайн (CODE_QA)

Единая точка входа изолированного пайплайна — пакет `app.modules.rag.code_qa_pipeline`:

- **Роутер:** только `IntentRouterV2`; legacy `RouterService` не используется.
- **Контракты:** `RouterResult` (IntentRouterResult), `RetrievalRequest`, `RetrievalResult`, `EvidenceBundle`, `AnswerSynthesisInput`, `DiagnosticsReport`.
- **Цепочка:** запрос → IntentRouterV2 → RetrievalRequest → layered retrieval (через адаптер) → нормализованный RetrievalResult → EvidenceBundle → evidence gate → AnswerSynthesisInput → diagnostics.
- **Evidence gate:** общая проверка достаточности evidence по сценарию (OPEN_FILE, EXPLAIN, FIND_TESTS, FIND_ENTRYPOINTS, GENERAL_QA); при недостатке — degraded/insufficient, без уверенного ответа.
- **Диагностика:** Level 1 (summary) и Level 2 (detail), машинно-читаемые коды причин (`failure_reasons`: `target_not_resolved`, `path_scope_empty`, `layer_c0_empty`, `insufficient_evidence`, `tests_not_found`, `entrypoints_not_found` и др.).
- **Запуск пайплайна в тестах:** `CodeQAPipelineRunner(router=..., retrieval_adapter=...)`; метод `run(user_query, rag_session_id)` возвращает `CodeQAPipelineResult` с полной диагностикой.

Тесты: `tests/pipeline_setup/pipeline_intent_rag/test_canonical_code_qa_pipeline.py` (роутер → retrieval request, нормализованный результат, evidence gate, диагностика).

## 4.2. Router

Router определяет:
- домен запроса;
- intent;
- sub-intent;
- confidence;
- подходящий graph;
- требования к retrieval plan.

Целевые домены:
- `CODE`
- `DOCS`
- `CROSS_DOMAIN`
- `GENERAL`

## 4.3. Graphs / pipelines

Graph — это специализированный сценарий обработки запроса.

Для MVP целесообразны как минимум:
- `CodeOpenGraph`
- `CodeExplainGraph`
- `FindTestsGraph`
- `FindEntrypointsGraph`
- `DocsSearchGraph`
- `DocsGenerateFromCodeGraph`
- `CrossDomainLinkGraph`
- `GeneralFallbackGraph`

## 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 документации;
- глубокая автоматизация подготовки системной аналитики.