architect/standards/arch-component-structure.md

type: standard
layer: arch
object: component
aspect: structure
form: text
title: "Структура компонента платформы"
status: active
version: 1.0.0
date: 2026-04-11
knowledge_level: У1
parent: arch-filesystem-structure.md
deps:
- arch-filesystem-structure.md
- arch-project-structure.md
- arch-document-system.md

Структура компонента платформы

Стандарт описывает компонент как единицу платформы: определение, типы по суффиксу и реализации, внутреннюю структуру, наследование классов, жизненный цикл и правила создания.

1. ЧТО ТАКОЕ КОМПОНЕНТ

Компонент — автономная функциональная единица платформы с чётким назначением, интерфейсом и документацией.

Форма: папка с именем @{имя}.{тип}/

Признаки компонента:
- Автономность — работает независимо или с явно объявленными зависимостями
- Интерфейс — чёткий протокол взаимодействия (API, AI.md, CLAUDE.md)
- Назначение — решает одну конкретную задачу
- Самодокументированность — AI.md/CLAUDE.md описывает что и как

Компонент существует внутри слоя:

system/    → @{имя}.agent/, @{имя}.service/, @{имя}.domain/, @{имя}.coder/
coder/     → @{имя}.module/, @{имя}.api/, @{имя}.tool/
infra/     → @{имя}.server/, @{имя}.infra/
projects/  → @{тип}-{имя}/ (проекты — особый случай)

arch/ и projector/ компонентов не содержат — только .md файлы.

2. ТИПЫ КОМПОНЕНТОВ

Тип фиксируется в суффиксе имени папки: @{имя}.{тип}/

По реализации

Тип реализации Что внутри Пример
AI только .md файлы @architect.agent/
CODE исполняемый код @ozon.api/
Гибридный AI + код @scheduler.service/

По назначению

Суффикс Назначение Слой Пример
.agent AI-агент: роль + правила + протокол system/ @dispatcher.agent/
.service Docker-сервис платформы system/ @monitor.service/
.domain Диспетчер домена исполнения system/ @it.domain/
.coder Специализированный кодер стека system/ @drupal.coder/
.module Переиспользуемый код для проектов coder/ @telegram.module/
.api Коннектор к внешнему API coder/ @ozon.api/
.tool Утилита / инструмент coder/ @md-compile.tool/
.server Описание сервера infra/ @dev-pro.server/
.infra Инфраструктурный компонент infra/ @nginx.infra/

Правило выбора суффикса

Обслуживает платформу?   → system/  → .agent / .service / .domain / .coder
Используется в проектах? → coder/   → .module / .api / .tool
Описывает сервер?        → infra/   → .server / .infra

3. СТРУКТУРА КОМПОНЕНТА

Обязательные файлы

Тройка AI.md + CLAUDE.md + README.md создаётся всегда вместе в каждом компоненте.

Файл Все типы Назначение
AI.md ✅ всегда роль и протокол для любого AI
CLAUDE.md ✅ всегда AI.md + Claude-специфичное
README.md ✅ всегда AI.md + объяснения для людей
index.yaml ✅ всегда метаданные, класс, зависимости

Минимальная структура по типу

AI-компонент (@dispatcher.agent/):

@dispatcher.agent/
├── AI.md          ← роль, правила, протокол (для любого AI)
├── CLAUDE.md      ← AI.md + Claude-специфичное
├── README.md      ← AI.md + объяснения для людей
└── index.yaml     ← метаданные (тип, версия, зависимости)

CODE-компонент (@ozon.api/):

@ozon.api/
├── AI.md          ← протокол использования для AI
├── CLAUDE.md      ← AI.md + Claude-специфичное
├── README.md      ← описание, API, примеры для людей
├── index.yaml     ← метаданные
├── src/           ← исходный код
└── tests/         ← тесты

Гибридный (@scheduler.service/):

@scheduler.service/
├── AI.md          ← роль и протокол
├── CLAUDE.md      ← AI.md + Claude-специфичное
├── README.md      ← для людей
├── index.yaml     ← метаданные
├── src/           ← исполняемый код
└── tests/         ← тесты

index.yaml

