77 lines
6.3 KiB
Markdown
77 lines
6.3 KiB
Markdown
[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]
|