markdown KB

agent_promts/knowledge_base/graphrag_optimization.md

@@ -0,0 +1,76 @@
+[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:**
+```kotlin
+// [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:**
+```kotlin
+// Пример для 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]