ййй

2026-03-27 15:51:10 +03:00
parent 15586f9a8c
commit 0bff171936
1245 changed files with 99621 additions and 543076 deletions
@@ -0,0 +1,790 @@
+## 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;
+- ошибки;
+- НФТ;
+- связи;
+- кодовые привязки.
+
+## 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
+## 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. 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 документации;
+- глубокая автоматизация подготовки системной аналитики.