architecture.md

Версия: 2.0.0
Дата: 2025-11-18
Статус: Актуальная архитектура

Структура системы

/opt/claude-workspace/
│
├── CLAUDE.md                     ← Точка входа (200 токенов)
├── index.yaml                    ← Индекс проектов/инфры (100 токенов)
│
├── system/                       ← Системные агенты (код AI)
│   ├── docs/                     ← Документация про систему
│   │   ├── architecture.md       ← Этот файл
│   │   ├── structure.md          ← Структура файлов
│   │   └── agents.md             ← Список агентов
│   │
│   ├── README.md                 ← Описание системы
│   ├── claude-code.ai.md         ← Агент: Claude Code
│   ├── orchestrator.ai.md        ← Агент: Оркестратор
│   ├── terminal.ai.md            ← Агент: Терминал
│   └── integrator.ai.md          ← Агент: Интегратор
│
├── platform/                     ← Стандарты платформы
│   ├── docs/                     ← Документация про платформу
│   │   └── rules.md              ← Правила платформы
│   │
│   ├── standard.yaml             ← Стандарты
│   ├── procedures/               ← Процедуры
│   ├── templates/                ← Шаблоны
│   └── agents/                   ← Конфиги исполнителей
│       ├── project.yaml
│       └── infra.yaml
│
├── projects/                     ← Приложения
│   ├── index.yaml
│   └── {name}/
│       ├── CLAUDE.md
│       └── index.yaml
│
└── infra/                        ← Инфраструктура
    ├── index.yaml
    └── {name}/
        ├── config.yaml           ← usage: ready | project
        └── CLAUDE.md             ← Если usage=project

Уровни абстракции

УРОВЕНЬ 0: Base (Workspace)

Аналог: BIOS + OS в компьютере
Что: Базовая настройка + глобальные правила
Файлы:
- CLAUDE.md - точка входа, глобальные правила
- index.yaml - индекс системы
- terminal.ai.md - интерфейс (опционально)

Роль: Управляющий агент работает здесь (не переходит в подпапки)

УРОВЕНЬ 1: Platform

Аналог: Операционная система
Что: Стандарты, процедуры, правила
Папка: platform/

УРОВЕНЬ 2: Programs

Аналог: Программы
Что: Конкретные проекты и инфраструктура
Папки: projects/, infra/

Процессы системы

ПРОЦЕСС 1: Claude Code (штатное)

cd папка/ → автоматически читает claude.md → базовый контекст

Механизм: Штатный Claude Code
Управляем: Содержимое claude.md

ПРОЦЕСС 2: Platform агенты (управление)

Оркестратор → запускает → Исполнители (project-agent, infra-agent)

Механизм: Task tool
Контекст: system/.ai.md, platform/

ПРОЦЕСС 3: Оператор (интерфейс)

Человек → terminal.ai.md → команды/меню

Механизм: Интерфейс взаимодействия
Файл: terminal.ai.md

ПРОЦЕСС 4: Интеграции (внешние системы)

API → конфигурации → внешние системы (Ozon, доставка, MCP)

Механизм: Интегратор
Конфиги: platform/integrations/

Агенты системы

Системные агенты (в system/)

1. Claude Code Agent
- Файл: system/claude-code.ai.md
- Роль: Работа с инструментами Claude Code
- Задачи: Read, Write, Bash, Task, Grep, Glob
- Правила: Когда что использовать, подтверждения

2. Оркестратор
- Файл: system/orchestrator.ai.md
- Роль: Управление проектами и инфраструктурой
- Задачи: Запуск исполнителей, чтение индексов, процедуры
- Местоположение: Работает из /opt/claude-workspace/

3. Терминал
- Файл: system/terminal.ai.md
- Роль: Интерфейс с оператором
- Задачи: Меню, команды, навигация

4. Интегратор
- Файл: system/integrator.ai.md
- Роль: Управление API и MCP серверами
- Задачи: Подключение к внешним системам

Исполнители (в projects/, infra/)

5. Project-agent
- Файл: projects/{name}/CLAUDE.md
- Роль: Работа С конкретным проектом
- Запуск: Через Task оркестратором
- Задачи: Обновить код, проверить, деплой

6. Infra-agent
- Файл: infra/{name}/CLAUDE.md
- Роль: Создание инфраструктуры
- Запуск: Через Task оркестратором
- Задачи: Terraform, развертывание, настройка

Опционально

7. Monitor
- Роль: Мониторинг системы
- Задачи: Health checks, логи

8. Security
- Роль: Безопасность
- Задачи: Проверки, бэкапы

Загрузка контекста (сегменты)

CORE (всегда, 200 токенов)

Содержит:
- Роль: "Ты управляющий агент"
- Глобальные правила
- Ссылки на system/*.ai.md

STARTUP (при старте, 400 токенов)

index.yaml               (100 токенов)
terminal.ai.md           (300 токенов, опционально)

ON-DEMAND (по требованию)

system/orchestrator.ai.md     (500 токенов) - работа с проектами
system/claude-code.ai.md      (400 токенов) - детали инструментов
system/integrator.ai.md       (300 токенов) - API, MCP
platform/standard.yaml        (1000 токенов) - стандарты

Каскадирование правил

УРОВЕНЬ 0: Workspace
├─ Глобальные правила (формат, подтверждения, безопасность)
│  ↓ КАСКАД (наследуются вниз)
│
УРОВЕНЬ 1: Platform
├─ Стандарты (структура, именование)
│  ↓ КАСКАД (наследуются вниз)
│
УРОВЕНЬ 2: Projects/Infra
└─ Специфика проекта (не каскадируется)

Что наследуется:
- ✅ Глобальные правила (формат ответа, подтверждения)
- ✅ Стандарты платформы (структура файлов, именование)
- ✅ Требования к index.yaml

Что НЕ наследуется:
- ❌ Роль оркестратора (только workspace)
- ❌ Правила управления (только platform)
- ❌ Специфика проекта (только свой проект)

Два типа инфраструктуры

Тип 1: ready (готовая)

# infra/@infra-dev-pro/config.yaml
infrastructure:
  usage: ready
  ip: 91.218.142.168

Использование:
- Оркестратор читает config.yaml напрямую
- Агент НЕ запускается
- Токены: ~300

Тип 2: project (создаваемая)

# infra/@infra-new-prod/config.yaml
infrastructure:
  usage: project
  status: planning

Использование:
- Оркестратор запускает infra-agent
- Агент создаёт инфраструктуру
- После создания: usage → ready
- Токены: ~2500

Работа архитектора

Роль архитектора:
- Читает: system/docs/, platform/docs/
- Проектирует: архитектуру, структуру
- Создаёт: код AI (system/*.ai.md, platform/*)

1. Читать документацию (docs/)
2. Проектировать систему
3. Создавать код AI (system/, platform/)
4. Агенты работают по коду AI

Режим работы:
- Архитектор работает с docs/
- Агенты работают с *.ai.md

Принципы

См. system/docs/structure.md для детальных принципов структуры.