---
doc_id: BRF-CK8S-PLATFORM-0001
type: brief
title: kodex — краткое описание платформы
status: active
owner_role: PM
created_at: 2026-04-26
updated_at: 2026-04-26
related_issues: [599, 600, 601, 602]
related_prs: []
related_docsets:
  - docs/platform/product/product_model.md
  - docs/platform/product/requirements.md
approvals:
  required: ["Owner"]
  status: approved
  request_id: "owner-2026-04-26-platform-product-frame"
  approved_by: "ai-da-stas"
  approved_at: 2026-04-26
---

# Brief: kodex

## TL;DR

- **Проблема:** разработка с агентами быстро теряет управляемость, если задачи, проверки, релизы, доступы и окружения живут в разных несвязанных контурах.
- **Для кого:** владелец продукта, инженерная команда, операторы платформы, внешние исполнители и клиентские организации.
- **Решение:** платформа управления агентной разработкой поверх нативных сущностей провайдера, Kubernetes-окружений, процессов `flow`, ролей, пакетной модели и управляемой приёмки.
- **Почему сейчас:** проект переписывается с нуля, поэтому нужно сразу зафиксировать enterprise-рамки и не зацементировать узкую модель одного репозитория, одного сервера и ручного запуска.
- **Успех:** владелец управляет проектами через командный центр, агенты создают проверяемые `Issue` и `PR/MR`, платформа видит `run`, `job`, риски, релизы и блокировки, а первая кодовая реализация домена доступа не требует пересмотра продуктовой модели.
- **Что не делаем:** не создаём параллельный внутренний трекер задач, не заменяем GitHub/GitLab review, не строим новую реализацию поверх старого кода из `deprecated/**`.

## Контекст

`kodex` развивается как платформа, через которую владелец и команда могут вести полный цикл работ: от идеи и постановки до разработки, проверки, релиза, postdeploy-наблюдения и операционных задач.

Прошлая модель слишком сильно смешивала внутренний control-plane, labels, старую документацию и скрытую runtime-логику. Новая версия должна быть понятна человеку и агенту без чтения старого кода: рабочие артефакты остаются у провайдера, а платформа владеет оркестрацией, runtime, политиками, аудитом и операторскими проекциями.

## Цель

Бизнес-цель:
- дать владельцу управляемый способ разрабатывать свои и клиентские проекты через платформу с агентами;
- заложить SaaS- и marketplace-контур без переписывания доменной модели после MVP;
- уменьшить ручную работу владельца: он утверждает документы, решения и high-risk переходы, а не обязан читать каждый diff.

Техническая цель:
- начать новую реализацию только после того, как сквозная продуктовая, архитектурная и доменная документация перенесена из `refactoring/**` в новую структуру `docs/**`;
- сохранить provider-first модель для `Issue`, `PR/MR`, комментариев, веток, тегов и review;
- строить платформу вокруг Kubernetes, agent-manager, `flow`, ролей, `run`, `job`, `slot`, пакетной платформы и доменных событий.

## Пользователи и сценарии

| Роль | Главная цель | Боль |
|---|---|---|
| Owner | запускать инициативы, утверждать документы, решения и релизы | нельзя превращаться в ручного reviewer всего кода |
| Оператор платформы | видеть сбои, блокировки, `job`, слоты и лимиты | скрытые сбои cleanup, deploy и внешних провайдеров приводят к деградации |
| Ролевой агент | выполнять этап или проверку в разрешённом контуре | непонятный workspace, недостающие права и неясный контракт артефактов ломают процесс |
| Внешний исполнитель | работать в рамках назначенных проектов и ролей | нельзя давать лишний доступ к организации и инфраструктуре |
| Клиентская организация | участвовать в согласованиях на своих этапах, получать результат, решения и отчётность по проекту | нужна изоляция, прозрачность затрат и понятная зона ответственности |

## Предлагаемое решение

- Командный центр с agent-manager как основной вход: текст, голос, быстрые действия и очередь решений.
- Provider-first рабочая модель: `Issue` является задачей, инициатива является `Issue` типа `initiative`, `PR/MR` остаётся артефактом изменения у провайдера.
- Процессы `flow` состоят из этапов, привязок ролей к этапам, правил перехода, Human gate и профилей приёмки.
- Роли, `flow` и шаблоны промптов канонически хранятся в БД платформы с версиями, аудитом и установочными фикстурами в репозитории.
- Runtime строится на Kubernetes: `slot` для работы, `run` для агентного запуска, `job` для технических build/deploy/cleanup операций.
- Пакетная платформа поддерживает плагины, пакеты руководящей документации, магазин пакетов и пользовательские источники.
- Организации, группы, внешние аккаунты, серверы, кластеры, биллинг, релизная политика и automation rules закладываются в MVP как обязательные расширяемые контуры.

## Границы

### Входит

- Сквозная продуктовая модель платформы.
- Обязательные ограничения и запреты для первой версии.
- Высокоуровневые функциональные и нефункциональные требования.
- Глоссарий терминов, которые должны одинаково использоваться в `docs/**`, PR и будущей реализации.

### Не входит

- Детальная архитектура сервисов и данных.
- Подробный пакет домена доступа.
- Кодовая реализация домена доступа.
- Перенос старой документации из `deprecated/**` как активной каноники.

## Метрики успеха

- Документы `docs/platform/product/**` дают достаточную рамку для следующих архитектурных и доменных документов без обращения к старым `docs/product`.
- В требованиях нет отдельной внутренней сущности инициативы.
- В требованиях явно присутствуют provider-first модель, `flow/stage/role/prompt`, организации, группы, внешние аккаунты, пакетная платформа, runtime/fleet, биллинг, релизная политика и автоматизация.
- Любой следующий PR может ссылаться на документы из `docs/platform/product/**` как на согласованную продуктовую канонику.

## Риски и допущения

| Риск | Как снижаем |
|---|---|
| Документы станут слишком общими и не помогут первому доменному коду | Домен доступа отдельно детализируется до начала реализации. |
| Enterprise-рамки перегрузят MVP | В каждом контуре различаем минимальный объём первой версии и целевую enterprise-модель. |
| Появится дублирование с `refactoring/**` | `docs/**` постепенно забирает канонику, а `refactoring/**` остаётся программным источником до явного переноса разделов. |

## Решение от Owner

- [x] Принять brief как базу сквозного продуктового каркаса.
- [x] Считать merge PR фактом согласования документа.

## Ссылки

- Главный мандат: `refactoring/task.md`
- Индекс продукта: `docs/platform/product/README.md`
