structure-component-standard.md

type: standard
aspect: structure
title: "Стандарт компонента платформы"
version: 1.0.0
date: 2026-03-30
status: active
source: extracted from concept/PLATFORM_ARCHITECTURE.md v0.1.0

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

ЧТО ТАКОЕ КОМПОНЕНТ?

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

Признаки компонента:

ТИПЫ КОМПОНЕНТОВ (по реализации)

1. AI-компонент

Что: Набор инструкций для Claude
Формат: .md, .ai.md, CLAUDE.md
Исполнение: Claude читает и следует

component-name/
├── CLAUDE.md           ← Описание и протокол
├── docs/               ← Детальная документация
└── templates/          ← Шаблоны (если нужны)

2. CODE-компонент

Что: Программный код
Формат: .py, .js, .sh
Исполнение: Интерпретатор/компилятор

component-name/
├── src/                ← Исходный код
├── tests/              ← Тесты
├── README.md           ← Документация
└── requirements.txt    ← Зависимости (Python)

3. ГИБРИДНЫЙ компонент (AI + CODE)

Что: AI-инструкции + программный код
Формат: CLAUDE.md + src/
Исполнение: Claude управляет кодом

@component-name.type/
├── CLAUDE.md           ← AI-протокол (обязательно)
├── index.yaml          ← Метаданные (обязательно)
├── README.md           ← Документация для людей
├── src/                ← Код
│   ├── main.py
│   └── ...
├── tests/              ← Тесты
├── docs/               ← Детальная документация
│   ├── API.md
│   └── EXAMPLES.md
├── templates/          ← Шаблоны (если нужны)
└── requirements.txt    ← Зависимости

ТИПЫ (суффиксы именования)

.service    — Сервис (scheduler, monitor, dms)
.agent      — AI-агент (projector, dispatcher)
.tool       — Инструмент (cli, scripts)
.lib        — Библиотека (connectors, utils)
.app        — Приложение (web, mobile)
.system     — Системный компонент (core, platform)

Когда использовать @-префикс и суффикс:
- Если компонент модульный и переиспользуемый
- Если нужно явно указать тип в файловой системе

ШАБЛОН CLAUDE.md

---
type: {service|agent|library|tool}
title: "{Название компонента}"
version: {X.Y.Z}
level: {L2|L3|L4|L5|L6}
---

# {Название}

**Уровень:** {L2-L6}
**Тип:** {service|agent|library|tool}
**Зависимости:** {список компонентов}

---

## Назначение

{Что делает компонент в 1-2 предложениях}

---

## Как использовать

### Для AI-агента
{Протокол взаимодействия}

### Для программиста
{API, команды}

---

## Зависимости

- {component-name} — {зачем}

---

## Примеры

{Примеры использования}

ШАБЛОН index.yaml

id: component-name
type: service  # service|agent|library|tool
level: L3      # L2|L3|L4|L5|L6
version: "1.0.0"

dependencies:
  - component-id: library
    version: ">=1.0.0"

provides:
  - capability: "document-management"
    interface: "python-api"

metadata:
  owner: architect
  created: "YYYY-MM-DD"
  status: active  # draft|active|deprecated

Тип компонента	CLAUDE.md	index.yaml	README.md
AI-компонент	✅ обязательно	—	рекомендовано
CODE-компонент	—	рекомендовано	✅ обязательно
Гибридный	✅ обязательно	✅ обязательно	✅ обязательно