markdown KB

agent_promts/knowledge_base/ai_friendly_logging.md

@@ -0,0 +1,52 @@
+[AIFriendlyLogging]
+**Tags:** LOGGING, TRACEABILITY, STRUCTURED_LOG, DEBUG, CLEAN_ARCHITECTURE
+
+> Логирование — это мой критически важный механизм для декларации `belief state` (внутреннего состояния/намерения) и трассировки выполнения кода. Каждая значимая операция, проверка контракта или изменение состояния ДОЛЖНЫ сопровождаться структурированной записью в лог. Это делает поведение кода в рантайме полностью прозрачным и отлаживаемым.
+
+## Rules
+
+### ArchitecturalBoundaryCompliance
+Логирование в его прямой реализации (т.е. вызов `logger.info`, `Timber.i` и т.д.) **КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНО** внутри модуля `:domain`.
+
+> `Согласно принципам чистой архитектуры, слой `domain` должен быть полностью независим от внешних фреймворков и платформ (включая Android). Его задача — содержать исключительно бизнес-логику. Логирование, как и другие инфраструктурные задачи, должно выполняться в более внешних слоях, таких как `:data` или `:app`.`
+
+### StructuredLogFormat
+Все записи в лог должны строго следовать этому формату для обеспечения машиночитаемости и консистентности.
+
+```
+`logger.level("[LEVEL][ANCHOR_NAME][BELIEF_STATE] Message with {} placeholders for data.")`
+```
+
+### ComponentDefinitions
+
+#### Components
+- **[LEVEL]**: Один из стандартных уровней логирования: `DEBUG`, `INFO`, `WARN`, `ERROR`. Я также использую специальный уровень `CONTRACT_VIOLATION` для логов, связанных с провалом `require` или `check`.
+- **[ANCHOR_NAME]**: Точное имя семантического якоря из кода, к которому относится данный лог. Это создает неразрывную связь между статическим кодом и его выполнением. Например: `[ENTRYPOINT]`, `[ACTION]`, `[PRECONDITION]`, `[FALLBACK]`.
+- **[BELIEF_STATE]**: Краткое, четкое описание моего намерения в `snake_case`. Это отвечает на вопрос 'почему' я выполняю этот код. Примеры: `validating_input`, `calling_external_api`, `mutating_state`, `persisting_data`, `handling_exception`, `mapping_dto`.
+
+### Example
+Вот как я применяю этот стандарт на практике внутри функции:
+```kotlin
+// ...
+// [ENTRYPOINT]
+suspend fun processPayment(request: PaymentRequest): Result {
+    logger.info("[INFO][ENTRYPOINT][processing_payment] Starting payment process for request '{}'.", request.id)
+
+    // [PRECONDITION]
+    logger.debug("[DEBUG][PRECONDITION][validating_input] Validating payment request.")
+    require(request.amount > 0) { "Payment amount must be positive." }
+
+    // [ACTION]
+    logger.info("[INFO][ACTION][calling_external_api] Calling payment gateway for amount {}."), request.amount)
+    val result = paymentGateway.execute(request)
+
+    // ...
+}
+```
+
+### TraceabilityIsMandatory
+Каждая запись в логе ДОЛЖНА быть семантически привязана к якорю в коде. Логи без якоря запрещены. Это не опция, а фундаментальное требование для обеспечения полной трассируемости потока выполнения.
+
+### DataAsArguments_NotStrings
+Данные (переменные, значения) должны передаваться в логгер как отдельные аргументы, а не встраиваться в строку сообщения. Я использую плейсхолдеры `{}`. Это повышает производительность и позволяет системам сбора логов индексировать эти данные.
+[/End AIFriendlyLogging]

agent_promts/knowledge_base/design_by_contract.md

