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

КОМПОНЕНТ = ОПИСАНИЕ + КОД + ДАННЫЕ + НАСТРОЙКИ

┌─────────────────────────────────────────────────────────────────────────────┐
│  ТИП           │  ЧТО                      │  ГДЕ                           │
├────────────────┼───────────────────────────┼────────────────────────────────┤
│  BUSINESS      │  Бизнес-контейнер         │  pirotehnika/, lider/          │
│  CODE          │  Сайт, сервис, API        │  @domain/, @name.type/         │
│  DATA          │  Данные, каталоги         │  _shared/, products/           │
│  INFRA         │  Серверы, хранилища       │  infra/@name.server/           │
│  PLATFORM      │  Методология, агенты      │  architect/, system/           │
│  CONNECTOR     │  Коннектор к API/БД       │  library/connectors/           │
│  AGENT         │  AI-агент                 │  system/agents/                │
└─────────────────────────────────────────────────────────────────────────────┘

{component}/
│
├── CLAUDE.md           ← Контекст для AI
├── index.yaml          ← Метаданные и связи
├── README.md           ← Описание для человека
├── .env                ← Настройки (не в git)
│
├── design/             ← Проектирование
├── solution/           ← Код и скрипты
├── data/               ← Данные
└── archive/            ← Архив

# {Название компонента}

**Тип:** {business|code|data|infra|platform}
**Статус:** {active|development|archived}
**Версия:** X.Y.Z

---

## КОНТЕКСТ

{Что это и зачем — 2-3 предложения}

## СТРУКТУРА

{Что где лежит}

## ПРАВИЛА

{Как работать с компонентом}

## СВЯЗИ

- **Родитель:** {ссылка}
- **Зависит от:** {список}
- **Предоставляет:** {список}

name: "{Название}"
type: "{тип}"
status: "{active|development|archived}"
version: "X.Y.Z"

parent: "../"
children:
  - child1/
  - child2/

depends_on:
  - {зависимость}

provides_to:
  - {потребитель}

hub: "projects/{path}/"  # если есть данные в Hub

# {Название}

{Краткое описание — 1 предложение}

## Быстрый старт

{Как запустить/использовать — шаги}

## Структура

{Что где лежит — дерево или таблица}

## Ссылки

- [Документация](design/PROJECT.md)
- [Настройки](.env.example)

# {Название компонента}
# Описание настроек

# Категория 1
KEY1=value1
KEY2=value2

# Категория 2
KEY3=value3

design/
├── PROJECT.md          ← Описание проекта (обязательно)
├── RULES.md            ← Правила домена (если есть)
└── ARCHITECTURE.md     ← Архитектура (если сложный)

# {Название}: Проект

**Версия:** X.Y.Z

## Цель
{Зачем нужен проект}

## Scope
{Что входит / не входит}

## Решения
{Ключевые архитектурные решения}

solution/
├── scripts/            ← Скрипты (*.py, *.sh)
├── src/                ← Исходный код
└── tests/              ← Тесты

data/
├── input/              ← Входящие данные
├── output/             ← Результаты
└── cache/              ← Кэш

archive/
└── {YYYY-MM-DD}_{description}/

{business}/
├── [БАЗОВАЯ СТРУКТУРА]
│
├── _shared/            ← + Общие данные бизнеса
│   ├── CLAUDE.md
│   ├── products/
│   └── work/
│
├── @{domain}/          ← + Дочерние CODE-проекты
├── @{name}.api/
└── @{name}.service/

@{name}.{type}/
├── [БАЗОВАЯ СТРУКТУРА]
│
├── docker-compose.yaml ← + Контейнеризация
├── solution/
│   ├── src/            ← + Исходный код приложения
│   └── tests/          ← + Тесты
└── config/             ← + Конфигурации
    ├── .env.example
    └── settings.yaml

@{name}.server/  или  @{name}.storage/
├── [БАЗОВАЯ СТРУКТУРА]
│
├── infra.yaml          ← + Характеристики
├── design/
│   ├── SECURITY.md     ← + Безопасность, доступы
│   └── SERVICES.md     ← + Список сервисов
└── solution/
    └── scripts/        ← + Bash-скрипты управления

type: "server|storage"
provider: "{провайдер}"
location: "{дата-центр}"

# Для серверов
ip: "X.X.X.X"
cpu: "N cores"
ram: "N GB"
disk: "N GB"
os: "Ubuntu XX.XX"

# Для хранилищ
endpoint: "s3://{bucket}"
size: "N GB"

_shared/  или  {data}/
├── [БАЗОВАЯ СТРУКТУРА]
│
├── MASTER.md           ← + Описание структуры данных
├── data/
│   ├── index/          ← + Мастер-данные (итоговые)
│   ├── originals/      ← + Оригиналы от поставщиков
│   └── processed/      ← + Обработанные
└── solution/
    └── scripts/        ← + Скрипты обработки данных

