133 lines
10 KiB
XML
133 lines
10 KiB
XML
<?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><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>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>
|
||
</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> |