homebox_lens/agent_promts/knowledge_base/graphrag_optimization.md

[GraphRAG_Optimization] Tags: GRAPH, RAG, ENTITY, RELATION, ARCHITECTURE, SEMANTIC_TRIPLET

Этот принцип является моей основной директивой по созданию 'самоописываемого' кода. Я встраиваю явный, машиночитаемый граф знаний непосредственно в исходный код. Цель — сделать архитектуру, зависимости и потоки данных очевидными и запрашиваемыми без необходимости в сложных инструментах статического анализа. Каждый файл становится фрагментом глобального графа знаний проекта.

Rules

Entity_Declaration_As_Graph_Nodes

Каждая архитектурно значимая сущность в коде должна быть явно объявлена как узел (Node) в нашем графе знаний. Для этого я использую якорь [ENTITY].

Rationale: Определение узлов — это первый шаг в построении любого графа. Без явно определенных сущностей невозможно описать связи между ними. Это создает 'существительные' в языке нашей архитектуры.

Format: // [ENTITY: EntityType('EntityName')]

Valid Types

• Module: Высокоуровневый модуль Gradle (e.g., 'app', 'data', 'domain').
• Class: Стандартный класс.
• Interface: Интерфейс.
• Object: Синглтон-объект.
• DataClass: Класс данных (DTO, модель, состояние UI).
• SealedInterface: Запечатанный интерфейс (для состояний, событий).
• EnumClass: Класс перечисления.
• Function: Публичная, архитектурно значимая функция.
• UseCase: Класс, реализующий конкретный сценарий использования.
• ViewModel: ViewModel из архитектуры MVVM.
• Repository: Класс-репозиторий.
• DataStructure: Структура данных, которая не является DataClass (e.g., Pair, Map).
• DatabaseTable: Таблица в базе данных Room.
• ApiEndpoint: Конкретная конечная точка API.

Example:

// [ENTITY: ViewModel('DashboardViewModel')]
class DashboardViewModel(...) { ... }

Relation_Declaration_As_Graph_Edges

Все взаимодействия и зависимости между сущностями должны быть явно объявлены как ребра (Edges) в нашем графе знаний. Для этого я использую якорь [RELATION] в формате семантического триплета.

Rationale: Ребра — это 'глаголы' в языке нашей архитектуры. Они делают неявные связи (как вызов метода или использование DTO) явными и машиночитаемыми. Это позволяет автоматически строить диаграммы зависимостей, анализировать влияние изменений и находить архитектурные проблемы.

Format: // [RELATION: 'SubjectType'('SubjectName')] -> [RELATION_TYPE] -> ['ObjectType'('ObjectName')]

Valid Relations

• CALLS: Субъект вызывает функцию/метод объекта.
• CREATES_INSTANCE_OF: Субъект создает экземпляр объекта.
• INHERITS_FROM: Субъект наследуется от объекта (для классов).
• IMPLEMENTS: Субъект реализует объект (для интерфейсов).
• READS_FROM: Субъект читает данные из объекта (e.g., DatabaseTable, Repository).
• WRITES_TO: Субъект записывает данные в объект.
• MODIFIES_STATE_OF: Субъект изменяет внутреннее состояние объекта.
• DEPENDS_ON: Субъект имеет зависимость от объекта (e.g., использует как параметр, DTO, или внедряется через DI). Это наиболее частая связь.
• DISPATCHES_EVENT: Субъект отправляет событие/сообщение определенного типа.
• OBSERVES: Субъект подписывается на обновления от объекта (e.g., Flow, LiveData).
• TRIGGERS: Субъект (обычно UI-событие или компонент) инициирует выполнение объекта (обычно функции ViewModel).
• EMITS_STATE: Субъект (обычно ViewModel или UseCase) является источником/производителем определённого состояния (DataClass).
• CONSUMES_STATE: Субъект (обычно UI-компонент или экран) потребляет/подписывается на определённое состояние (DataClass).

Example:

// Пример для ViewModel, который зависит от UseCase и является источником состояния
// [ENTITY: ViewModel('DashboardViewModel')]
// [RELATION: ViewModel('DashboardViewModel')] -> [DEPENDS_ON] -> [UseCase('GetStatisticsUseCase')]
// [RELATION: ViewModel('DashboardViewModel')] -> [EMITS_STATE] -> [DataClass('DashboardUiState')]
class DashboardViewModel @Inject constructor(
    private val getStatisticsUseCase: GetStatisticsUseCase
) : ViewModel() { ... }

MarkupBlockCohesion

Вся семантическая разметка, относящаяся к одной сущности ([ENTITY] и все ее [RELATION] триплеты), должна быть сгруппирована в единый, непрерывный блок комментариев.

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

Placement: Этот блок всегда размещается непосредственно перед KDoc-блоком сущности или, если KDoc отсутствует, перед самой декларацией сущности. [/End GraphRAG_Optimization]