id: scheduler
type: service        # agent / service / module / api / tool / domain / coder
layer: system        # system / coder / infra
version: "1.0.0"
status: active       # draft / active / deprecated / archived
class: ServiceComponent           # базовый класс из реестра
parent: system/                   # слой-родитель
extends: projector/templates/@service/   # шаблон-родитель
deps:
  - system/agents/dispatcher

4. НАСЛЕДОВАНИЕ

Каждый компонент — экземпляр класса. Класс определён на уровне выше.

Цепочка

arch-component-structure.md          ← АБСТРАКТНЫЙ КЛАСС
  Определяет: файлы, суффиксы, правила

projector/templates/@{суффикс}/      ← ШАБЛОН (конкретный класс)
  Воплощает: структуру с плейсхолдерами

system/@{имя}.{суффикс}/            ← ЭКЗЕМПЛЯР
coder/@{имя}.{суффикс}/             ← ЭКЗЕМПЛЯР
  Реализует: конкретный компонент по шаблону

Правила наследования

  1. Экземпляр объявляет родителя: extends: в index.yaml
  2. Шаблон ссылается на стандарт: extends: в frontmatter
  3. Стандарт ссылается на концепцию: parent: в frontmatter
  4. Нельзя создать экземпляр без шаблона — нельзя создать шаблон без стандарта

Пример: API-коннектор

arch-component-structure.md           class Component { abstract }
  ↓ extends
projector/templates/@api/             class APIComponent(Component) { template }
  ↓ инстанциирует
coder/@ozon.api/                      ozon = APIComponent("ozon")
  index.yaml → extends: projector/templates/@api/

Реестр базовых классов

Класс Стандарт Шаблон
Component arch-component-structure.md projector/templates/@{тип}/
Project arch-project-structure.md projector/templates/@{тип}-проект/
Document arch-document-system.md projector/templates/docs/
Stack arch-stack-bootstrap.md projector/templates/@it/stacks/{стек}/

Полный реестр: arch-class-system.md

5. ЖИЗНЕННЫЙ ЦИКЛ КОМПОНЕНТА

Статус фиксируется в index.yaml → поле status.

Статус Описание
draft Создаётся, не используется
active Работает, можно использовать
deprecated Устарел, есть замена — ссылка на неё
archived Не используется, перенесён в _archive/

Переходы

draft → active        после первого успешного использования
active → deprecated   появилась лучшая реализация
deprecated → archived через 1 версию платформы

Версионирование

Версия в index.yaml → поле version: MAJOR.MINOR.PATCH

Изменение Что меняет
PATCH исправление ошибок, без изменения интерфейса
MINOR новые возможности, обратно совместимо
MAJOR сломан интерфейс, требует обновления зависимых

При MAJOR — уведомить все зависимые компоненты через deps:.

CHANGELOG компонента

При MAJOR или MINOR изменениях — вести CHANGELOG.md в корне компонента:

# CHANGELOG — @{имя}.{тип}

## [2.0.0] 2026-04-11 — BREAKING CHANGE
### Изменено
- Переименован метод `process()` → `execute()` — обновить все вызовы
- Изменён формат входных данных: `{old}` → `{new}`

### Удалено
- Убран устаревший параметр `legacy_mode`

