---
doc_id: PRD-CK8S-PLATFORM-0001
type: prd
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/brief.md
  - docs/platform/product/constraints.md
  - docs/platform/product/product_model.md
  - docs/platform/product/glossary.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
---

# PRD: kodex

## TL;DR

- **Что строим:** платформу управления агентной разработкой, поставкой и эксплуатацией поверх GitHub/GitLab и Kubernetes.
- **Для кого:** Owner, операторы платформы, инженерные команды, внешние исполнители, клиентские организации и будущие SaaS-пользователи.
- **Почему:** агентная работа без единого контура задач, окружений, ролей, рисков и приёмки становится непрозрачной и опасной.
- **MVP:** provider-first работа с `Issue/PR/MR`, организации и доступы, проекты и репозитории, agent-manager, flow/roles/prompts, runtime slots, `run`, `job`, пакетная платформа, базовый биллинг, релизная политика и уведомления.
- **Критерии успеха:** первая кодовая реализация домена доступа может стартовать без пересмотра модели, а последующие домены расширяют уже согласованные сущности.

## Проблема и цель

Проблема:
- владелец не должен вручную контролировать каждый технический шаг, но должен видеть решения, риски, блокировки и результат;
- агенты должны работать с реальными `Issue`, `PR/MR` и репозиториями, а не с внутренними карточками платформы;
- build, deploy, cleanup и runtime-сбои должны быть видимы как часть поставки, а не теряться в Kubernetes;
- будущие организации, пакеты, биллинг, серверы, кластеры и SaaS-модель должны быть заложены до кода.

Цель:
- зафиксировать сквозные требования платформы на уровне продукта;
- дать следующим архитектурным, доменным и кодовым срезам стабильную рамку;
- исключить возврат к старой control-plane-центричной и label-only модели.

## Пользователи

| Роль | Главный сценарий |
|---|---|
| Owner | Запустить инициативу или flow, принять документы, high-risk решение или релиз. |
| Оператор платформы | Найти сбой `run`, `job`, slot, внешнего аккаунта, лимита или housekeeping. |
| Разработчик/исполнитель | Получить задачу, workspace и права для работы в одном или нескольких репозиториях. |
| Роль проверки | Проверить артефакт, оставить замечания, approval или structured feedback. |
| Администратор | Настроить организации, группы, внешние аккаунты, пакеты, серверы, кластеры и политики. |
| Клиентская организация | Участвовать в обсуждениях и согласованиях на разрешённых этапах, получать результат, прозрачность статусов, затрат и решений без доступа к лишней инфраструктуре. |

## Функциональные требования