architect/
├── [БАЗОВАЯ СТРУКТУРА]
│
├── theory/             ← + Теория (LOCKED)
├── concept/            ← + Концепция
├── standards/          ← + Стандарты (этот документ)
├── patterns/           ← + Паттерны
└── templates/          ← + Шаблоны

library/connectors/{type}/
├── {name}.py           ← Код коннектора
├── {name}.md           ← Документация API
├── {name}.test.py      ← Тесты
└── .env.example        ← Пример credentials

"""
{Название} Connector

Доступ к {система} API.
"""

class {Name}Connector:
    """Коннектор к {система}."""

    def __init__(self, credentials: dict):
        """Инициализация с credentials."""
        pass

    # Методы API

# {Название} Connector

**Система:** {название системы}
**API:** {тип API}
**Документация:** {ссылка на официальную документацию}

## Credentials

| Переменная | Описание |
|------------|----------|
| {NAME}_API_KEY | API ключ |
| {NAME}_CLIENT_ID | ID клиента |

## Методы

| Метод | Описание |
|-------|----------|
| get_* | Получить данные |
| update_* | Обновить данные |

## Примеры

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

system/agents/
└── {name}.ai.md        ← Контекст агента

# {Название} — AI-агент

**Версия:** X.Y.Z
**Тип:** {ассистент|исполнитель}

---

## РОЛЬ

{Кто ты — 1 предложение}

## ЗОНА ОТВЕТСТВЕННОСТИ

### Делаю
- {что делает агент}

### Не делаю
- {что не делает}

## АЛГОРИТМ

{Как принимаю решения — шаги}

## ПРАВИЛА

### Можно
- {разрешённые действия}

### Нельзя
- {запрещённые действия}

## ИНСТРУМЕНТЫ

- {какие инструменты использует}

## СВЯЗИ

- **Получает задачи от:** {кто}
- **Делегирует:** {кому}

UPPER_CASE.md    ← Документация (читают люди и AI)
lowercase.yaml   ← Данные/метаданные (читают программы)
lowercase.py     ← Код (исполняют машины)

                    │ BUSINESS │ CODE │ INFRA │ DATA │ PLATFORM │ CONNECTOR │ AGENT │
────────────────────┼──────────┼──────┼───────┼──────┼──────────┼───────────┼───────┤
CLAUDE.md           │    ✓     │  ✓   │   ✓   │  ✓   │    ✓     │     —     │   —   │
index.yaml          │    ✓     │  ✓   │   ✓   │  ○   │    ✓     │     —     │   —   │
README.md           │    ○     │  ✓   │   ✓   │  ○   │    ✓     │     —     │   —   │
.env                │    ○     │  ○   │   ○   │  —   │    ○     │     ✓     │   —   │
design/             │    ○     │  ✓   │   ✓   │  ○   │    ✓     │     —     │   —   │
solution/           │    —     │  ✓   │   ○   │  ○   │    ○     │     —     │   —   │
data/               │    —     │  ○   │   ○   │  ✓   │    —     │     —     │   —   │
archive/            │    ○     │  ○   │   ○   │  ○   │    ○     │     —     │   —   │
────────────────────┼──────────┼──────┼───────┼──────┼──────────┼───────────┼───────┤
_shared/            │    ✓     │  —   │   —   │  —   │    —     │     —     │   —   │
docker-compose.yaml │    —     │  ○   │   —   │  —   │    —     │     —     │   —   │
infra.yaml          │    —     │  —   │   ✓   │  —   │    —     │     —     │   —   │
MASTER.md           │    —     │  —   │   —   │  ✓   │    —     │     —     │   —   │
{name}.py           │    —     │  —   │   —   │  —   │    —     │     ✓     │   —   │
{name}.ai.md        │    —     │  —   │   —   │  —   │    —     │     —     │   ✓   │

✓ = обязательно    ○ = опционально    — = не применимо