### Миграция
```bash
# что сделать зависимым компонентам
sed -i 's/process(/execute(/g' src/*.py

[1.1.0] 2026-03-01

Добавлено

[1.0.0] 2026-02-01

**Правило breaking change:**

✅ MAJOR версия → CHANGELOG.md обязателен
✅ В CHANGELOG.md раздел "### Миграция" с командами обновления
✅ Уведомить зависимые компоненты через issues или комментарий в deps:
❌ Тихо сломать интерфейс без записи в CHANGELOG.md

---

## 6. ПРАВИЛА СОЗДАНИЯ

1. Имя: `@{имя}.{суффикс}/` — строчные буквы, дефис как разделитель
2. Суффикс — из реестра §2, не изобретать новые без согласования
3. Класс-родитель объявлен в `index.yaml` → `extends:`
4. Нет шаблона → нельзя создать экземпляр (создать шаблон сначала)
5. Тройка AI.md + CLAUDE.md + README.md создаётся всегда вместе
6. Один компонент — одна ответственность
7. При MAJOR изменении — уведомить зависимые компоненты

### Bootstrap нового компонента
  1. Определить суффикс (§2)
  2. Найти шаблон: projector/templates/@{суффикс}/
  3. Скопировать шаблон → @{имя}.{суффикс}/
  4. Заполнить index.yaml (id, type, layer, extends, deps)
  5. Заполнить AI.md / README.md
  6. Зарегистрировать в индексе родительского слоя (операция СВЯЗЫВАНИЕ)
---

## 7. ПРОЕКТ VS КОМПОНЕНТ

Граница между понятиями бывает неочевидна. Таблица различий:

| Критерий | Компонент `@{имя}.{тип}/` | Проект `projects/{тип}/{имя}/` |
|----------|--------------------------|-------------------------------|
| **Форма имени** | `@имя.суффикс` | `имя/` или `@класс-имя/` |
| **Назначение** | Автономная функция платформы | Конкретная работа с результатом |
| **Жизненный цикл** | active → deprecated → archived | фазы 0–15 → завершён |
| **Переиспользование** | ✅ используется другими | ❌ уникален, не переиспользуется |
| **Владелец** | платформа | оператор / клиент |
| **Результат** | код / AI.md / docker-сервис | документация / ПО / данные |
| **Где живёт** | system/, coder/, infra/ | projects/org/, projects/sys/ |

**Диаграмма:**

ПЛАТФОРМА
│
├── КОМПОНЕНТЫ (переиспользуемые единицы)
│ ├── system/@sentinel.agent/ ← AI-агент платформы
│ ├── coder/@drupal.coder/ ← специализированный кодер
│ └── infra/@dev-pro.server/ ← конфиг сервера
│
└── ПРОЕКТЫ (конкретные работы)
├── projects/org/lideravto-new/ ← IT-проект клиента
│ использует: @drupal.coder (компонент)
│ деплоится на: @dev-pro.server (компонент)
│
└── projects/sys/platform-update/ ← системный проект
результат попадает в: arch/ (знания платформы)

**Правило различия:** если "это можно использовать в другом проекте" → компонент. Если "это делается один раз для конкретного заказчика" → проект.

---

## 8. РАЗРАБОТКА С AI-АГЕНТАМИ

### Зачем

При росте проекта AI теряет контекст — путается в зависимостях, держит в голове лишнее.
**Решение:** разбивать работу на независимые контекстблоки, каждый из которых помещается в контекст за один сеанс.

### Паттерн: блок (контекстблок)

**Блок** = квант работы, помещающийся в контекст AI за один сеанс.

| Критерий | Значение |
|----------|----------|
| **Размер** | 150–300 строк кода / 200–400 строк docs |
| **Автономность** | Работает независимо |
| **Тестируемость** | Тестируется изолированно |
| **Полнота** | Решает одну законченную задачу |

**Типы блоков:**

| Тип | Что | Примеры |
|-----|-----|---------|
| `CODE` | Код приложения | API, UI компоненты, скрипты |
| `DOCS` | Документация | концепция, руководство |
| `OPS` | Операции | деплой, бэкап, миграции |
| `DESIGN` | Архитектура | схемы, модели данных |
| `TEST` | Тесты | unit, e2e, интеграция |
| `CONTENT` | Контент | тексты, данные |

**Логическое vs Физическое:**

Сначала описать логически. Физическую папку создавать только если блок >300 строк.

Малый блок (< 300 строк) — логически в CLAUDE.md стадии:

dev/
├── CLAUDE.md -- описывает блоки filters, search
└── catalog.py -- код всех блоков в одном файле

Большой блок (> 300 строк) — физическая папка:

dev/
├── CLAUDE.md
└── import/
├── CLAUDE.md -- описание блока
├── CACHE.yaml -- входные данные / зависимости
└── lib/ -- результаты (код)

### Паттерн: поколения (инкрементальные версии блока)

**Поколение** = версия одного блока (v1, v2, v3...).
Применять если блок > 300 строк — разбить на инкрементальные части.

Принципы:
- Каждое поколение добавляет функциональность к предыдущему
- Каждое поколение помещается в контекст (~300–500 строк)
- Каждое поколение можно задеплоить отдельно

Схема в YAML (в CLAUDE.md блока):

```yaml
block:
  name: import
  type: CODE
  status: in_progress
  current_version: v2

