agent/info/documentation_concept.md

Концепция документации (Strong MVP, без связи с кодом)

1. Область применения

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

Включает:

• текущее состояние (as-is)
• целевые сценарии использования
• целевую модель документации
• расширенный frontmatter
• базовую структуру документа frontmatter + Summary + Details
• RAG-слои (без связи с кодом)

---

2. Текущее состояние (As-Is)

2.1 Источник истины

• Документация хранится в Confluence
• Основная модель — иерархия страниц
• Навигация через дерево страниц

2.2 Структура и связи

• Документы не атомарны
• Одна страница содержит несколько тем
• Используются перекрестные ссылки между страницами

2.3 Ограничения

• Нет типизации документов
• Нет структурированного metadata-слоя
• Связи не формализованы

---

3. Целевые сценарии использования

3.1 Поиск документации

Пользователь формулирует запрос, например: "как работает создание заказа".

Система должна:

• найти релевантные документы
• отобрать наиболее точные фрагменты
• учитывать тип документа, модуль и сущности

Результат:

• короткий список релевантных документов
• возможность перейти в детали

3.2 Объяснение (Explain)

Пользователь хочет понять:

• как работает компонент
• что делает API
• как устроен процесс

Система должна:

• взять summary документа
• дополнить его деталями из Details
• дать краткое и точное объяснение без лишнего текста

3.3 Поиск по сущности (Entity Lookup)

Пользователь ищет:

• где используется сущность
• какие документы с ней связаны

Система должна:

• найти все документы, где упоминается сущность
• показать связи между ними

3.4 Навигация по документации

Пользователь начинает с одного документа и хочет:

• понять контекст
• перейти к связанным частям

Система должна:

• использовать parent/children
• использовать links
• строить осмысленный путь по документации

3.5 Генерация документации

Система создает новый документ:

• по шаблону
• с корректным frontmatter
• с заполненными разделами Summary и Details

Результат:

• документ сразу пригоден для использования
• соответствует структуре системы

3.6 Актуализация документации

При изменениях документа:

• система должна обновить только нужные части
• сохранить структуру
• обновить frontmatter и Details

Результат:

• документ остается консистентным
• не происходит деградации структуры

3.7 Связывание документации

При создании или обновлении:

• система добавляет связи между документами
• формирует граф знаний

Результат:

• документы не изолированы
• появляется навигация и reasoning

---

4. Frontmatter (расширенный контракт)

id: api.create_order
type: api_method
name: create_order
title: Create order API

module: orders
layer: application

status: draft
updated_at: 2026-03-20

tags:
  - orders
  - api

entities:
  - Order
  - Cart

parent: orders_api
children: []

links:
  - type: related_api
    target: api.get_order

Назначение ключевых полей

• id — стабильный идентификатор документа
• type — тип документа
• title — человекочитаемое имя
• module — модуль или bounded context
• layer — слой системы
• status — состояние документа
• updated_at — дата последнего обновления
• tags — фильтрация и поиск
• entities — база для entity lookup
• parent / children — иерархия
• links — граф связей

Все сведения о связях, сущностях и навигации должны храниться во frontmatter. В теле документа отдельные разделы для связей, сущностей и навигации не создаются.

---

5. Структура документа (целевая)

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

• frontmatter
• контент

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

• # Summary
• # Details

5.1 Общие правила структуры

• Summary и Details всегда имеют заголовок уровня #
• других заголовков первого уровня в документе быть не должно
• Summary остается кратким и пригодным для explain
• Details заменяет прежние разделы Context и Основное описание
• внутренняя структура Details зависит от типа документа

5.2 Summary

Краткое описание на 3-6 строк. Используется для explain, краткого ответа и быстрого понимания сути документа.

5.3 Details

Раздел содержит полное содержательное описание документа. Состав подразделов определяется типом документа.

---

6. Типовая структура Details для API

Для документов типа api_method раздел # Details должен содержать следующие подразделы:

• ## Описание
• ## Сценарий
• ## Функциональные требования
• ## Нефункциональные требования
• ## Контракт

6.1 Описание

Короткое описание сути метода:

• какую работу он выполняет
• для чего предназначен

6.2 Сценарий

Сценарий описывается в формате технического use case и включает:

• название
• предусловия
• триггер
• основной сценарий
• альтернативный сценарий
• обработку ошибок
• постусловие

Правила для сценария:

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

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

Функциональные требования описываются как последовательность требований внутри одного документа.

Формат:

• FR-1
• FR-2
• FR-3

Правила:

• идентификаторы локальны для документа
• на них нельзя ссылаться извне как на сквозные идентификаторы
• каждое требование описывает отдельный обязательный аспект реализации

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

Нефункциональные требования описываются аналогично функциональным.

Формат:

• NFR-1
• NFR-2
• NFR-3

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

6.5 Контракт

Контракт должен быть пригоден для последующей сборки OpenAPI-спецификации.

Контракт описывает:

• входные параметры метода API
• выходные параметры
• структуру сообщения, как правило JSON
• обязательность полей
• типы полей
• ограничения на размер и формат
• назначение полей
• правила заполнения полей
• примеры данных

---

7. Базовая структура Details для остальных типов документов

Для всех типов документов, кроме api_method, на текущем этапе обязателен минимум:

• # Summary
• # Details

Дополнительные рекомендации по внутренней структуре Details для logic_block, architecture_overview, domain_entity и других типов будут заданы отдельно.

---

8. RAG слои (только документация)

D0 — Чанки документов

Полный текст + разбиение.

D1 — Каталог документов

• id
• type
• title
• module
• tags

D2 — Индекс фактов

Факты, извлеченные из документов.

D3 — Каталог сущностей

• сущности
• документы, где они используются

D4 — Индекс сценариев (Workflow)

• последовательности действий
• пользовательские сценарии

D5 — Граф связей

• связи между документами

---

9. Итог

Система документации:

• атомарные документы
• строгий frontmatter
• единая структура Summary + Details
• типовые правила для API-документов
• разделенные RAG-слои

Это позволяет:

• точно искать
• объяснять
• строить навигацию
• генерировать и обновлять документацию