AGENTS.md — 40-operations

Назначение уровня

Операционная документация проекта: deployment, observability, rate limits и runbooks по текущему контуру.

Содержание

40-operations/
├── AGENTS.md                          # ← вы здесь
├── deployment.md                      # compose-стек, env-конвенции, ingress и production-like публикация
├── production-environment.md          # production host, ingress, runtime-state, systemd, runner topology
├── observability.md                   # OTel, метрики, логи, трейсы
├── rate-limits.md                     # сводный документ по rate budget'ам поставщиков
└── runbooks/
    ├── AGENTS.md
    ├── _TEMPLATE.md
    ├── etm-session-failure.md
    ├── kafka-consumer-lag.md
    ├── event-store-projection-lag.md
    ├── rate-limit-exhausted.md
    └── visibility-policy-cache-poisoning.md

Ключевые концепции уровня

• Compose stack — единый docker compose контур проекта.
• Compose network — внутренняя сеть среды для service-to-service коммуникации.
• Centralized ports — host ports описаны в корневом .env.
• Deploy env — домены, DSN и infra credentials живут в deploy/.env.

Когда смотреть сюда

• Диагностируете инцидент.
• Настраиваете мониторинг или алерты.
• Планируете локальный или production-like запуск.
• Планируете деплой.
• Трогаете production ingress, host nginx, runner’ы или blue/green state.

Когда НЕ смотреть сюда

• Нужны бизнес-правила → ../10-business/.
• Нужны архитектурные решения по схемам и паттернам → ../20-architecture/.
• Нужны сервисные контракты → ../30-services/.

Связано

• deployment.md
• observability.md
• runbooks/AGENTS.md

Соглашения

• Deployment assets живут вне docs/, в /deploy/.
• Все локальные команды запуска идут через Makefile.
• Межсервисные адреса внутри среды используют compose DNS, а не host ports.
• Не создаём альтернативные deployment-файлы под каждую среду без необходимости; используем base compose + override.
• Все межсервисные адреса внутри среды используют compose DNS, а не host ports.
• Перед изменениями production-хоста сначала открывайте production-environment.md; это canonical snapshot текущего окружения.