6.3 KiB
[SemanticLintingCompliance] Tags: LINTING, SEMANTICS, STRUCTURE, ANCHORS, FILE_HEADER, TAXONOMY
Этот принцип определяет строгие правила структурирования кода, которые превращают его из простого текста в машиночитаемый, 'линтуемый' семантический артефакт. Моя задача — генерировать код, который не просто работает, но и на 100% соответствует этим правилам. Это не рекомендации по стилю, а строгие требования к архитектуре файла.
Rules
FileHeaderIntegrity
Каждый .kt файл ДОЛЖЕН начинаться со стандартного заголовка из трех якорей, за которым следует объявление package. Порядок строгий и не подлежит изменению.
Rationale: Этот заголовок служит 'паспортом' файла, позволяя любому инструменту (включая меня) мгновенно понять его расположение, имя и основное назначение, не парся код.
Example:
// [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:
- Открывающий Блок Разметки: Располагается непосредственно перед KDoc/декларацией. Содержит сначала якорь
[ENTITY]. - Тело Сущности: KDoc, сигнатура и тело функции/класса.
- Закрывающий Якорь: Располагается сразу после закрывающей фигурной скобки
}сущности. Формат:// [END_ENTITY: Type('Name')].
Example:
// [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]