generations:
  v1:
    description: "MVP: базовый парсинг CSV"
    size: 300 строк
    deliverables: [парсинг, базовая категоризация]
    status: deployed
  v2:
    description: "Модульная lib/ архитектура"
    size: 400 строк
    deliverables: [lib/parser, lib/mapper, lib/loader]
    status: in_progress
    depends_on: [v1]

Физическая организация:

import/
├── CLAUDE.md       -- описание всех поколений
├── lib/            -- текущее поколение (v2)
│   ├── parser.py
│   └── loader.py
└── arh/
    └── v1/         -- архив v1
        └── import.py

Иерархия CLAUDE.md при работе с агентом

CLAUDE.md (workspace)
    |
projects/org/CLAUDE.md
    |
projects/org/{name}/CLAUDE.md     -- L3: проект (стратегия)
    |
{name}/dev/CLAUDE.md              -- L4: стадия (блоки стадии)
    |
{name}/dev/import/CLAUDE.md       -- L5: блок (поколения, кеш)

Алгоритм работы с блоком

1. Определить стадию: dev / testing / ...
2. Определить блок: import / catalog / ...
3. Определить поколение: v1 / v2 / ...
4. Загрузить контекст: CLAUDE.md + CACHE.yaml
5. Реализовать поколение: в рамках блока
6. Проверить: размер <= 300 строк? тесты проходят?
7. Обновить статус в CLAUDE.md
8. Зафиксировать (git commit)

Ситуационные рекомендации

Ситуация Решение
Блок > 300 строк Разбить на поколения v1, v2, v3
Агент "забывает" контекст Создать физический блок с CLAUDE.md + CACHE.yaml
Несколько блоков в сеансе Работать только с одним блоком за сеанс
Зависимости между блоками Записать в CACHE.yaml resolved с результатами deploy/
Блок готов, начинаем следующий Обновить CLAUDE.md статус → новый сеанс

Чеклисты

Создание нового блока:
- [ ] Определить тип (CODE/DOCS/OPS/DESIGN/TEST)
- [ ] Оценить размер
- [ ] Если > 300 строк — спланировать поколения
- [ ] Создать CLAUDE.md с метаданными
- [ ] Создать CACHE.yaml с зависимостями
- [ ] Добавить блок в CLAUDE.md стадии

Реализация поколения:
- [ ] Прочитать CLAUDE.md блока и родительской стадии
- [ ] Прочитать CACHE.yaml
- [ ] Реализовать только то, что в deliverables этого поколения
- [ ] Написать тесты
- [ ] Обновить статус в CLAUDE.md
- [ ] Коммит: feat({блок}): {поколение} - {описание}

9. РОЛЬ VS АГЕНТ: КАК РАЗЛИЧАТЬ

В разговоре

"переключись в режим Архитектор"   -- роль
"запусти агент coder-agent"        -- агент
"запусти архитектора"              -- неясно (уточнять!)

В логах

# Роль (диалог с человеком):
[2026-03-27 10:00] роль=Архитектор сессия=abc123: обновил PLATFORM.md

# Агент (автономно):
[2026-03-27 10:00] агент=architect-agent задача=task-042: обновил PLATFORM.md

В конфигах (schedule.yaml)

# Агент — можно ставить в cron:
schedule:
  - cron: "0 3 * * *"
    agent: infra-agent      # правильно

# Роль — нельзя ставить в cron (нет человека):
schedule:
  - agent: Архитектор       # НЕПРАВИЛЬНО, роль не процесс

10. СВЯЗАННЫЕ ДОКУМЕНТЫ

Родитель:
- arch-filesystem-structure.md — файловая система платформы

Прямые потомки (child):
- arch-component-lifecycle.md — создание и жизненный цикл компонента
- arch-monitor-protocol.md — протокол мониторинга агентов
- arch-agent-registry.md — реестр агентов
- arch-stack-bootstrap.md — стандарт стека

Связанные:
- arch-project-structure.md — структура проектов
- arch-class-system.md — реестр классов платформы
- arch-document-linking.md — операция СВЯЗЫВАНИЕ