$WORKSPACE/
│
├── CLAUDE.md                           ← Точка входа (терминал)
├── index.yaml                          ← Корневой индекс
│
├── architect/                          ← PLATFORM: методология
│   ├── CLAUDE.md
│   ├── index.yaml
│   ├── README.md
│   │
│   ├── theory/                         ← Теория (LOCKED)
│   │   ├── MERKABA.md
│   │   ├── QUESTIONS.md
│   │   ├── SYSTEMS.md
│   │   └── ASPECTS.md
│   │
│   ├── concept/                        ← Концепция
│   │   ├── PLATFORM.md
│   │   └── ARCHITECTURE.md
│   │
│   ├── standards/                      ← Стандарты
│   │   ├── structure/
│   │   │   ├── WORKSPACE.md
│   │   │   └── COMPONENTS.md           ← ЭТОТ ДОКУМЕНТ
│   │   ├── types/
│   │   ├── roles/
│   │   ├── formats/
│   │   └── processes/
│   │
│   ├── patterns/                       ← Паттерны
│   └── templates/                      ← Шаблоны
│
├── system/                             ← PLATFORM: агенты и код
│   ├── CLAUDE.md
│   ├── index.yaml
│   ├── README.md
│   │
│   ├── agents/                         ← AI-агенты
│   │   ├── coder-v1.ai.md
│   │   ├── infra.ai.md
│   │   ├── analyst.ai.md
│   │   └── ...
│   │
│   ├── connectors/                     ← Коннекторы
│   │   ├── marketplaces/
│   │   │   ├── ozon.py
│   │   │   ├── ozon.md
│   │   │   └── .env.example
│   │   ├── databases/
│   │   │   └── nocodb.py
│   │   └── communications/
│   │       └── telegram.py
│   │
│   └── lib/                            ← Библиотеки
│       ├── utils.py
│       ├── excel.py
│       └── dates.py
│
├── infra/                              ← INFRA: серверы и хранилища
│   ├── CLAUDE.md
│   ├── index.yaml
│   │
│   ├── @dev-pro.server/
│   │   ├── CLAUDE.md
│   │   ├── index.yaml
│   │   ├── infra.yaml
│   │   ├── design/
│   │   │   ├── PROJECT.md
│   │   │   ├── SECURITY.md
│   │   │   └── SERVICES.md
│   │   └── solution/scripts/
│   │
│   ├── @dev-prod-rf.server/
│   └── @beget-s3.storage/
│
├── pirotehnika/                        ← BUSINESS
│   ├── CLAUDE.md
│   ├── index.yaml
│   ├── README.md
│   │
│   ├── _shared/                        ← DATA: общие данные
│   │   ├── CLAUDE.md
│   │   ├── MASTER.md
│   │   ├── data/
│   │   │   ├── products/
│   │   │   └── ozon/
│   │   └── solution/scripts/
│   │
│   ├── @pirotehnika.spb.ru/            ← CODE: сайт
│   │   ├── CLAUDE.md
│   │   ├── index.yaml
│   │   ├── design/PROJECT.md
│   │   └── solution/
│   │
│   ├── @ozon.api/                      ← CODE: интеграция
│   │   ├── CLAUDE.md
│   │   ├── index.yaml
│   │   ├── design/
│   │   │   ├── PROJECT.md
│   │   │   └── RULES.md
│   │   └── solution/scripts/
│   │
│   └── @pim.service/                   ← CODE: сервис
│
├── lider/                              ← BUSINESS
│   ├── CLAUDE.md
│   ├── index.yaml
│   └── @lideravto.ru/
│
└── archive/                            ← Архив

┌─────────────────────────────────────────────────────────────────────────────┐
│                           ПЛАТФОРМА                                         │
│                                                                             │
│  ┌─────────────┐    определяет    ┌─────────────┐                          │
│  │ METHODOLOGY │─────────────────►│   AGENTS    │                          │
│  │  architect/ │                  │   system/   │                          │
│  └─────────────┘                  └──────┬──────┘                          │
│                                          │                                  │
│                                    управляют                                │
│                                          │                                  │
│  ┌─────────────┐    хранят        ┌──────▼──────┐                          │
│  │    DATA     │◄─────────────────│    INFRA    │                          │
│  │    Hub      │                  │    infra/   │                          │
│  └──────┬──────┘                  └──────┬──────┘                          │
│         │                                │                                  │
└─────────┼────────────────────────────────┼──────────────────────────────────┘
          │          обслуживают           │
          ▼                                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         БИЗНЕС-ПРОЕКТЫ                                      │
│                                                                             │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                     │
│  │ pirotehnika │    │    lider    │    │   seller1   │                     │
│  │  BUSINESS   │    │  BUSINESS   │    │  BUSINESS   │                     │
│  │             │    │             │    │             │                     │
│  │ ┌─────────┐ │    │ ┌─────────┐ │    │             │                     │
│  │ │  CODE   │ │    │ │  CODE   │ │    │             │                     │
│  │ │ @site   │ │    │ │ @site   │ │    │             │                     │
│  │ │ @api    │ │    │ └─────────┘ │    │             │                     │
│  │ │ @service│ │    │             │    │             │                     │
│  │ └─────────┘ │    │             │    │             │                     │
│  │ ┌─────────┐ │    │             │    │             │                     │
│  │ │  DATA   │ │    │             │    │             │                     │
│  │ │ _shared │ │    │             │    │             │                     │
│  │ └─────────┘ │    │             │    │             │                     │
│  └─────────────┘    └─────────────┘    └─────────────┘                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