@@ -0,0 +1,35 @@
+[DesignByContractAsFoundation]
+**Tags:** DBC, CONTRACT, PRECONDITION, POSTCONDITION, INVARIANT, KDOC, REQUIRE, CHECK
+
+> Принцип 'Проектирование по контракту' (DbC) — это не опция, а фундаментальная основа моего подхода к разработке. Каждая функция и класс, которые я создаю, являются реализацией формального контракта между поставщиком (код) и клиентом (вызывающий код). Это устраняет двусмысленность, предотвращает ошибки и делает код самодокументируемым и предсказуемым.
+
+## Rules
+
+### ContractFirstMindset
+Я всегда начинаю с проектирования и написания KDoc-контракта. Код является реализацией этой формальной спецификации. Проверки контракта (`require`, `check`) создаются до или вместе с основной логикой, а не после как запоздалая мысль.
+
+### KDocAsFormalSpecification
+KDoc-блок является человекочитаемой формальной спецификацией контракта. Для правильной обработки механизмом Causal Attention, он ВСЕГДА предшествует блоку семантической разметки и декларации функции/класса. Я использую стандартизированный набор тегов для полного описания контракта.
+
+#### Tags
+- **@param**: Описывает **предусловия** для конкретного параметра. Что клиент должен гарантировать.
+- **@return**: Описывает **постусловия** для возвращаемого значения. Что поставщик гарантирует в случае успеха.
+- **@throws**: Описывает условия (обычно нарушение предусловий), при которых будет выброшено исключение. Это часть 'негативного' контракта.
+- **@invariant**: (для класса) Явно описывает **инвариант** класса — условие, которое должно быть истинным всегда, когда объект не выполняет метод.
+- **@sideeffect**: Четко декларирует любые побочные эффекты (запись в БД, сетевой вызов, изменение внешнего состояния). Если их нет, я явно указываю `@sideeffect Отсутствуют.`.
+
+### PreconditionsWithRequire
+Предусловия (обязательства клиента) должны быть проверены в самом начале публичного метода с использованием `require(condition) { "Error message" }`. Это реализует принцип 'Fail-Fast' — немедленный отказ, если клиент нарушил контракт.
+
+**Location:** Первые исполняемые строки кода внутри тела функции, сразу после лога `[ENTRYPOINT]`.
+
+### PostconditionsWithCheck
+Постусловия (гарантии поставщика) должны быть проверены в самом конце метода, прямо перед возвратом управления, с использованием `check(condition) { "Error message" }`. Это самопроверка, гарантирующая, что моя работа выполнена правильно.
+
+**Location:** Последние строки кода внутри тела функции, непосредственно перед каждым оператором `return`.
+
+### InvariantsWithInitAndCheck
+Инварианты класса (условия, которые всегда должны быть истинны для экземпляра) проверяются в двух местах: в блоке `init` для гарантии корректного создания объекта, и в конце каждого публичного метода, изменяющего состояние, с помощью `check(condition)`.
+
+**Location:** Блок `init` и конец каждого метода-мутатора.
+[/End DesignByContractAsFoundation]

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]

agent_promts/knowledge_base/semantic_linting.md

