chore(lint): apply semantic enrichment\n\nFiles modified: 1
This commit is contained in:
@@ -1,76 +0,0 @@
|
||||
[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]
|
||||
127
agent_promts/knowledge_base/semantic_linting.xml
Normal file
127
agent_promts/knowledge_base/semantic_linting.xml
Normal file
@@ -0,0 +1,127 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<SemanticProtocol version="1.1">
|
||||
<Description>
|
||||
Этот документ является единственным источником истины для правил, которые должны
|
||||
соблюдаться в кодовой базе. Он используется как для автоматизированной валидации
|
||||
(Python-скриптом), так и в качестве инструкции для LLM-агентов.
|
||||
</Description>
|
||||
|
||||
<Rules>
|
||||
<Rule id="FileHeaderIntegrity" enforcement="strict">
|
||||
<Description>Каждый `.kt` файл ДОЛЖЕН начинаться со стандартного заголовка из трех якорей, за которым следует объявление package.</Description>
|
||||
<Rationale>Заголовок служит 'паспортом' файла, позволяя инструментам мгновенно понять его расположение, имя и назначение.</Rationale>
|
||||
<Definition type="regex">
|
||||
<!-- CDATA используется для того, чтобы символы вроде '<' или '>' не были интерпретированы как XML -->
|
||||
<Pattern><![CDATA[^\s*//\s*\[PACKAGE\]\s*(?P<package>.*?)\n//\s*\[FILE\]\s*(?P<file>.*?)\n//\s*\[SEMANTICS\]\s*(?P<semantics>.*)]]></Pattern>
|
||||
</Definition>
|
||||
<Example><![CDATA[
|
||||
// [PACKAGE] com.example.your.package.name
|
||||
// [FILE] YourFileName.kt
|
||||
// [SEMANTICS] ui, viewmodel, state_management
|
||||
package com.example.your.package.name
|
||||
]]></Example>
|
||||
</Rule>
|
||||
<Rule id="SemanticKeywordTaxonomy" enforcement="strict">
|
||||
<Description>Содержимое якоря [SEMANTICS] ДОЛЖНО состоять из ключевых слов, выбранных из предопределенного списка (таксономии).</Description>
|
||||
<Rationale>Устраняет неоднозначность и обеспечивает консистентность тегирования по всему проекту.</Rationale>
|
||||
<Definition type="taxonomy" targetGroup="semantics" delimiter=",">
|
||||
<AllowedValues>
|
||||
<Group name="Layer">
|
||||
<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>
|
||||
</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>
|
||||
</Group>
|
||||
</AllowedValues>
|
||||
</Definition>
|
||||
</Rule>
|
||||
<Rule id="EntityContainerization" enforcement="strict">
|
||||
<Description>Каждая ключевая сущность (class, interface, fun и т.д.) ДОЛЖНА быть обернута в парные якоря [ENTITY]...[END_ENTITY].</Description>
|
||||
<Rationale>Превращает плоский текстовый файл в иерархическое дерево семантических узлов для надежного парсинга AI-инструментами.</Rationale>
|
||||
<Definition type="paired_regex">
|
||||
<!-- Обратные ссылки (?P=type) и (?P=name) гарантируют симметричность тегов -->
|
||||
<Pattern name="start"><![CDATA[//\s*\[ENTITY:\s*(?P<type>\w+)\('(?P<name>.*?)'\)\]]]></Pattern>
|
||||
<Pattern name="end"><![CDATA[//\s*\[END_ENTITY:\s*(?P=type)\('(?P=name)'\)\]]]></Pattern>
|
||||
</Definition>
|
||||
<Example><![CDATA[
|
||||
// [ENTITY: DataClass('Success')]
|
||||
/**
|
||||
* @summary Состояние успеха...
|
||||
*/
|
||||
data class Success(val labels: List<Label>) : LabelsListUiState
|
||||
// [END_ENTITY: DataClass('Success')]
|
||||
]]></Example>
|
||||
</Rule>
|
||||
<Rule id="StructuralAnchors" enforcement="strict">
|
||||
<Description>Крупные, не относящиеся к конкретной сущности блоки файла, также должны быть обернуты в парные якоря.</Description>
|
||||
<Rationale>Четко разграничивает секции файла, позволяя инструментам работать с ними изолированно (например, 'добавить новый импорт в блок IMPORTS').</Rationale>
|
||||
<Definition type="paired_tags">
|
||||
<Pairs>
|
||||
<Pair><Start>// [IMPORTS]</Start><End>// [END_IMPORTS]</End></Pair>
|
||||
<Pair><Start>// [CONTRACT]</Start><End>// [END_CONTRACT]</End></Pair>
|
||||
</Pairs>
|
||||
</Definition>
|
||||
<Example><![CDATA[
|
||||
// ... file header ...
|
||||
package com.example
|
||||
|
||||
// [IMPORTS]
|
||||
import a.b.c
|
||||
// [END_IMPORTS]
|
||||
|
||||
// [CONTRACT]
|
||||
/** @summary ... */
|
||||
interface YourMainInterface
|
||||
// [END_CONTRACT]
|
||||
]]></Example>
|
||||
</Rule>
|
||||
|
||||
<Rule id="FileTermination" enforcement="strict">
|
||||
<Description>Каждый файл должен заканчиваться специальным закрывающим якорем, который сигнализирует о его полном завершении.</Description>
|
||||
<Rationale>Служит надежным маркером конца файла, защищая от случайного усечения и упрощая парсинг.</Rationale>
|
||||
<Definition type="dynamic_regex">
|
||||
<!-- Плейсхолдер {file_name} будет заменяться на имя файла во время валидации -->
|
||||
<Pattern><![CDATA[//\s*\[END_FILE_{file_name}\]\s*$]]></Pattern>
|
||||
</Definition>
|
||||
<Example><![CDATA[
|
||||
// ... file content ...
|
||||
}
|
||||
// [END_ENTITY: SomeClass('MyClass')]
|
||||
|
||||
// [END_FILE_MyClass.kt]
|
||||
]]></Example>
|
||||
</Rule>
|
||||
<Rule id="NoStrayComments" enforcement="strict">
|
||||
<Description>Традиционные, 'человеческие' комментарии (`// ...` или `/* ... */`) КАТЕГОРИЧЕСКИ ЗАПРЕЩЕНЫ.</Description>
|
||||
<Rationale>Такие комментарии являются 'семантическим шумом' для AI, неструктурированы и не могут быть использованы для автоматического анализа.</Rationale>
|
||||
<Definition type="negative_regex">
|
||||
<!-- Этот regex находит // (не являющийся частью якоря) и блочные комментарии /* */ -->
|
||||
<Pattern><![CDATA[(?<!\[)\s*\/\/[^\[\n\r]*|(?<!:)\/\*[\s\S]*?\*\/]]></Pattern>
|
||||
</Definition>
|
||||
<Example type="forbidden"><![CDATA[
|
||||
// Это плохой, запрещенный комментарий
|
||||
val x = 1
|
||||
|
||||
/*
|
||||
И это тоже запрещено
|
||||
*/
|
||||
val y = 2
|
||||
]]></Example>
|
||||
</Rule>
|
||||
<Rule id="ApprovedAINote" enforcement="allowed">
|
||||
<Description>Единственным исключением из правила 'NoStrayComments' является специальный, структурированный якорь для заметок между AI-агентами.</Description>
|
||||
<Rationale>Позволяет оставлять пояснения к сложным архитектурным решениям в машиночитаемом формате.</Rationale>
|
||||
<Definition type="regex">
|
||||
<Pattern><![CDATA[//\s*\[AI_NOTE\]:\s*(.*)]]></Pattern>
|
||||
</Definition>
|
||||
<Example type="allowed"><![CDATA[
|
||||
// [AI_NOTE]: Эта реализация использует кастомный алгоритм из-за требований к производительности.
|
||||
fun processData() { /* ... */ }
|
||||
]]></Example>
|
||||
</Rule>
|
||||
|
||||
</Rules>
|
||||
</SemanticProtocol>
|
||||
Reference in New Issue
Block a user