Версия: 2.0.0
Дата: 2025-11-18
Агент = Claude Code + Контекст
Claude Code (исполнитель)
+
Контекст из *.ai.md (роль, правила, задачи)
=
Агент (действующая сущность)
Важно:
- Файл *.ai.md ≠ агент
- Файл = описание роли для агента
- Агент = Claude Code, прочитавший этот файл
Контексты в system/*.ai.md
Файл: system/claude-code.ai.md
Роль: Базовый уровень работы с инструментами Claude Code
Ответственность:
- Инструменты: Read, Write, Edit, Bash, Task, Grep, Glob
- Правила использования (когда что применять)
- Подтверждения (что требует разрешения пользователя)
- Параллельные вызовы
- Безопасность (apt -y, DEBIAN_FRONTEND)
Загружается: По требованию (детали инструментов)
Токены: ~400
Файл: system/orchestrator.ai.md
Роль: Управление проектами и инфраструктурой
Ответственность:
- Управление проектами (чтение index.yaml, запуск project-agent)
- Управление инфраструктурой (определение типа ready/project, запуск infra-agent)
- Запуск исполнителей через Task tool
- Работа с индексами
- Процедуры управления
Поведение:
- Работает из /opt/claude-workspace/
- НЕ переходит в projects/ или infra/ напрямую
- Запускает агентов-исполнителей
- Передаёт контекст из CLAUDE.md проектов/инфры
Загружается: Всегда (основная роль)
Токены: ~500
Типичные задачи:
- "Обнови проект marketplace"
- "Подключись к серверу dev-pro"
- "Создай новую инфру prod-us"
Файл: system/terminal.ai.md
Роль: Интерфейс взаимодействия с оператором
Ответственность:
- Меню навигации
- Команды управления
- Форматирование вывода для оператора
- Помощь по командам
Поведение:
- Показывает меню при запросе
- Обрабатывает команды
- Переводит запросы оператора в задачи для оркестратора
Загружается: При старте (опционально)
Токены: ~300
Интерфейс:
1. Проекты
2. Инфраструктура
3. Интеграции
4. Система
Файл: system/integrator.ai.md
Роль: Управление интеграциями с внешними системами
Ответственность:
- API (Ozon, доставка, платежи)
- MCP серверы
- Подключения к внешним сервисам
- Конфигурации интеграций
Поведение:
- Читает конфиги из platform/integrations/
- Управляет подключениями
- Обрабатывает запросы к API
Загружается: По требованию
Токены: ~300
Контексты в projects/{name}/CLAUDE.md или infra/{name}/CLAUDE.md
Файл: projects/{name}/CLAUDE.md
Роль: Работа С конкретным проектом
Запуск: Оркестратором через Task tool
Контекст загружается:
ГЛОБАЛЬНЫЕ ПРАВИЛА:
{read('/opt/claude-workspace/CLAUDE.md')}
КОНТЕКСТ ПРОЕКТА:
cd /opt/claude-workspace/projects/{name}/
{read('CLAUDE.md')}
{read('design/spec.md')}
{read('index.yaml')}
Ответственность:
- Обновить код согласно спецификации
- Проверить тесты
- Деплой на сервер
- Вернуть результат оркестратору
Ограничения:
- Работает ТОЛЬКО в своей папке
- НЕ изменяет platform/
- НЕ изменяет другие проекты
- Обновляет index.yaml при изменениях
Токены: ~1500 (загрузка контекста)
Типичные задачи:
- "Обнови marketplace согласно спеке"
- "Проверь тесты pim-drupal"
- "Задеплой изменения на сервер"
Файл: infra/{name}/CLAUDE.md
Роль: Создание инфраструктуры
Запуск: Оркестратором через Task tool (только для usage=project)
Контекст загружается:
ГЛОБАЛЬНЫЕ ПРАВИЛА:
{read('/opt/claude-workspace/CLAUDE.md')}
КОНТЕКСТ ИНФРЫ:
cd /opt/claude-workspace/infra/{name}/
{read('CLAUDE.md')}
{read('design/plan.md')}
Ответственность:
- Создать terraform конфигурацию
- Развернуть сервер
- Настроить доступы
- Обновить config.yaml: usage=ready, status=active
- Вернуть результат
Жизненный цикл:
1. Создание проекта: usage=project, status=planning
2. Работа агента: usage=project, status=creating
3. Инфра развёрнута: usage=ready, status=active (тип меняется!)
Токены: ~2000 (загрузка контекста)
Типичные задачи:
- "Создай prod сервер в US"
- "Разверни staging окружение"
Файл: system/monitor.ai.md (если создан)
Роль: Мониторинг системы
Ответственность:
- Health checks (проверка работоспособности)
- Проверка актуальности index.yaml
- Логирование
- Алерты при проблемах
Загружается: По расписанию или по требованию
Файл: system/security.ai.md (если создан)
Роль: Безопасность системы
Ответственность:
- Проверка безопасности кода
- Бэкапы
- Аудит изменений
- Проверка прав доступа
Загружается: По требованию
┌─────────────┐
│ ОПЕРАТОР │
└──────┬──────┘
│
terminal.ai.md
│
↓
┌────────────────────────────────────────┐
│ CLAUDE CODE │
│ Читает: CLAUDE.md │
└──────────────┬─────────────────────────┘
│
↓ "Читай system/orchestrator.ai.md"
┌────────────────────────────────────────┐
│ ОРКЕСТРАТОР │
│ Контекст: system/orchestrator.ai.md │
│ Управляет: проектами, инфрой │
└──────────────┬─────────────────────────┘
│
┌───────┴────────┬────────────┐
↓ ↓ ↓
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ Project- │ │ Infra- │ │ Integrator │
│ agent │ │ agent │ │ │
│ │ │ │ │ │
│ Task tool │ │ Task tool │ │ system/ │
└─────────────┘ └─────────────┘ └──────────────┘
Сценарий: "Обнови проект marketplace"
1. Оператор → Терминал
Команда: "Обнови marketplace"
2. Терминал → Оркестратор
Интерпретация команды
3. Оркестратор:
- Читает index.yaml → находит marketplace
- Читает platform/agents/project.yaml → конфиг запуска
- Запускает Task(subagent="general-purpose")
4. Task → Project-agent
- cd projects/marketplace/
- Загружает контекст (CLAUDE.md, spec.md)
- Выполняет работу
- Возвращает результат
5. Оркестратор → Оператор
Отчёт о выполнении
Файл: platform/agents/project.yaml
agent:
type: "Task"
subagent: "general-purpose"
context:
global_rules: "/opt/claude-workspace/CLAUDE.md"
project_context: "{project_path}/CLAUDE.md"
project_spec: "{project_path}/design/spec.md"
project_index: "{project_path}/index.yaml"
prompt_template: |
ГЛОБАЛЬНЫЕ ПРАВИЛА:
{global_rules}
КОНТЕКСТ ПРОЕКТА:
cd {project_path}
Прочитай CLAUDE.md
Прочитай design/spec.md
Прочитай index.yaml
ЗАДАЧА:
{user_task}
ВЕРНУТЬ РЕЗУЛЬТАТ оркестратору
Файл: platform/agents/infra.yaml
agent:
type: "Task"
subagent: "general-purpose"
context:
global_rules: "/opt/claude-workspace/CLAUDE.md"
infra_context: "{infra_path}/CLAUDE.md"
infra_plan: "{infra_path}/design/plan.md"
prompt_template: |
ГЛОБАЛЬНЫЕ ПРАВИЛА:
{global_rules}
КОНТЕКСТ ИНФРЫ:
cd {infra_path}
Прочитай CLAUDE.md
Прочитай design/plan.md
ЗАДАЧА:
Создать инфраструктуру согласно плану
ПОСЛЕ СОЗДАНИЯ:
Обновить config.yaml: usage=ready, status=active
ВЕРНУТЬ РЕЗУЛЬТАТ
1. Определить роль
- [ ] Системный (в system/) или исполнитель (в projects/infra/)
- [ ] Задачи агента
- [ ] Когда вызывается
2. Создать контекст
- [ ] Файл: system/{name}.ai.md или projects/{name}/CLAUDE.md
- [ ] Описать роль
- [ ] Описать задачи
- [ ] Описать ограничения
3. Документировать
- [ ] Добавить в system/docs/agents.md
- [ ] Описать в system/README.md
4. Настроить запуск (если исполнитель)
- [ ] Создать platform/agents/{name}.yaml
- [ ] Шаблон prompt
- [ ] Конфигурация Task
5. Обновить индексы
- [ ] Обновить system/index.yaml
- [ ] Обновить platform/index.yaml (если нужно)
Чёткое разделение ролей:
- Системные агенты: управление
- Исполнители: работа
Изоляция:
- Исполнители работают только в своей папке
- НЕ изменяют platform/ или другие проекты
Контекст:
- Всегда включать глобальные правила в Task prompt
- Передавать специфичный контекст
Возврат результата:
- Исполнители ВСЕГДА возвращают результат оркестратору
- Не работают "в фоне"
Версия: 2.0.0
Дата: 2025-11-18
Статус: Актуальный справочник