| ID | Требование | Приоритет |
|---|---|---|
| FR-1 | Платформа должна работать с `Issue`, `PR/MR`, комментариями, mentions, relationships, ветками и тегами как с нативными сущностями провайдера. | Must |
| FR-2 | Инициатива должна быть `Issue` типа `initiative`, а не отдельной внутренней сущностью. | Must |
| FR-2.1 | Платформа должна хранить зеркальные проекции и собственные метаданные для `Issue`, `PR/MR`, комментариев и связей, не превращая их во внутренний трекер задач. | Must |
| FR-2.2 | Если `Issue` или `PR/MR` создан напрямую у провайдера, платформа должна связать его с проектом, проверить обязательные поля и запустить дозаполнение через agent-manager или запросить решение человека по policy. | Must |
| FR-2.3 | Платформа должна синхронизировать проекции через webhook inbox, incremental reconciliation, приоритеты горячих сущностей и контроль рассинхронизации. | Must |
| FR-2.4 | Платформа должна учитывать расход лимитов провайдера: детерминированно для операций через provider-hub и приближёнными снимками для прямой работы slot-агентов через `gh`. | Must |
| FR-3 | Платформа должна поддерживать рабочие типы задач для этапов flow: `intake`, `vision`, `prd`, `arch`, `design`, `plan`, `dev`, `qa`, `release`, `postdeploy`, `ops` и специальные типы. | Must |
| FR-4 | Agent-manager должен принимать запросы из UI, голосового ввода, внешних каналов, `Issue`, `PR/MR` и mentions. | Must |
| FR-5 | Agent-manager должен выбирать flow, роль, шаблон промпта, runtime-режим и следующий шаг по policy. | Must |
| FR-6 | Ролевой агент должен оформлять provider-native артефакты через `gh` или API провайдера, а платформенные операции выполнять через MCP. | Must |
| FR-7 | Платформа должна поддерживать flow, этапы, профили ролей, привязки ролей к этапам, Human gate, acceptance profile и automation rules. | Must |
| FR-8 | Flow, роли и шаблоны промптов должны храниться в БД с версиями, digest, аудитом, UI-редактированием и установочными фикстурами в репозитории. | Must |
| FR-9 | Acceptance machine должна проверять provider-native поля, открытые разделы, watermark, связи, policy и ожидаемые follow-up артефакты. | Must |
| FR-10 | Платформа должна поддерживать связанный набор `PR/MR` по одной задаче в нескольких репозиториях. | Must |
| FR-11 | Платформа должна поддерживать организации, группы пользователей, membership, наследование прав, explicit deny и аудит решений доступа. | Must |
| FR-12 | Платформа должна поддерживать внешние аккаунты провайдеров, моделей, каналов связи и сервисных операций. | Must |
| FR-13 | Платформа должна поддерживать проекты с несколькими репозиториями и источниками проектной документации, описанными в `services.yaml`. | Must |
| FR-14 | Платформа должна загружать агенту в workspace код, проектную документацию, документацию зависимостей и руководящие пакеты по policy. | Must |
| FR-15 | Платформа должна поддерживать пакетную модель: plugin packages, guidance packages, установленные пакеты, доступные пакеты и пользовательские источники. | Must |
| FR-16 | Пакет магазина доступных пакетов должен подключаться как пакет, а не быть встроенным ядром. | Must |
| FR-17 | Платформа должна поддерживать `run`, `job`, slot, подготовку окружения, build, deploy, cleanup и housekeeping. | Must |
| FR-18 | Платформа должна хранить по `job` статус, контекст, timestamps, причину ошибки, короткий хвост лога и ссылку на первоисточник. | Must |
| FR-19 | Платформа должна поддерживать release policy, release line, release gate, deploy `job`, postdeploy-наблюдение, `hold`, `rollback` и follow-up. | Must |
| FR-20 | Платформа должна поддерживать risk class, роль управления рисками, Human gate и историю изменения риска. | Must |
| FR-21 | Платформа должна поддерживать уведомления о сбоях, блокировках, завершении важных этапов, human gate, лимитах и housekeeping. | Must |
| FR-21.1 | Внешние каналы взаимодействия должны подключаться через пакеты и общий контракт взаимодействия, а не через жёстко зашитый список адаптеров. | Must |
| FR-22 | Платформа должна поддерживать управление серверами и Kubernetes-кластерами: добавление пустого OS-сервера, установку зависимостей, Kubernetes и firewall, проверку здоровья, мониторинг и placement policy. | Must |
| FR-23 | Платформа должна поддерживать cost records, billing account и основу для выставления счетов организациям и проектам. | Should |
| FR-24 | Платформа должна поддерживать запуск flow или создание задач по cron, trigger и внешним сигналам. | Should |
| FR-25 | Пакеты внешних каналов должны уметь запрашивать approvals, доставлять вопросы пользователям и возвращать ответы через единый контракт взаимодействия. | Should |
| FR-26 | Клиентская организация или её представитель должны иметь возможность участвовать в обсуждениях и утверждать результаты на этапах, где это разрешено политикой. | Must |
| FR-27 | Вход в платформу должен идти через SSO/OIDC-контур с базовым самостоятельно управляемым IdP Keycloak; GitHub/GitLab подключаются как внешние поставщики идентичности. | Must |

## Нефункциональные требования

| ID | Категория | Требование |
|---|---|---|
| NFR-1 | Безопасность | Секреты платформы и её зависимостей должны храниться в Vault; проекты могут использовать свои хранилища. |
| NFR-2 | Безопасность | Опасные операции с инфраструктурой, секретами, production и destructive actions должны идти через policy и Human gate. |
| NFR-3 | Аудит | Изменения доступа, flow, ролей, шаблонов, risk class, release decisions и внешних аккаунтов должны быть аудируемыми. |
| NFR-4 | Наблюдаемость | Сбои `run`, `job`, slot, внешних аккаунтов, лимитов, cleanup и release safety-loop должны быть видимы оператору. |
| NFR-5 | Данные | Полные технические логи и бинарные вложения не должны без отдельного решения храниться в PostgreSQL. |
| NFR-6 | Масштабируемость | Документация и модель данных должны поддерживать несколько организаций, проектов, репозиториев, серверов и кластеров. |
| NFR-7 | Расширяемость | Пакеты, внешние каналы, MCP-инструменты и роли должны подключаться без переписывания ядра. |
| NFR-8 | Локализация | UI и документы должны сохранять цельность выбранной локали. |
| NFR-9 | Поддерживаемость | Новые документы создаются по шаблонам, а карты Issue разбиты по доменам и рабочим срезам. |
| NFR-10 | Совместимость провайдеров | GitHub является первой реализацией, но продуктовая модель не должна блокировать GitLab. |
| NFR-11 | Производительность и лимиты | UI, списки, фильтры и приёмка не должны читать провайдера на каждый запрос; для этого используются webhook, reconciliation и локальные зеркальные проекции. |
| NFR-12 | Устойчивость синхронизации | Потеря webhook не должна приводить к вечной рассинхронизации: reconciliation обязан находить изменения без ручного действия пользователя. |
| NFR-13 | Наблюдаемость лимитов | Платформа должна показывать риск исчерпания лимитов провайдера по аккаунту и контуру, даже если часть операций выполнялась агентом через `gh`. |