@@ -0,0 +1,76 @@
+[SemanticLintingCompliance]
+**Tags:** LINTING, SEMANTICS, STRUCTURE, ANCHORS, FILE_HEADER, TAXONOMY
+
+> Этот принцип определяет строгие правила структурирования кода, которые превращают его из простого текста в машиночитаемый, 'линтуемый' семантический артефакт. Моя задача — генерировать код, который не просто работает, но и на 100% соответствует этим правилам. Это не рекомендации по стилю, а строгие требования к архитектуре файла.
+
+## Rules
+
+### FileHeaderIntegrity
+Каждый `.kt` файл ДОЛЖЕН начинаться со стандартного заголовка из трех якорей, за которым следует объявление `package`. Порядок строгий и не подлежит изменению.
+
+**Rationale:** Этот заголовок служит 'паспортом' файла, позволяя любому инструменту (включая меня) мгновенно понять его расположение, имя и основное назначение, не парся код.
+
+**Example:**
+```kotlin
+// [PACKAGE] com.example.your.package.name
+// [FILE] YourFileName.kt
+// [SEMANTICS] ui, viewmodel, state_management
+package com.example.your.package.name
+```
+
+### SemanticKeywordTaxonomy
+Содержимое якоря `[SEMANTICS]` ДОЛЖНО состоять из ключевых слов, выбранных из предопределенного, контролируемого списка (таксономии).
+
+**Rationale:** Это устраняет неоднозначность и обеспечивает консистентность семантического тегирования по всему проекту, делая поиск и анализ на основе этих тегов надежным и предсказуемым.
+
+#### Example Taxonomy
+- **Layer**: `ui`, `domain`, `data`, `presentation`
+- **Component**: `viewmodel`, `usecase`, `repository`, `service`, `screen`, `component`, `dialog`, `model`, `entity`
+- **Concern**: `networking`, `database`, `caching`, `authentication`, `validation`, `parsing`, `state_management`, `navigation`, `di`, `testing`
+
+### EntityContainerization
+Каждая ключевая сущность (`class`, `interface`, `object`, `data class`, `sealed class`, `enum class` и каждая публичная `fun`) ДОЛЖНА быть обернута в 'семантический контейнер'. Контейнер состоит из двух частей: открывающего блока разметки ПЕРЕД сущностью и закрывающего якоря ПОСЛЕ нее.
+
+**Rationale:** Это превращает плоский текстовый файл в иерархическое дерево семантических узлов. Это позволяет будущим AI-инструментам надежно парсить, анализировать и рефакторить код, точно зная, где начинается и заканчивается каждая сущность.
+
+**Structure:**
+1.  **Открывающий Блок Разметки:** Располагается непосредственно перед KDoc/декларацией. Содержит сначала якорь `[ENTITY]`.
+2.  **Тело Сущности:** KDoc, сигнатура и тело функции/класса.
+3.  **Закрывающий Якорь:** Располагается сразу после закрывающей фигурной скобки `}` сущности. Формат: `// [END_ENTITY: Type('Name')]`.
+
+**Example:**
+```kotlin
+// [ENTITY: DataClass('Success')]
+/**
+ * @summary Состояние успеха...
+ */
+data class Success(val labels: List<Label>) : LabelsListUiState
+// [END_ENTITY: DataClass('Success')]
+```
+
+### StructuralAnchors
+Крупные, не относящиеся к конкретной сущности блоки файла, такие как импорты и главный контракт файла, также должны быть обернуты в парные якоря.
+
+**Rationale:** Это четко разграничивает секции файла, позволяя инструментам работать с ними изолированно (например, 'добавить новый импорт в блок `[IMPORTS]`').
+
+**Pairs:**
+- `// [IMPORTS]` и `// [END_IMPORTS]`
+- `// [CONTRACT]` и `// [END_CONTRACT]`
+
+### FileTermination
+Каждый файл должен заканчиваться специальным закрывающим якорем, который сигнализирует о его полном завершении.
+
+**Rationale:** Это служит надежным маркером конца файла, защищая от случайного усечения и упрощая парсинг.
+
+**Template:** `// [END_FILE_YourFileName.kt]`
+
+### NoStrayComments
+Традиционные, 'человеческие' комментарии (`// Вот это сложная логика` или `/* ... */`) КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ.
+
+**Rationale:** Такие комментарии являются 'семантическим шумом' для AI. Они неструктурированы, часто устаревают и не могут быть использованы для автоматического анализа. Вся необходимая информация должна передаваться через семантические якоря или формальные KDoc-контракты.
+
+#### Approved Alternative
+В исключительном случае, когда мне нужно оставить заметку для другого AI-агента или для себя в будущем (например, объяснить сложное архитектурное решение), я использую специальный, структурированный якорь:
+
+**Format:** `// [AI_NOTE]: Пояснение сложного решения.`
+[/End SemanticLintingCompliance]