# Инструкции для ИИ-агентов

## Базовые правила

- Ответы пользователю и оформление PR писать на русском языке.
- Тексты commit message писать на английском языке.
- Перед началом работы читать этот файл и проверять текущую ветку.
- Прямой push в `main` и работа в `main` запрещены.
- Если текущая ветка `main`, сначала обновить её от `origin/main`, затем создать рабочую ветку.
- Если текущая ветка не `main`, продолжать работу в ней, если пользователь не попросил новую ветку.
- При противоречии между запросом пользователя и правилами остановиться и дать варианты решения.
- Для актуальной информации по библиотекам использовать Context7 MCP.

## Текущая каноника

- Главный документ программы: `refactoring/task.md`.
- Индекс программы: `refactoring/README.md`.
- В рамках активной программы рефакторинга источник правды по продукту, архитектуре, поставке и эксплуатации находится в `refactoring/**`, пока соответствующий раздел явно не перенесён в `docs/**`.
- Новые документы в `docs/**` создаются с нуля по `docs/templates/**` в принятой структуре:
  `docs/platform/**`, `docs/domains/**`, `docs/catalogs/**`, `docs/delivery/**`, `docs/research/**`.
- В активной документации `README.md` используется как карта раздела, а `AGENTS.md` — как локальная инструкция для агентов по правилам редактирования этого раздела.
- Сквозная каноника платформы живёт в `docs/platform/**`, доменные пакеты — в `docs/domains/**`, каталоги пакетов и расширений — в `docs/catalogs/**`.
- Карта связей `Issue/PR ↔ документы` не ведётся одним большим файлом: использовать `docs/delivery/issue-map/index.md` и раздельные файлы внутри `docs/delivery/issue-map/**`.
- Внешние источники документации и пакеты подключаются как source submodule и входят в рабочий контур проекта: руководящие документы — в `docs/external/**`, шаблоны — в `docs/templates/**`, пакеты — в `packages/**`.
- Штатный рабочий контур предполагает checkout всех submodule из `.gitmodules`; если источник недоступен, агент фиксирует это как проблему доступа, а не подменяет источник локальной копией.
- Старые документы, код и инфраструктурные каталоги перенесены в `deprecated/**`.
- Всё внутри `deprecated/**` было в корне репозитория до reset-итерации, устарело и оставлено только как временный справочный материал для владельца. Агент не должен использовать `deprecated/**` как основу новой реализации, за исключением случаев когда пользователь дает ссылку на материалы там как на референсы.
- `deprecated/**` оформлен как отдельный архивный Go module, чтобы корневые `go mod tidy`, `go test ./...` и `go list ./...` не обходили устаревший код. Не запускать `go mod tidy` внутри `deprecated/**` и не чинить его зависимости без отдельного запроса пользователя.
- Новая реализация пишется с нуля в новых сервисах и новых каталогах целевой архитектуры. Устаревший код из `deprecated/**` не дорабатывается.

## Live-safe evolution

- Платформа уже развёрнута в live-кластере, поэтому активные сервисы, миграции, секреты, конфигурация и deploy path больше не считаются одноразовыми. Быстрые внутренние изменения допустимы, но только с безопасной последовательностью обновления.
- Уже применённые миграции не редактировать и не переупорядочивать. Изменения схемы делать новой forward-only additive migration. Destructive/drop/rename выполнять только через отдельный путь `expand -> migrate -> contract`; live drift чинить новой миграцией, а не ручным SQL.
- Для `proto`, OpenAPI и AsyncAPI breaking change допустим только когда все потребители обновляются в согласованном срезе и нет live rolling gap. Иначе сначала добавить новое поле/операцию, затем перевести потребителей, затем удалить старое отдельным срезом.
- Новые обязательные env/secrets/config должны иметь staged rollout path или безопасную диагностику. Нельзя ломать старт уже развёрнутого сервиса без явного runbook шага и синхронного обновления deploy inventory.
- Изменения bootstrap/deploy tooling должны сохранять возможность последовательного обновления существующего live-кластера: порядок migrations, сервисов, edge и frontend фиксируется явно, а обратимые операционные шаги описываются в runbook.

## Что читать перед работой

- Для любой работы по программе рефакторинга читать:
  - `refactoring/task.md`;
  - `refactoring/README.md`;
  - релевантные документы `refactoring/*.md`;
  - `docs/templates/index.md`, если создаются новые документы.
- Для любых изменений активной документации в `docs/**` читать:
  - `docs/AGENTS.md`;
  - ближайший локальный `AGENTS.md` в нужной зоне документации, например `docs/domains/AGENTS.md`, `docs/platform/AGENTS.md`, `docs/catalogs/AGENTS.md` или `docs/delivery/AGENTS.md`.
- Если добавляется новый домен, обязательно следовать `docs/domains/AGENTS.md`.
- Для изменения инженерных стандартов или кода читать:
  - `docs/design-guidelines/AGENTS.md`;
  - релевантные файлы из `docs/design-guidelines/common/**`;
  - `docs/design-guidelines/go/**`, если затронут Go;
  - `docs/design-guidelines/vue/**`, если затронут frontend.