## Acceptance criteria

| ID | Критерий |
|---|---|
| AC-1 | Если пользователь запускает инициативу, платформа создаёт или использует `Issue` типа `initiative`, а не внутреннюю карточку инициативы. |
| AC-2 | Если агент создаёт `PR/MR`, acceptance machine проверяет ссылку на исходный `Issue`, открытые разделы, watermark и ожидаемый follow-up. |
| AC-3 | Если задача требует изменения нескольких репозиториев, платформа связывает набор `PR/MR` с одной задачей и одним acceptance-контуром. |
| AC-4 | Если `job` падает, оператор видит статус, причину ошибки, короткий хвост лога, ссылку на первоисточник и следующее действие. |
| AC-5 | Если переход требует Human gate, процесс остаётся в ожидании до явного решения человека. |
| AC-6 | Если flow, роль или шаблон меняется через UI, платформа создаёт новую версию в БД с аудитом и policy-проверкой. |
| AC-7 | Если пользователь подключает пакет, платформа проверяет manifest, права, секреты, версию, источник и область применения. |
| AC-8 | Если внешний канал нужен для уведомлений или approval, он подключается через пакет и общий контракт взаимодействия, а не через жёстко зашитую интеграцию. |
| AC-9 | Если пользователь создал задачу напрямую в GitHub/GitLab, платформа создаёт проекцию, проверяет тип и обязательные признаки, а недостающие данные дозаполняет или выносит человеку. |
| AC-10 | Если оператор добавляет пустой сервер, платформа проводит bootstrap, устанавливает Kubernetes, применяет firewall baseline, проверяет здоровье и показывает результат. |
| AC-11 | Если webhook по задаче или `PR/MR` не дошёл, incremental reconciliation находит изменение по cursor или окну перекрытия и обновляет проекцию без участия пользователя. |
| AC-12 | Если лимиты провайдера близки к исчерпанию, платформа сохраняет синхронизацию горячих сущностей, откладывает холодные проверки и показывает признак возможной устарелости там, где данные не перепроверены. |

## Non-goals

- Не реализовывать код домена доступа в рамках этого продуктового документа.
- Не проектировать детальную схему БД и API в этом документе.
- Не восстанавливать старые документы из `deprecated/**`.
- Не создавать внутренний трекер задач, который конкурирует с GitHub/GitLab.
- Не выбирать окончательный стек логирования, метрик и платежных провайдеров на уровне этого документа.

## UX/UI заметки

- Главная точка входа — командный центр с agent-manager, чатом, голосом и быстрыми действиями.
- Рабочие пространства строятся вокруг `Issue`, `PR/MR`, `run`, `job` и slot.
- Консоль должна показывать центр внимания: approvals, ошибки, блокировки, лимиты, housekeeping и важные завершения.
- Review diff остаётся у провайдера; консоль показывает сводку, состояние, gates и переходы.

## Зависимости

| Зависимость | Зачем нужна |
|---|---|
| GitHub/GitLab | Рабочие артефакты, review, ветки, теги и repository storage. |
| Kubernetes | Runtime, slots, plugins, jobs и workloads. |
| Vault | Секреты платформы и её зависимостей. |
| PostgreSQL | Состояние owner-сервисов, версии, аудит, зеркальные проекции, платформенные метаданные `run` и `job`. |
| Object storage | Медиа-вложения и потенциально крупные артефакты, которые не должны жить в PostgreSQL. |
| OpenAI/Codex providers | Модели для agent-manager и ролевых агентов. |

## Риски

| Риск | Митигирование |
|---|---|
| Слишком широкая MVP-модель | Делить реализацию по доменам и фиксировать минимум первой версии. |
| Скрытое возвращение старой реализации | Корневые правила запрещают использовать `deprecated/**` как основу новой реализации. |
| Дублирование провайдера | Provider-first ограничения и acceptance-контракт запрещают создавать внутренние заменители рабочих артефактов. |
| Рост документации и merge-конфликты | Документы и карты Issue делятся по платформе, доменам и рабочим срезам. |

## Следующие продуктовые уточнения

| Направление | Результат |
|---|---|
| Архитектура | Сквозной архитектурный каркас, границы сервисов и синхронизация событий. |
| Доступ | Пакет домена доступа: организации, группы, пользователи, SSO, внешние аккаунты и политики. |
| Delivery | Трассируемость, приёмка, связи документов с работами и правила принятия результата. |
| Ops | Управление серверами и кластерами, deploy gate, наблюдаемость и эксплуатационные решения. |

## Апрув

- request_id: `owner-2026-04-26-platform-product-frame`
- Решение: approved
- Комментарий: требования фиксируют целевую продуктовую рамку платформы для последующей декомпозиции.
