homebox_lens/agent_promts/protocols/semantic_enrichment_protocol.md

Протокол Семантического Обогащения (Semantic Enrichment Protocol)

Версия: 1.1

Описание

Этот документ является единственным источником истины для правил, которые должны соблюдаться в кодовой базе. Он используется как для автоматизированной валидации, так и в качестве инструкции для LLM-агентов.

---

Правила

1. Целостность Заголовка Файла (FileHeaderIntegrity)

Каждый .kt файл ДОЛЖЕН начинаться со стандартного заголовка из двух якорей, за которым следует объявление package. Заголовок служит 'паспортом' файла.

Пример:

// [FILE] YourFileName.kt
// [SEMANTICS] ui, viewmodel, state_management

package com.example.your.package.name

2. Таксономия Семантических Ключевых Слов (SemanticKeywordTaxonomy)

Содержимое якоря [SEMANTICS] ДОЛЖНО состоять из ключевых слов, выбранных из предопределенного списка (таксономии).

Допустимые значения:

• Layer: ui, domain, data, presentation
• Component: viewmodel, usecase, repository, service, screen, component, dialog, model, entity, activity, application, nav_host, controller, navigation_drawer, scaffold, dashboard, item, label, location, setup, theme, dependencies, custom_field, statistics, image, attachment, item_creation, item_detailed, item_summary, item_update, summary, update
• Concern: networking, database, caching, authentication, validation, parsing, state_management, navigation, di, testing, entrypoint, hilt, timber, compose, actions, routes, common, color_selection, loading, list, details, edit, label_management, labels_list, dialog_management, locations, sealed_state, parallel_data_loading, timber_logging, dialog, color, typography, build, data_transfer_object, dto, api, item_creation, item_detailed, item_summary, item_update, create, mapper, count, user_setup, authentication_flow
• LanguageConstruct: sealed_class, sealed_interface
• Pattern: ui_logic, ui_state, data_model, immutable

3. Якоря Сущностей (Anchors)

Каждая ключевая сущность (class, interface, fun и т.д.) ДОЛЖНА быть обернута в парные якоря для навигации и консолидации семантики.

Синтаксис:

• Открывающий якорь: // [ANCHOR:id:type]
• Закрывающий якорь: // [END_ANCHOR:id]

Пример:

// [ANCHOR:Success:DataClass]
/**
 * @summary Состояние успеха...
 */
data class Success(val labels: List<Label>) : LabelsListUiState
// [END_ANCHOR:Success]

4. Структурные Якоря (StructuralAnchors)

Крупные блоки файла (импорты, контракты) также должны быть обернуты в парные якоря.

• // [IMPORTS] ... // [END_IMPORTS]
• // [CONTRACT] ... // [END_CONTRACT]

5. Завершение Файла (FileTermination)

Каждый файл должен заканчиваться специальным закрывающим якорем // [END_FILE_MyClass.kt].

6. Запрет Посторонних Комментариев (NoStrayComments)

Традиционные, 'человеческие' комментарии (// ... или /* ... */) КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ. Единственное исключение — структурированная заметка для агентов: // [AI_NOTE]: ...

---

Принципы Проектирования

A. Дружественное к ИИ Логирование (AIFriendlyLogging)

Каждая значимая операция ДОЛЖНА сопровождаться структурированной записью в лог.

• Формат: [LEVEL][ANCHOR][STATE]...
• Ограничение: Данные передаются как аргументы, а не через строковую интерполяцию ($).

B. Проектирование по Контракту (DesignByContract)

Каждая публичная сущность (функция, класс) ДОЛЖНА иметь исчерпывающий, машиночитаемый контракт, расположенный непосредственно перед ее объявлением. Контракт заключается в якоря [CONTRACT] и [END_CONTRACT].

Структура контракта:

// [CONTRACT:unique_entity_id]
// [PURPOSE] Краткое описание назначения.
// [PRE] Предусловие 1 (например, "входной список не пуст").
// [POST] Постусловие 1 (например, "возвращаемое значение не null").
// [PARAM:name:type] Описание параметра.
// [RETURN:type] Описание возвращаемого значения.
// [TEST:description] input: "valid", expected: true
// [THROW:exception] Описание, когда выбрасывается исключение.
// [END_CONTRACT:unique_entity_id]

Реализация в коде: Предусловия и постусловия ([PRE] и [POST]), описанные в контракте, ДОЛЖНЫ быть реализованы в коде с использованием функций require() и check().

C. Граф Знаний в Коде (GraphRAG)

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

Синтаксис триплета: Отношение (триплет "субъект-предикат-объект") определяется внутри якоря субъекта с помощью следующего синтаксиса: // [RELATION:predicate:object_id]

• Субъект: Неявно определяется якорем [ANCHOR], в котором находится [RELATION].
• Предикат: Тип отношения из предопределенного списка.
• Объект: id другого якоря [ANCHOR].

Пример:

// [ANCHOR:DashboardViewModel:ViewModel]
// [RELATION:CALLS:GetStatisticsUseCase]
// [RELATION:DEPENDS_ON:ItemRepository]
class DashboardViewModel(...) { ... }
// [END_ANCHOR:DashboardViewModel]

Таксономия:

• Типы сущностей (для [ANCHOR:id:type]): Module, Class, Interface, Object, DataClass, SealedInterface, EnumClass, Function, UseCase, ViewModel, Repository, DataStructure, DatabaseTable, ApiEndpoint.
• Типы отношений (для [RELATION:predicate:object_id]): CALLS, CREATES_INSTANCE_OF, INHERITS_FROM, IMPLEMENTS, READS_FROM, WRITES_TO, MODIFIES_STATE_OF, DEPENDS_ON, DISPATCHES_EVENT, OBSERVES, TRIGGERS, EMITS_STATE, CONSUMES_STATE.