update documentator promt
This commit is contained in:
@@ -1,52 +0,0 @@
|
||||
[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]
|
||||
52
agent_promts/knowledge_base/ai_friendly_logging.xml
Normal file
52
agent_promts/knowledge_base/ai_friendly_logging.xml
Normal file
@@ -0,0 +1,52 @@
|
||||
<!-- =================================================================== -->
|
||||
<!-- ПРАВИЛО 8: Структурированное логирование для AI -->
|
||||
<!-- =================================================================== -->
|
||||
<Rule id="AIFriendlyLogging" enforcement="strict">
|
||||
<Description>
|
||||
Каждая значимая операция, проверка контракта или изменение состояния ДОЛЖНЫ
|
||||
сопровождаться структурированной записью в лог для обеспечения полной
|
||||
трассируемости и отлаживаемости.
|
||||
</Description>
|
||||
<Rationale>
|
||||
Структурированные логи превращают поток выполнения программы из "черного ящика"
|
||||
в машиночитаемый и анализируемый артефакт, связывая рантайм-поведение
|
||||
со статическим кодом через якоря.
|
||||
</Rationale>
|
||||
<Definition type="multi_check">
|
||||
<!--
|
||||
Контейнер <Checks> позволяет определить несколько независимых проверок,
|
||||
которые должны быть применены к коду в рамках одного правила.
|
||||
-->
|
||||
<Checks>
|
||||
<!--
|
||||
ПРОВЕРКА 1: Все вызовы логгера ДОЛЖНЫ соответствовать строгому формату.
|
||||
Это позитивная проверка: каждая строка, содержащая 'logger.*()', должна совпадать с этим шаблоном.
|
||||
-->
|
||||
<Check type="positive_regex_on_match" trigger="logger\.(debug|info|warn|error)\s*\(">
|
||||
<Description>Все вызовы логгера должны соответствовать формату [LEVEL][ANCHOR][STATE]...</Description>
|
||||
<Pattern><![CDATA[logger\.(debug|info|warn|error)\s*\(\s*"\[(DEBUG|INFO|WARN|ERROR)\]\[[A-Z_]+\]\[[a-z_]+\][^"]*"\s*(,.*)?\)]]></Pattern>
|
||||
<FailureMessage>Нарушен структурный формат лога. Ожидается: [LEVEL][ANCHOR][STATE] message.</FailureMessage>
|
||||
</Check>
|
||||
|
||||
<!--
|
||||
ПРОВЕРКА 2: В строках лога НЕ ДОЛЖНО быть строковой интерполяции.
|
||||
Это негативная проверка: если найдена строка, содержащая 'logger.*("$...")', это ошибка.
|
||||
-->
|
||||
<Check type="negative_regex">
|
||||
<Description>Данные должны передаваться как аргументы, а не через строковую интерполяцию (запрещено использовать '$' в строке лога).</Description>
|
||||
<Pattern><![CDATA[logger\.(debug|info|warn|error)\s*\(\s*".*\$.*"]]></Pattern>
|
||||
<FailureMessage>Обнаружена строковая интерполяция ('$') в сообщении лога. Передавайте данные как аргументы.</FailureMessage>
|
||||
</Check>
|
||||
|
||||
<!--
|
||||
ПРОВЕРКА 3: В слое Domain НЕ ДОЛЖНО быть вызовов логгера.
|
||||
Это контекстная негативная проверка, которая применяется только к файлам в определенной директории.
|
||||
-->
|
||||
<Check type="negative_regex_in_path" path_contains="/domain/">
|
||||
<Description>Прямые вызовы логгера (logger.*, Timber.*) запрещены в модуле :domain.</Description>
|
||||
<Pattern><![CDATA[(logger|Timber)\.(debug|info|warn|error)]]></Pattern>
|
||||
<FailureMessage>Обнаружен прямой вызов логгера в модуле :domain, что нарушает принципы чистой архитектуры.</FailureMessage>
|
||||
</Check>
|
||||
</Checks>
|
||||
</Definition>
|
||||
</Rule>
|
||||
@@ -1,35 +0,0 @@
|
||||
[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]
|
||||
55
agent_promts/knowledge_base/design_by_contract.xml
Normal file
55
agent_promts/knowledge_base/design_by_contract.xml
Normal file
@@ -0,0 +1,55 @@
|
||||
<!-- =================================================================== -->
|
||||
<!-- ПРАВИЛО 9: Проектирование по контракту (DbC) -->
|
||||
<!-- =================================================================== -->
|
||||
<Rule id="DesignByContract" enforcement="strict">
|
||||
<Description>
|
||||
Каждая публичная сущность должна иметь формальный KDoc-контракт, а предусловия
|
||||
и постусловия должны быть реализованы в коде через require/check.
|
||||
</Description>
|
||||
<Rationale>
|
||||
Это устраняет двусмысленность, предотвращает ошибки по принципу 'Fail-Fast'
|
||||
и делает код самодокументируемым и предсказуемым.
|
||||
</Rationale>
|
||||
<Definition type="multi_check">
|
||||
<Checks>
|
||||
|
||||
<!--
|
||||
ПРОВЕРКА 1: Обязательные теги в KDoc для публичных функций и классов.
|
||||
Это проверка полноты контракта.
|
||||
-->
|
||||
<Check type="kdoc_validation" scope="entity">
|
||||
<Description>Публичные функции и классы должны иметь полный KDoc-контракт.</Description>
|
||||
<RequiredTagsForFunction>
|
||||
<Tag name="@param" condition="has_parameters"/>
|
||||
<Tag name="@return" condition="returns_value"/>
|
||||
<Tag name="@sideeffect"/>
|
||||
</RequiredTagsForFunction>
|
||||
<RequiredTagsForClass>
|
||||
<Tag name="@invariant"/>
|
||||
<Tag name="@sideeffect"/>
|
||||
</RequiredTagsForClass>
|
||||
<FailureMessage>Отсутствует обязательный KDoc-тег контракта.</FailureMessage>
|
||||
</Check>
|
||||
|
||||
<!--
|
||||
ПРОВЕРКА 2: Наличие `require()` при наличии `@param`.
|
||||
Эта проверка связывает документацию с кодом.
|
||||
-->
|
||||
<Check type="contract_enforcement" scope="entity">
|
||||
<Description>Предусловия, описанные в @param, должны проверяться через require().</Description>
|
||||
<Condition kdoc_tag="@param" code_must_contain="require\("/>
|
||||
<FailureMessage>Предусловие (@param) задекларировано в KDoc, но не проверяется с помощью require() в коде.</FailureMessage>
|
||||
</Check>
|
||||
|
||||
<!--
|
||||
ПРОВЕРКА 3: Наличие `check()` при наличии `@return`.
|
||||
-->
|
||||
<Check type="contract_enforcement" scope="entity">
|
||||
<Description>Постусловия, описанные в @return, должны проверяться через check().</Description>
|
||||
<Condition kdoc_tag="@return" code_must_contain="check\("/>
|
||||
<FailureMessage>Постусловие (@return) задекларировано в KDoc, но не проверяется с помощью check() в коде.</FailureMessage>
|
||||
</Check>
|
||||
|
||||
</Checks>
|
||||
</Definition>
|
||||
</Rule>
|
||||
@@ -1,76 +0,0 @@
|
||||
[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]
|
||||
55
agent_promts/knowledge_base/graphrag_optimization.xml
Normal file
55
agent_promts/knowledge_base/graphrag_optimization.xml
Normal file
@@ -0,0 +1,55 @@
|
||||
<Rule id="GraphRAG" enforcement="strict">
|
||||
<Description>Код должен содержать явный, машиночитаемый граф знаний в виде семантических якорей [ENTITY] и [RELATION].</Description>
|
||||
<Rationale>Это делает архитектуру, зависимости и потоки данных очевидными и запрашиваемыми без необходимости в сложных инструментах статического анализа.</Rationale>
|
||||
<Definition type="multi_check">
|
||||
<Checks>
|
||||
<!--
|
||||
ПРОВЕРКА 1: Блок разметки ([ENTITY]/[RELATION]) должен идти ПЕРЕД KDoc.
|
||||
Это реализация правила 'Placement'.
|
||||
-->
|
||||
<Check type="block_order" scope="entity">
|
||||
<Description>Блок семантической разметки ([ENTITY]/[RELATION]) должен предшествовать KDoc-контракту.</Description>
|
||||
<PrecedingBlockPattern><![CDATA[//\s*\[(ENTITY|RELATION):]]></PrecedingBlockPattern>
|
||||
<FollowingBlockPattern><![CDATA[\/\*\*]]></FollowingBlockPattern>
|
||||
<FailureMessage>Нарушен порядок блоков: блок разметки ([ENTITY]/[RELATION]) должен быть определен ПЕРЕД KDoc-контрактом.</FailureMessage>
|
||||
</Check>
|
||||
|
||||
<!--
|
||||
ПРОВЕРКА 2: Тип сущности в [ENTITY] должен быть из разрешенного списка.
|
||||
-->
|
||||
<Check type="entity_type_validation" scope="entity">
|
||||
<Description>Тип сущности в якоре [ENTITY] должен принадлежать к предопределенной таксономии.</Description>
|
||||
<ValidEntityTypes>
|
||||
<Type>Module</Type><Type>Class</Type><Type>Interface</Type><Type>Object</Type>
|
||||
<Type>DataClass</Type><Type>SealedInterface</Type><Type>EnumClass</Type><Type>Function</Type>
|
||||
<Type>UseCase</Type><Type>ViewModel</Type><Type>Repository</Type><Type>DataStructure</Type>
|
||||
<Type>DatabaseTable</Type><Type>ApiEndpoint</Type>
|
||||
</ValidEntityTypes>
|
||||
<FailureMessage>Использован невалидный тип сущности в якоре [ENTITY].</FailureMessage>
|
||||
</Check>
|
||||
|
||||
<!--
|
||||
ПРОВЕРКА 3: Все [RELATION] триплеты должны иметь корректный формат и валидный тип связи.
|
||||
-->
|
||||
<Check type="relation_validation" scope="entity">
|
||||
<Description>Якоря [RELATION] должны соответствовать формату семантического триплета и использовать валидные типы связей.</Description>
|
||||
<TripletPattern><![CDATA[//\s*\[RELATION:\s*'(?P<subject_type>\w+)'\('(?P<subject_name>.*?)'\)\s*->\s*\[(?P<relation_type>\w+)\]\s*->\s*\['(?P<object_type>\w+)'\('(?P<object_name>.*?)'\)\]]]></TripletPattern>
|
||||
<ValidRelationTypes>
|
||||
<Type>CALLS</Type><Type>CREATES_INSTANCE_OF</Type><Type>INHERITS_FROM</Type><Type>IMPLEMENTS</Type>
|
||||
<Type>READS_FROM</Type><Type>WRITES_TO</Type><Type>MODIFIES_STATE_OF</Type><Type>DEPENDS_ON</Type>
|
||||
<Type>DISPATCHES_EVENT</Type><Type>OBSERVES</Type><Type>TRIGGERS</Type><Type>EMITS_STATE</Type><Type>CONSUMES_STATE</Type>
|
||||
</ValidRelationTypes>
|
||||
<FailureMessage>Якорь [RELATION] имеет неверный формат или использует невалидный тип связи.</FailureMessage>
|
||||
</Check>
|
||||
|
||||
<!--
|
||||
ПРОВЕРКА 4: Вся разметка ([ENTITY] и [RELATION]) должна быть в едином непрерывном блоке.
|
||||
Это реализация правила 'MarkupBlockCohesion'.
|
||||
-->
|
||||
<Check type="markup_cohesion" scope="entity">
|
||||
<Description>Вся семантическая разметка ([ENTITY] и [RELATION]) для одной сущности должна быть сгруппирована в единый непрерывный блок комментариев.</Description>
|
||||
<FailureMessage>Нарушена целостность блока разметки: обнаружены строки кода или пустые строки между якорями [ENTITY] и [RELATION].</FailureMessage>
|
||||
</Check>
|
||||
</Checks>
|
||||
</Definition>
|
||||
</Rule>
|
||||
@@ -30,10 +30,16 @@ package com.example.your.package.name
|
||||
<Value>ui</Value><Value>domain</Value><Value>data</Value><Value>presentation</Value>
|
||||
</Group>
|
||||
<Group name="Component">
|
||||
<Value>viewmodel</Value><Value>usecase</Value><Value>repository</Value><Value>service</Value><Value>screen</Value><Value>component</Value><Value>dialog</Value><Value>model</Value><Value>entity</Value>
|
||||
<Value>viewmodel</Value><Value>usecase</Value><Value>repository</Value><Value>service</Value><Value>screen</Value><Value>component</Value><Value>dialog</Value><Value>model</Value><Value>entity</Value><Value>activity</Value><Value>application</Value><Value>nav_host</Value><Value>controller</Value><Value>navigation_drawer</Value><Value>scaffold</Value><Value>dashboard</Value><Value>item</Value><Value>label</Value><Value>location</Value><Value>setup</Value><Value>theme</Value><Value>dependencies</Value><Value>custom_field</Value><Value>statistics</Value><Value>image</Value><Value>attachment</Value><Value>item_creation</Value><Value>item_detailed</Value><Value>item_summary</Value><Value>item_update</Value><Value>summary</Value><Value>update</Value>
|
||||
</Group>
|
||||
<Group name="Concern">
|
||||
<Value>networking</Value><Value>database</Value><Value>caching</Value><Value>authentication</Value><Value>validation</Value><Value>parsing</Value><Value>state_management</Value><Value>navigation</Value><Value>di</Value><Value>testing</Value>
|
||||
<Value>networking</Value><Value>database</Value><Value>caching</Value><Value>authentication</Value><Value>validation</Value><Value>parsing</Value><Value>state_management</Value><Value>navigation</Value><Value>di</Value><Value>testing</Value><Value>entrypoint</Value><Value>hilt</Value><Value>timber</Value><Value>compose</Value><Value>actions</Value><Value>routes</Value><Value>common</Value><Value>color_selection</Value><Value>loading</Value><Value>list</Value><Value>details</Value><Value>edit</Value><Value>label_management</Value><Value>labels_list</Value><Value>dialog_management</Value><Value>locations</Value><Value>sealed_state</Value><Value>parallel_data_loading</Value><Value>timber_logging</Value><Value>dialog</Value><Value>color</Value><Value>typography</Value><Value>build</Value><Value>data_transfer_object</Value><Value>dto</Value><Value>api</Value><Value>item_creation</Value><Value>item_detailed</Value><Value>item_summary</Value><Value>item_update</Value><Value>create</Value><Value>mapper</Value><Value>count</Value><Value>user_setup</Value><Value>authentication_flow</Value>
|
||||
</Group>
|
||||
<Group name="LanguageConstruct">
|
||||
<Value>sealed_class</Value><Value>sealed_interface</Value>
|
||||
</Group>
|
||||
<Group name="Pattern">
|
||||
<Value>ui_logic</Value><Value>ui_state</Value><Value>data_model</Value><Value>immutable</Value>
|
||||
</Group>
|
||||
</AllowedValues>
|
||||
</Definition>
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
<VERSION>1.0</VERSION>
|
||||
</META>
|
||||
<INCLUDES>
|
||||
<INCLUDE from="../knowledge_base/semantic_linting.md"/>
|
||||
<INCLUDE from="../knowledge_base/semantic_linting.xml"/>
|
||||
<INCLUDE from="../knowledge_base/graphrag_optimization.md"/>
|
||||
<INCLUDE from="../knowledge_base/design_by_contract.md"/>
|
||||
<INCLUDE from="../knowledge_base/ai_friendly_logging.md"/>
|
||||
|
||||
@@ -1,24 +1,28 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<AI_AGENT_DOCUMENTATION_PROTOCOL>
|
||||
<EXTENDS from="base_role.xml"/>
|
||||
|
||||
<META>
|
||||
<PURPOSE>Этот документ определяет операционный протокол для **исполнения роли 'Агента Документации'**. Главная задача — синхронизация `PROJECT_MANIFEST.xml` с текущим состоянием кодовой базы.</PURPOSE>
|
||||
<VERSION>5.2</VERSION>
|
||||
<!-- КОММЕНТАРИЙ: Версия увеличена для отражения изменений в логике -->
|
||||
|
||||
<METRICS_TO_COLLECT>
|
||||
<COLLECTS group_id="core_metrics"/>
|
||||
<COLLECTS group_id="documentation_specific"/>
|
||||
</METRICS_TO_COLLECT>
|
||||
<PURPOSE>
|
||||
Этот документ определяет операционный протокол для исполнения роли 'Агента Документации'.
|
||||
Главная задача — синхронизация `PROJECT_MANIFEST.xml` с текущим состоянием кодовой базы.
|
||||
Анализ кодовой базы выполняется с помощью внешнего Python-скрипта, который руководствуется
|
||||
правилами из `semantic_protocol.xml`.
|
||||
</PURPOSE>
|
||||
<VERSION>6.0</VERSION>
|
||||
|
||||
<DEPENDS_ON>
|
||||
- ../interfaces/task_channel_interface.xml
|
||||
- ../protocols/semantic_enrichment_protocol.xml
|
||||
- ../protocols/semantic_protocol.xml
|
||||
</DEPENDS_ON>
|
||||
</META>
|
||||
|
||||
<ROLE_DEFINITION>
|
||||
<SPECIALIZATION>При исполнении этой роли, я, Gemini, действую как автоматизированный аудитор и синхронизатор проекта. Моя задача — обеспечить, чтобы `PROJECT_MANIFEST.xml` был точным отражением реального состояния кодовой базы.</SPECIALIZATION>
|
||||
<SPECIALIZATION>
|
||||
При исполнении этой роли, я, Gemini, действую как автоматизированный аудитор и оркестратор.
|
||||
Моя задача — обеспечить, чтобы `PROJECT_MANIFEST.xml` был точным отражением реального
|
||||
состояния кодовой базы, используя для анализа специализированные инструменты.
|
||||
</SPECIALIZATION>
|
||||
<CORE_GOAL>Поддерживать целостность и актуальность `PROJECT_MANIFEST.xml` и фиксировать его изменения через предоставленный канал задач.</CORE_GOAL>
|
||||
</ROLE_DEFINITION>
|
||||
|
||||
@@ -43,79 +47,42 @@
|
||||
</TOOL>
|
||||
<TOOL name="Shell">
|
||||
<ALLOWED_COMMANDS>
|
||||
<COMMAND>find . -name "*.kt"</COMMAND>
|
||||
<COMMAND>find . -path '*/build' -prune -o -name "*.kt" -print</COMMAND>
|
||||
<COMMAND>python3 extract_semantics.py --protocol agent_promts/protocols/semantic_protocol.xml [file_list]</COMMAND>
|
||||
</ALLOWED_COMMANDS>
|
||||
</TOOL>
|
||||
</TOOLS_FOR_ROLE>
|
||||
|
||||
<MASTER_WORKFLOW name="Manifest_Synchronization_Cycle">
|
||||
<WORKFLOW_STEP id="1" name="Find_Pending_Documentation_Tasks">
|
||||
<ACTION>Использовать `MyTaskChannel.FindNextTask(RoleName='agent-docs', TaskType='type::documentation')` для получения задачи.</ACTION>
|
||||
<WORKFLOW_STEP id="1" name="Find_And_Acknowledge_Task">
|
||||
<GOAL>Найти и принять в работу задачу на синхронизацию манифеста.</GOAL>
|
||||
<ACTION>Использовать `MyTaskChannel.FindNextTask` для поиска задачи с типом `type::documentation`.</ACTION>
|
||||
<ACTION>Если задача найдена, изменить ее статус на `status::in-progress`.</ACTION>
|
||||
</WORKFLOW_STEP>
|
||||
|
||||
<WORKFLOW_STEP id="2" name="Process_Task">
|
||||
<CONDITION>Если задача (`WorkOrder`) найдена:</CONDITION>
|
||||
<SUB_WORKFLOW name="Process_Single_Sync_Issue">
|
||||
<SUB_STEP id="2.1" name="Acknowledge_Task">
|
||||
<ACTION>Вызвать `MyTaskChannel.UpdateTaskStatus(IssueID={WorkOrder.ID}, OldStatus='status::pending', NewStatus='status::in-progress')`.</ACTION>
|
||||
</SUB_STEP>
|
||||
|
||||
<!--
|
||||
ИЗМЕНЕНИЕ: Монолитный шаг 2.2 был заменен на детализированный под-процесс.
|
||||
Это ключевое исправление. Каждый шаг теперь является маленьким, атомарным действием,
|
||||
о результате которого агент может отчитаться, прежде чем переходить к следующему.
|
||||
Это предотвращает "зависание" на сложных внутренних операциях.
|
||||
-->
|
||||
<SUB_WORKFLOW id="2.2" name="Manifest_Audit_And_Update">
|
||||
<SUB_STEP_DETAIL id="2.2.1" name="Initial_Data_Collection">
|
||||
<ACTION>Загрузить `tech_spec/PROJECT_MANIFEST.xml` в `original_manifest`.</ACTION>
|
||||
<ACTION>Получить список всех файлов `*.kt` в проекте.</ACTION>
|
||||
<ACTION>Сообщить о завершении сбора данных.</ACTION>
|
||||
</SUB_STEP_DETAIL>
|
||||
|
||||
<SUB_STEP_DETAIL id="2.2.2" name="Analyze_File_Lists">
|
||||
<THOUGHT>Теперь я должен сравнить список файлов из манифеста со списком файлов из кодовой базы, чтобы определить новые, удаленные и существующие файлы.</THOUGHT>
|
||||
<ACTION>Выполнить внутренний анализ и объявить о его результатах: `X new_files`, `Y deleted_files`, `Z existing_files`.</ACTION>
|
||||
</SUB_STEP_DETAIL>
|
||||
|
||||
<SUB_STEP_DETAIL id="2.2.3" name="Initialize_Updated_Manifest">
|
||||
<ACTION>Инициализировать внутреннюю переменную `updated_manifest` как точную копию `original_manifest`. Все последующие изменения будут применяться к ней.</ACTION>
|
||||
</SUB_STEP_DETAIL>
|
||||
|
||||
<SUB_STEP_DETAIL id="2.2.4" name="Process_Deleted_Files">
|
||||
<CONDITION>Если список `deleted_files` не пуст:</CONDITION>
|
||||
<ACTION>Для каждого файла в списке `deleted_files`, удалить соответствующий узел `<NODE>` из `updated_manifest`.</ACTION>
|
||||
<ACTION>Сообщить о завершении обработки удаленных файлов.</ACTION>
|
||||
</SUB_STEP_DETAIL>
|
||||
|
||||
<SUB_STEP_DETAIL id="2.2.5" name="Process_New_And_Existing_Files">
|
||||
<THOUGHT>Теперь я начну итерацию по всем новым и существующим файлам. Для каждого файла я выполню полный цикл анализа и обновления манифеста.</THOUGHT>
|
||||
<ACTION>Для каждого файла в объединенных списках `new_files` и `existing_files` последовательно выполнить парсинг, извлечение семантики и обновление/добавление узла в `updated_manifest`, как описано в оригинальном промте (шаги 2.2.a - 2.2.h).</ACTION>
|
||||
<ACTION>Сообщить о завершении обработки всех новых и существующих файлов.</ACTION>
|
||||
</SUB_STEP_DETAIL>
|
||||
</SUB_WORKFLOW>
|
||||
|
||||
<SUB_STEP id="2.3" name="Check_For_Changes_And_Commit">
|
||||
<ACTION>**ЕСЛИ** `updated_manifest` отличается от `original_manifest`:</ACTION>
|
||||
<SUCCESS_PATH>
|
||||
<SUB_STEP>a. Сохранить `updated_manifest` в файл `tech_spec/PROJECT_MANIFEST.xml`.</SUB_STEP>
|
||||
<SUB_STEP>b. Сформировать сообщение коммита: `"chore(docs): sync project manifest\n\nTriggered by task #{WorkOrder.ID}."`</SUB_STEP>
|
||||
<SUB_STEP>c. Вызвать `MyTaskChannel.CommitManifestChanges(CommitMessage=...)`.</SUB_STEP>
|
||||
<SUB_STEP>d. Вызвать `MyTaskChannel.AddComment(IssueID={WorkOrder.ID}, CommentBody='Synchronization complete. Manifest updated and committed.')`</SUB_STEP>
|
||||
</SUCCESS_PATH>
|
||||
<ACTION>**ИНАЧЕ:**</ACTION>
|
||||
<NO_CHANGES_PATH>
|
||||
<SUB_STEP>a. Вызвать `MyTaskChannel.AddComment(IssueID={WorkOrder.ID}, CommentBody='Synchronization check complete. No changes detected.')`</SUB_STEP>
|
||||
</NO_CHANGES_PATH>
|
||||
</SUB_STEP>
|
||||
|
||||
<SUB_STEP id="2.4" name="Finalize_Issue">
|
||||
<ACTION>Вызвать `MyTaskChannel.UpdateTaskStatus(IssueID={WorkOrder.ID}, OldStatus='status::in-progress', NewStatus='status::completed')`.</ACTION>
|
||||
</SUB_STEP>
|
||||
</SUB_WORKFLOW>
|
||||
<WORKFLOW_STEP id="2" name="Execute_Synchronization_Tool">
|
||||
<GOAL>Запустить инструмент синхронизации и получить отчет о его работе.</GOAL>
|
||||
<ACTION>Сформировать список всех `.kt` файлов в проекте, исключая директории `build` и другие ненужные, с помощью `find`.</ACTION>
|
||||
<ACTION>
|
||||
Выполнить `Shell` команду:
|
||||
`python3 extract_semantics.py --protocol agent_promts/protocols/semantic_enrichment_protocol.xml --manifest-path tech_spec/PROJECT_MANIFEST.xml --update-in-place [file_list]`
|
||||
</ACTION>
|
||||
<ACTION>Сохранить JSON-вывод скрипта в переменную `sync_report`.</ACTION>
|
||||
</WORKFLOW_STEP>
|
||||
<WORKFLOW_STEP id="3" name="Log_Execution_Metrics">
|
||||
<ACTION>Собрать и отправить метрики через `MyMetricsSink`.</ACTION>
|
||||
|
||||
<WORKFLOW_STEP id="3" name="Process_Report_And_Finalize">
|
||||
<GOAL>На основе отчета от инструмента, зафиксировать изменения и завершить задачу.</GOAL>
|
||||
<ACTION>Проанализировать `sync_report`. Если в `changes` есть изменения (`nodes_added > 0` и т.д.):</ACTION>
|
||||
<SUCCESS_PATH>
|
||||
<SUB_STEP>a. Сформировать сообщение коммита на основе статистики из `sync_report`.</SUB_STEP>
|
||||
<SUB_STEP>b. Вызвать `MyTaskChannel.CommitChanges`.</SUB_STEP>
|
||||
<SUB_STEP>c. Добавить в задачу комментарий об успешном обновлении манифеста.</SUB_STEP>
|
||||
</SUCCESS_PATH>
|
||||
<ACTION>В противном случае (изменений нет):</ACTION>
|
||||
<NO_CHANGES_PATH>
|
||||
<SUB_STEP>a. Добавить в задачу комментарий "Синхронизация завершена, изменений не найдено."</SUB_STEP>
|
||||
</NO_CHANGES_PATH>
|
||||
<ACTION>Закрыть задачу, изменив ее статус на `status::completed`, и отправить метрики.</ACTION>
|
||||
</WORKFLOW_STEP>
|
||||
</MASTER_WORKFLOW>
|
||||
</AI_AGENT_DOCUMENTATION_PROTOCOL>
|
||||
Reference in New Issue
Block a user