- Для изменения шаблонов документации читать `docs/templates/AGENTS.md`.
- Для работы с документационными submodule читать `docs/external/AGENTS.md`.
- Для работы с пакетными submodule читать `packages/AGENTS.md`.
- При локальной работе читать `.local/agents-temp-dev-rules.md`, если нужен GitHub, локальный запуск или доступ к окружению. Править этот файл нельзя без отдельного запроса пользователя.

## GitHub и PR

- Для GitHub PR-операций в первую очередь использовать `KODEX_GIT_BOT_TOKEN` из `bootstrap/host/config.env`.
- `KODEX_GITHUB_PAT` использовать только как fallback для чтения или технического обхода, если бот-токен не подходит.
- Если агент знает своё имя, номер, домен или роль, он должен добавлять это в заголовок PR перед кратким названием задачи, чтобы owner быстрее понимал, чей это PR. Формат: `agent-<номер>/<домен или роль>: <код среза> — <краткое описание>`, например `agent-3/package-platform: PKG-5.3b — сверка секретов установки`.
- После завершения работы создать или обновить PR и явно сообщить пользователю, как принять результат.
- При устранении замечаний PR получить все незакрытые комментарии, отработать каждый и ответить на каждый от имени бота.
- В открытом PR каждая итерация исправлений должна быть одним commit.

## Документация

- Документы писать по-русски там, где смысл не теряет точность.
- Английский оставлять для имён файлов, каталогов, API, протоколов, env, model id и code identifiers.
- В теле продуктовой и руководящей документации не ссылаться на номера волн, Issue, PR, review threads, временные ветки и другие динамические сущности рабочего процесса.
- Такие ссылки допустимы во frontmatter-полях связей, в `docs/delivery/**`, картах `Issue/PR ↔ документы`, самих Issue/PR, QA/ops/SRE отчётах и delivery-планах.
- Документ в PR должен отражать целевое состояние. Merge PR считается фактом согласования.
- Если merge PR должен зафиксировать согласование документа, до merge документ приводится к согласованному состоянию: не оставлять в результате текущего PR статусы вида `в PR`, `на ревью` или временные формулировки рабочего процесса.
- Если документ намеренно фиксирует вариантную проработку или открытый выбор владельца, это должно быть явно оформлено как `approvals.status: pending` или отдельный раздел с ожидаемым решением, без привязки к текущему PR.
- Старые ссылки внутри `deprecated/**` не чинить, если пользователь не просит отдельно.
- Для новых документов использовать шаблоны из `docs/templates/**` и сразу добавлять документы в соответствующий индекс.
- Для правил размещения документов пользоваться локальными `AGENTS.md` внутри `docs/**`; если подходящего файла нет, сначала обновить правила зоны, а затем добавлять новые документы.
- Публичные репозитории руководящих гайдов подключаются как source submodule в `docs/external/guidelines/**`; если источник импортирован в проект, его правила обязательны.
- Репозиторий `docs/design-guidelines/**` содержит проектный overlay `kodex`; при конфликте overlay имеет приоритет над подключённым внешним baseline.
- Публичный репозиторий шаблонов `github.com/codex-k8s/kodex-doc-templates-ru` подключается как source submodule `docs/templates`.
- Если проекту нужен иной набор шаблонов, создаётся отдельный репозиторий шаблонов и привязывается к проекту через `services.yaml`.
- Source submodule объявляются в `.gitmodules`, а `services.yaml` фиксирует политику их checkout и правила рабочего пространства. Пакеты размещаются в `packages/**`; доступность и права проверяет платформа.
- Для пользовательских форков и downstream-инсталляций отдельный workflow должен удалять магазин, сайт и необязательные пакеты, которые не должны попадать в этот репозиторий.
- Если меняется внешний репозиторий, сначала вносить изменения в его собственной ветке и PR, и только после merge обновлять gitlink в `kodex`.

## Проверки перед push

- Для документационных изменений выполнить self-check по `docs/design-guidelines/common/check_list.md` в применимой части.
- Для Go-изменений дополнительно выполнить `docs/design-guidelines/go/check_list.md`.
- Для frontend-изменений дополнительно выполнить `docs/design-guidelines/vue/check_list.md`.
- Если проверки не запускались, явно написать причину в финальном сообщении.

## Неподвижные ограничения продукта

- Поддерживается только Kubernetes.
- Регистрация пользователей отключена: вход через платформенный SSO/OIDC-контур с матчингом по email, разрешённым администратором; базовый самостоятельно управляемый IdP — Keycloak, GitHub/GitLab могут быть внешними поставщиками идентичности.
- Рабочая модель строится вокруг нативных сущностей провайдера (`provider-native`): `Issue`, `PR/MR`, комментарии, ветки, теги и связи.
- Инициатива является `Issue` со своим типом, а не отдельной проектной сущностью.
- Платформа должна иметь задел под организации, группы пользователей, внешние аккаунты, плагины, пакеты руководящей документации, серверы/кластеры, биллинг, релизную политику и автоматизацию по расписанию/триггерам.
