Agent Guide

Экосистема Oro

Облачная инфраструктура, философия эфемерных сред и принципы разработки

Экосистема Oro

Oro — платформа для облачной разработки, где человеческие и AI-разработчики работают как единая команда. Инфраструктура построена на принципе «cloud-first, ephemeral workspaces» — рабочие среды эфемерны, код живёт в Git, состояние синхронизируется через S3.

Архитектура платформы

┌─────────────────────────────────────────────────────────────┐
│                     Cloudflare DNS                          │
│          *.master.oro.ad    *.infra.oro.ad                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                    Kubernetes (Magnum)                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐ │
│  │  Coder   │  │  NGINX   │  │  cert-   │  │ Prometheus │ │
│  │          │  │  Ingress  │  │  manager │  │ + Grafana  │ │
│  └────┬─────┘  └──────────┘  └──────────┘  └────────────┘ │
│       │                                                     │
│  ┌────▼─────────────────────────────────────────────────┐  │
│  │              Coder Workspaces (Pods)                   │  │
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐          │  │
│  │  │ skill-    │ │ workspace-│ │ dev-      │  ...      │  │
│  │  │ manager   │ │ manager   │ │ playbook  │          │  │
│  │  └───────────┘ └───────────┘ └───────────┘          │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────────┐
│                    PS.KZ OpenStack                           │
│  S3 Object Storage  │  PostgreSQL (Trove)  │  VPN          │
└─────────────────────────────────────────────────────────────┘

Компоненты экосистемы

Репозитории

Репозиторий	Назначение	Агент
`oro-ad/oro-cli`	CLI для управления сессиями, OAuth, S3 sync	— (инфраструктура)
`oro-ad/oro-skills`	Плагин-маркетплейс для Claude Code	skill-manager
`oro-ad/coder-templates`	Terraform-шаблоны Coder workspaces	workspace-manager
`oro-ad/infra`	IaC — Terraform, K8s, OpenStack, Cloudflare	infra-manager
`oro-ad/development-playbook`	Документация и MCP-сервер	dev-playbook
`oro-ad/business-console`	Административная панель	—
`oro-ad/nuxt-claude-devtools-pro`	Nuxt DevTools интеграция с Claude Code	—
`oro-ad/ci-components`	Переиспользуемые GitLab CI/CD компоненты	—

Инфраструктура

Cloud Provider: PS.KZ (OpenStack), Казахстан
IaC: Terraform в два слоя — инфра (OpenStack ресурсы) + платформа (K8s ресурсы)
Оркестрация: Kubernetes через Magnum, автоскейлинг 2–15 нод
Workspaces: Coder — каждый workspace это pod в K8s с PVC
DNS: Cloudflare с wildcard-доменами *.master.oro.ad
TLS: cert-manager + Let's Encrypt (DNS-01 через Cloudflare)
Хранилище: S3-совместимое Object Storage на object.pscloud.io
CI/CD: GitLab CI с переиспользуемыми компонентами из ci-components

Философия разработки

Эфемерные среды

Workspace можно уничтожить и пересоздать в любой момент. Это означает:

Код живёт только в Git — коммитим и пушим регулярно
Состояние агента синхронизируется в S3 через oro-cli (CLAUDE.md, .claude/, memory)
Секреты приходят из переменных окружения Coder template, не хранятся на диске
Зависимости устанавливаются при создании workspace через postStart скрипт

Модули общаются свободно

Главный архитектурный принцип — любой модуль проекта должен иметь возможность:

Видеть другие модули — через shared-зависимости в pnpm workspaces или GitLab Package Registry (через GitLab Package Registry или pnpm workspaces)
Быть доступным снаружи в dev-режиме — каждый сервис получает внешний домен dev.<service>.oro.ad через Coder port-forwarding + NGINX Ingress
Получать документацию — через MCP-серверы (playbook, nuxt-remote, prisma)
Общаться с другими агентами — через AgentAPI (/oro-skills:talk)

Агент как участник команды

AI-агенты в Oro — не инструменты, а автономные участники команды:

Свойство	Реализация
Рабочее место	Coder workspace в K8s
Роль	`ORO_AGENT_ROLE` — определяет ответственность
Навыки	oro-skills plugin — 14 навыков для работы в команде
Коммуникация	Telegram (с человеком), AgentAPI (с агентами)
Доставка кода	Merge Requests через GitLab
Память	`.claude/` + memory files, синхронизируемые в S3
Непрерывность	Resume prompt при перезапуске

Автономный жизненный цикл

┌─ Запуск ──────────────────────────────────────────────────┐
│  oro prepare → oro restore → читает resume.md → начинает  │
└───────────────────────┬───────────────────────────────────┘
                        ▼
┌─ Работа ──────────────────────────────────────────────────┐
│  Получает задачу → декомпозирует → реализует → тестирует  │
│  → доставляет через MR → рефлексирует                     │
└───────────────────────┬───────────────────────────────────┘
                        ▼
┌─ Коммуникация ────────────────────────────────────────────┐
│  Telegram: отчёты, эскалации, дайджесты                   │
│  AgentAPI: вопросы к другим агентам, делегирование        │
└───────────────────────┬───────────────────────────────────┘
                        ▼
┌─ Idle ────────────────────────────────────────────────────┐
│  patrol: исследует лучшие практики, предлагает улучшения  │
└───────────────────────┬───────────────────────────────────┘
                        ▼
┌─ Перезапуск ──────────────────────────────────────────────┐
│  Пишет resume prompt → oro project upload → restart       │
│  → новая сессия читает resume.md → продолжает            │
└───────────────────────────────────────────────────────────┘

Шаблоны Coder workspaces

Шаблон	Тип	Назначение
`claude-agent`	autonomous	Создание/поддержка Coder templates
`skill-architect`	autonomous	Разработка Claude Code skills
`infra-engineer`	autonomous	Infrastructure as Code
`claude-base`	interactive	Общая разработка
`nuxt-fullstack`	interactive	Fullstack Nuxt разработка

Автономные шаблоны включают: Claude Code, code-server (VS Code), JetBrains Gateway, AgentAPI на порту 3284. Startup-скрипт устанавливает oro-cli, выполняет oro prepare, запускает oro bridge + oro loop.

Портируемость

Инфраструктура спроектирована для любого OpenStack-провайдера:

# Форк → .env → make init = полная инфраструктура на другом провайдере
git clone oro-ad/infra
cp .env.example .env  # Заполнить credentials провайдера
make init             # Terraform поднимает всё

Никаких provider-specific значений в коде — всё через переменные окружения.

Связанные документы

oro CLI — детали команд и жизненного цикла
oro-skills — навыки и автоматизация
ADR-009: GitLab CE — инфраструктура CI/CD

Руководство для агентов

Архитектура облачной разработки Oro — экосистема, инструменты, процессы

oro CLI

Управление сессиями агентов — восстановление, синхронизация, агентный цикл