ййй
This commit is contained in:
@@ -0,0 +1,126 @@
|
||||
# Процессы работы с документацией (AS IS / TO BE)
|
||||
|
||||
|
||||
## Основные артефакты системной аналитики
|
||||
Системные аналитики работают с 3 артефактами:
|
||||
|
||||
- бизнес-требованиями
|
||||
- системной аналитикой
|
||||
- технической документацией
|
||||
|
||||
|
||||
### Бизнес требования
|
||||
Описывает бизнес и пользовательские требования, пользователькие use case, макеты экранов.
|
||||
Сейчас не всегда оформляется как отдельный документ, часто этот шаг пропускается и требования фиксируются сразу в документе системной аналитики.
|
||||
|
||||
|
||||
### Системная аналитика
|
||||
Документ описыватет изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков. Так же этот документ проходит согласование с экспертами по архитектуре, безопасности, сопровождению.
|
||||
|
||||
Может описывать как целиком процесс (в случае реализации с нуля), так и инкремент, который вносит небольшие изменения в существующие процессы.
|
||||
|
||||
В данном документе содкржится вся информация по сути вносимых изменений, но отсутствует контекст о текущей реализации системы.
|
||||
|
||||
Состоит из разделов:
|
||||
- Цели - короткое описание какую проблему и для кого решаем.
|
||||
- Процесс AS IS и TO BE - фокус на изменения с точки зрения бизнес функций, без технической детализации.
|
||||
- Ограничения - ограничения и допущения в реализации.
|
||||
- Архитектура - описывает схему уровня контейнеров, основной фокус на интеграции между контейнерами и интеграционные сценарии.
|
||||
- Функциональные требования - описывают изменения в системе.
|
||||
- Нефункциональные требования - требования к аудиту, мониторингу, фичетоглам, пользовтелькой аналитике.
|
||||
|
||||
|
||||
### Техническая документация
|
||||
Техническая документация описывает реализацию системы. Эта информация используется командой разработки при проектировании и реализации новых фичей, понимании как работает система. Артефакт живет чуть впереди кода
|
||||
Представялет из себя иерархическую модель документов, сейчас реализованную в конфлюенсе.
|
||||
|
||||
Есть несколько типов страниц, каждая из которы описывает определенный тип функциональности
|
||||
|
||||
- UI страницы
|
||||
- API методы
|
||||
- БД
|
||||
- Логические блоки
|
||||
|
||||
#### UI страницы
|
||||
Описывают экран на UI.
|
||||
**Декомпозиция**
|
||||
Как правило на страницу с описанием выносится целый макет/страница фронтального приложения, с одной основной интеграцией и опционально вспомогательными интеграциями.
|
||||
Например - форма создания сущности. Есть вспомогательгные методы для полученяи правочников, использующихся при заполнении полей на форме, и вызов оснвного метода создания сущности.
|
||||
|
||||
Таким образом приложение декомпозируется на отдельные экраны, коотры свызываются между собой последовательно, но сами по себе являются независимыми
|
||||
|
||||
**Состав описания**
|
||||
Все разделы обязательны.
|
||||
Страница с описанием содержит:
|
||||
- Краткое описание
|
||||
- Технический use case
|
||||
- Описание макета с декомпозицией на компоненты + их поведение
|
||||
- Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
|
||||
- Нефункциональные требования - фичетоглы и события пользовательской аналитики
|
||||
|
||||
|
||||
#### API методы
|
||||
**Декомпозиция**
|
||||
На каждый метод API заводится отдельная страница.
|
||||
**Состав описания**
|
||||
Все разделы обязательны.
|
||||
Страница с описанием содержит:
|
||||
- Краткое описание
|
||||
- Технический use case
|
||||
- Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
|
||||
- Нефункциональные требования - фичетоглы и события пользовательской аналитики
|
||||
- Контракт метода - описание запроса и ответа. Для ответа так же приводится описание как заполнять поля.
|
||||
|
||||
#### БД
|
||||
**Декомпозиция**
|
||||
Сейсас это только странциа с описанием таблица. На каждую таблицу заводится отдельная страница.
|
||||
**Состав описания**
|
||||
Все разделы обязательны.
|
||||
Страница с описанием содержит:
|
||||
- Краткое описание
|
||||
- Таблица с офисанием физической модели данных
|
||||
|
||||
#### Логические блоки
|
||||
**Декомпозиция**
|
||||
На отдельную страницу может быть вынесен общий переиспользуемый блок логики. Это позволяет не дублировать его на страницах документации. Как правило соответствует реализации общего компонента в коде.
|
||||
**Состав описания**
|
||||
Часть разделов в описании может отсутствовать.
|
||||
- Краткое описание
|
||||
- Технический use case
|
||||
- Функциональные требования - описание интеграций и логики, специфичной для этой формы UI
|
||||
- Нефункциональные требования - фичетоглы и события пользовательской аналитики
|
||||
|
||||
#### Прочие особенности процесса
|
||||
##### Описание технических use cases
|
||||
Сценарий описывает основные шаги процесса в разрезе участников, все технические детали, если их нельзя описать одним предложением, выносятся в разделы функциональных требований, нефункциональных требований, или даются ссылки на другие страницы (как правило это страницы с логическими блоками).
|
||||
|
||||
В технических use cases приводятся ссылки на страницы с описнаием вызываемых методов API. Особенно это актуально для страниц фронта, т.к. он использует наши методы API, которые есть в документации. Для интеграций с другими АС как правило приводистя ссылка на описание конфлюенса.
|
||||
|
||||
|
||||
|
||||
## AS IS
|
||||
Сейчас все артефакты ведутся в конфлюенс. Одна страница содержит описанием одного аретфакта (бизнес требования, системная аналитика, страница документации), страницы организованы иерархически, используюстя ссылки для обозначения связей.
|
||||
|
||||
Проблемы:
|
||||
- документация со временем теряет актуальность
|
||||
- отсутствие автоматизации
|
||||
- ручное ведение
|
||||
---
|
||||
|
||||
## TO BE
|
||||
|
||||
Целевое состояние:
|
||||
- аналитик продолжает писать артефакты бизнес-требований и системной аналитики
|
||||
- агент генерирует и обновляет документацию по странице системной аналитики
|
||||
- документация становится инженерным артефактом, который ведется в GIT
|
||||
|
||||
### Форматы
|
||||
- Markdown
|
||||
- OpenAPI
|
||||
- Mermaid / PlantUML
|
||||
|
||||
### Роль агента
|
||||
- использование документации как базы знаний - как для ответов на вопросы, так и для проектирования изменений в системе.
|
||||
- внесение изменений в документацию по артефактам системной аналитики
|
||||
- генерация из документации спецификаций OPENAPI и JSON-schema
|
||||
|
||||
@@ -0,0 +1,235 @@
|
||||
Ниже обновленная версия с учетом гибридной модели интент роутера.
|
||||
|
||||
---
|
||||
|
||||
## 1. Концепция агента
|
||||
|
||||
Агент проектируется как intent-driven система для работы с кодом и документацией, где пользовательский запрос сначала нормализуется и интерпретируется, затем по нему извлекается релевантный контекст из многослойного RAG, после чего специализированный task workflow выполняет целевую задачу. Агент не является единым “умным чатом”: логика разделена на маршрутизацию, retrieval и специализированные execution workflows. Проверка evidence, вызовы LLM и правила сборки ответа находятся внутри task workflows и зависят от типа задачи.
|
||||
|
||||
---
|
||||
|
||||
## 2. Компонентная модель
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
IDE[IDE Plugin / Client] --> API[API Layer]
|
||||
API --> IR[IntentRouter V3]
|
||||
IR --> RAG[Retrieval RAG]
|
||||
|
||||
RAG --> TW1[Task Workflow: Documentation Explain]
|
||||
RAG --> TW2[Task Workflow: OpenAPI Generation]
|
||||
RAG --> TW3[Task Workflow: Documentation Generation]
|
||||
RAG --> TWN[Other Specialized Task Workflows]
|
||||
|
||||
TW1 --> OUT[Response / Artifact]
|
||||
TW2 --> OUT
|
||||
TW3 --> OUT
|
||||
TWN --> OUT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Основной flow процесса
|
||||
|
||||
### Основной процесс
|
||||
|
||||
1. Пользователь отправляет запрос через IDE plugin или другой клиент.
|
||||
2. `API Layer` принимает запрос и передает его в агент.
|
||||
3. `IntentRouter V3`:
|
||||
|
||||
* нормализует запрос;
|
||||
* детерминированно извлекает ключевые артефакты;
|
||||
* с помощью LLM определяет тип задачи и параметры обработки;
|
||||
* формирует параметры retrieval.
|
||||
4. Выполняется извлечение данных из `Retrieval RAG`.
|
||||
5. Извлеченный контекст передается в соответствующий `Task Workflow`.
|
||||
6. Внутри workflow выполняется:
|
||||
|
||||
* подготовка контекста;
|
||||
* evidence-проверки;
|
||||
* вызовы LLM;
|
||||
* формирование результата.
|
||||
7. Результат возвращается пользователю.
|
||||
|
||||
### Sequence diagram
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as User / IDE Plugin
|
||||
participant API as API Layer
|
||||
participant Router as IntentRouter V3
|
||||
participant RAG as Retrieval RAG
|
||||
participant WF as Task Workflow
|
||||
|
||||
User->>API: request
|
||||
API->>Router: agent call
|
||||
Router->>Router: normalize + extract artifacts
|
||||
Router->>Router: LLM routing (task / intent)
|
||||
Router->>RAG: retrieval request
|
||||
RAG-->>Router: retrieved context
|
||||
Router->>WF: route result + context
|
||||
WF->>WF: evidence logic + LLM calls
|
||||
WF-->>API: final result
|
||||
API-->>User: response
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Описание компонентов
|
||||
|
||||
### 4.1. IDE Plugin / Client
|
||||
|
||||
**Задача**
|
||||
Точка входа пользователя в агент.
|
||||
|
||||
**Как устроен**
|
||||
Любой внешний клиент (IDE plugin, web UI и др.), который отправляет запрос и получает результат.
|
||||
|
||||
**Почему так**
|
||||
Агент изначально проектируется как backend-система, независимая от интерфейса.
|
||||
|
||||
---
|
||||
|
||||
### 4.2. API Layer
|
||||
|
||||
**Задача**
|
||||
Обеспечивает внешний интерфейс взаимодействия с агентом.
|
||||
|
||||
**Как устроен**
|
||||
Принимает запрос, валидирует его и передает во внутренний pipeline, затем возвращает результат.
|
||||
|
||||
**Почему так**
|
||||
Позволяет изолировать транспортный слой от логики агента.
|
||||
|
||||
---
|
||||
|
||||
### 4.3. IntentRouter V3
|
||||
|
||||
**Задача**
|
||||
Определяет, как должен обрабатываться пользовательский запрос и какой сценарий выполнения применить.
|
||||
|
||||
**Как устроен**
|
||||
|
||||
Гибридная модель из двух частей:
|
||||
|
||||
#### 1. Детерминированный слой
|
||||
|
||||
Выполняет:
|
||||
|
||||
* нормализацию запроса;
|
||||
* извлечение ключевых артефактов:
|
||||
|
||||
* домены;
|
||||
* типы сущностей (API, entity, component и т.д.);
|
||||
* явные ссылки (endpoint, путь, имя);
|
||||
* выделение базовых сигналов (например: explain / list / generate).
|
||||
|
||||
Этот слой задает **жесткие рамки интерпретации запроса**.
|
||||
|
||||
#### 2. LLM-роутинг
|
||||
|
||||
Использует:
|
||||
|
||||
* нормализованный запрос;
|
||||
* извлеченные артефакты;
|
||||
* описание доступных типов задач;
|
||||
|
||||
и определяет:
|
||||
|
||||
* тип задачи;
|
||||
* общий сценарий обработки;
|
||||
* параметры retrieval;
|
||||
* ожидаемую форму ответа.
|
||||
|
||||
#### Итог
|
||||
|
||||
Router формирует:
|
||||
|
||||
* параметры retrieval;
|
||||
* тип task workflow;
|
||||
* контекст для дальнейшего выполнения.
|
||||
|
||||
**Почему решение такое**
|
||||
|
||||
Ранее использовался более детерминированный подход с фиксированными сценариями, который хорошо работал в узком наборе задач, но плохо масштабируется. Полностью LLM-based роутинг, наоборот, дает гибкость, но теряет предсказуемость и управляемость.
|
||||
|
||||
Поэтому выбран гибридный подход:
|
||||
|
||||
* детерминированный слой фиксирует ключевые артефакты и ограничения;
|
||||
* LLM выполняет гибкую интерпретацию задачи.
|
||||
|
||||
Это позволяет:
|
||||
|
||||
* сохранить управляемость и стабильность;
|
||||
* избежать взрывного роста количества сценариев;
|
||||
* поддерживать сложные и нетиповые запросы.
|
||||
|
||||
---
|
||||
|
||||
### 4.4. Retrieval RAG
|
||||
|
||||
**Задача**
|
||||
Извлечь релевантный контекст для выполнения задачи.
|
||||
|
||||
**Как устроен**
|
||||
Многослойная система хранения знаний (код, документация, факты, связи), из которой извлекается структурированный контекст в зависимости от параметров, заданных роутером.
|
||||
|
||||
**Почему так**
|
||||
Разные задачи требуют разных типов данных, поэтому используется слойная модель вместо плоского поиска.
|
||||
|
||||
---
|
||||
|
||||
### 4.5. Task Workflows
|
||||
|
||||
**Задача**
|
||||
Реализуют прикладную логику выполнения конкретного типа задачи.
|
||||
|
||||
**Как устроены**
|
||||
Набор специализированных workflows, например:
|
||||
|
||||
* объяснение по документации;
|
||||
* генерация OpenAPI;
|
||||
* генерация документации;
|
||||
* другие сценарии.
|
||||
|
||||
Внутри workflow находятся:
|
||||
|
||||
* обработка контекста;
|
||||
* evidence-проверки;
|
||||
* вызовы LLM;
|
||||
* сборка результата.
|
||||
|
||||
**Почему так**
|
||||
Логика проверки данных и генерации сильно зависит от задачи, поэтому она инкапсулируется в отдельных workflows, а не в одном универсальном слое.
|
||||
|
||||
---
|
||||
|
||||
### 4.6. Output / Artifact
|
||||
|
||||
**Задача**
|
||||
Вернуть результат пользователю.
|
||||
|
||||
**Как устроен**
|
||||
Может быть:
|
||||
|
||||
* текстовый ответ;
|
||||
* структурированный список;
|
||||
* OpenAPI спецификация;
|
||||
* документация;
|
||||
* иной артефакт.
|
||||
|
||||
**Почему так**
|
||||
Агент должен поддерживать не только ответы, но и генерацию инженерных артефактов.
|
||||
|
||||
---
|
||||
|
||||
## Итог
|
||||
|
||||
Обновленная архитектура строится на следующем принципе:
|
||||
|
||||
* **детерминированное извлечение ключевых артефактов** задает рамки;
|
||||
* **LLM выполняет гибкий роутинг внутри этих рамок**;
|
||||
* **retrieval обеспечивает данные**;
|
||||
* **task workflows реализуют прикладную логику и контроль качества**.
|
||||
|
||||
Это позволяет одновременно сохранить управляемость системы и обеспечить масштабируемость под новые типы задач.
|
||||
@@ -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 документации;
|
||||
- глубокая автоматизация подготовки системной аналитики.
|
||||
Reference in New Issue
Block a user