Imported from FHRha/protocol-bunker (
AGENTS.md). Install upstream withnpx skills add FHRha/protocol-bunker. Copyright stays with the author.
# AGENTS.md
О проекте
Protocol: Bunker — это монорепозиторий браузерной адаптации игры «Бункер».
Проект включает:
- клиентскую часть;
- серверную часть;
- общие типы и контракты;
- сценарии и игровой контент;
- стримерские и зрительские режимы;
- сборку релизов под разные платформы;
- документацию для игроков, хостов, стримеров и разработчиков.
Игровой сценарий для обычных участников происходит в браузере. Хост поднимает игру локально, на своём устройстве или на сервере, а остальные подключаются по ссылке.
Зачем нужен этот файл
Этот файл — обзорная карта репозитория.
Он нужен, чтобы быстро понять:
- как устроен проект;
- за что отвечают основные директории;
- куда вносить изменения;
- какие документы считаются каноническими;
- где проходит граница между кодом, контентом, локализацией, стримингом и документацией.
Этот файл не заменяет профильную документацию из docs/. Его задача — быстро дать общую картину проекта.
Карта папок
Ниже — обзорная карта верхнего уровня репозитория.
protocol-bunker/
├─ client/ # браузерный клиент, UI, лобби, комната, карточки, overlay-related части
├─ server/ # сервер, комнаты, websocket-логика, состояние матча
├─ shared/ # общие типы, контракты, payload'ы, доменные сущности
├─ scenarios/ # сценарии, карты, игровые данные, special conditions
├─ tests/ # интеграционные и другие автоматические проверки
├─ scripts/ # сборка, упаковка, release/helper-скрипты
├─ docs/ # документация по ролям и сценариям
│ ├─ user/ # материалы для игроков
│ ├─ host/ # self-host, deployment, Linux/nginx
│ ├─ streaming/ # OBS, overlay, streamer flow
│ ├─ dev/ # архитектура, setup, testing, content system, releases
│ └─ internal/ # QA checklist, заметки, миграции, служебные материалы
├─ locales/ # UI-локализация, переводы, интерфейсные тексты
├─ package.json # корневые скрипты и workspace-конфигурация
├─ install.sh # Linux-установщик и сценарий обновления
├─ README.md # главный вход в репозиторий
├─ MANUAL.md # общий пользовательский мануал
└─ AGENTS.md # обзорная карта проекта и репозитория
## Общая структура репозитория
Ниже перечислены основные верхнеуровневые части проекта и их назначение.
### `client/`
Браузерный интерфейс игры.
Здесь находится всё, что связано с отображением:
- входа;
- лобби;
- игровой комнаты;
- игроков;
- карточек;
- голосования;
- состояний игры;
- мобильного и адаптивного поведения;
- UI для стримерских и зрительских сценариев.
Если меняется визуальная часть, пользовательский интерфейс или отображение состояния матча, основная точка входа обычно находится здесь.
### `server/`
Серверная часть проекта.
Здесь находится логика:
- создания и жизненного цикла комнат;
- подключений;
- websocket-взаимодействия;
- синхронизации состояния;
- хода партии;
- обработки игровых действий;
- ролей хоста, игроков, spectator / control и служебных соединений.
Если меняется серверная логика, сетевое поведение или поведение комнаты, основная точка входа обычно находится здесь.
### `shared/`
Общие типы, контракты и структуры данных.
Это слой, который связывает клиент и сервер между собой.
Здесь обычно находятся:
- типы сообщений;
- payload’ы событий;
- общие доменные сущности;
- перечисления;
- контракты состояния;
- общие утилиты без привязки к конкретной стороне приложения.
Если меняется формат данных между клиентом и сервером, почти всегда затрагивается `shared/`.
### `scenarios/`
Сценарии и игровой контент.
Здесь находятся:
- сценарии;
- наборы карт;
- игровые данные;
- special conditions;
- контентные сущности и связанная с ними логика.
Это слой, который отвечает за содержимое партии и сценарные правила.
Если меняются карты, сценарные данные, специальные условия или контентная модель — основная точка входа обычно находится здесь.
### `tests/`
Автоматические проверки проекта.
Здесь хранятся тесты, связанные с:
- критичными игровыми сценариями;
- websocket-flow;
- комнатами;
- подключениями;
- host transfer;
- установкой и обновлением, если это входит в текущий набор тестов.
Если нужно понять, что уже проверяется автоматически, или добавить новую важную проверку, начинать стоит здесь.
### `scripts/`
Служебные скрипты.
Здесь находятся скрипты для:
- сборки;
- упаковки;
- подготовки релизов;
- platform-specific сценариев;
- вспомогательных технических операций.
Если меняется packaging, release-flow или build-helper логика, точка входа обычно здесь.
### `docs/`
Документация проекта.
Она разделена по аудиториям:
- `docs/user/` — документы для игроков;
- `docs/host/` — документы для хостинга и развёртывания;
- `docs/streaming/` — документы для стриминга, OBS и оверлеев;
- `docs/dev/` — документы для разработки;
- `docs/internal/` — внутренние checklist’ы, заметки, миграции и служебные материалы.
### `locales/`
Локализация интерфейса и связанные с ней данные.
Здесь находятся UI-строки и связанные локализационные материалы.
Важно различать:
- локализацию интерфейса, которая нужна приложению;
- человекочитаемую документацию в `docs/`, которая нужна людям.
Если меняются тексты интерфейса, переводы и UI-ключи, начинать нужно здесь и в соответствующих клиентских местах.
### Прочие верхнеуровневые файлы
#### `README.md`
Главный вход в репозиторий. Это короткий роутер по основным сценариям:
- играть;
- хостить;
- стримить;
- разрабатывать.
#### `MANUAL.md`
Общий пользовательский мануал. Более длинный и человекочитаемый документ, чем `README.md`.
#### `AGENTS.md`
Этот файл. Обзорная карта проекта и структуры репозитория.
#### `package.json`
Корневые скрипты проекта, включая:
- `dev`
- `build`
- `typecheck`
- `test:integration`
- `pack:*`
- `locale:*`
#### `install.sh`
Linux-установщик и сценарий быстрой установки / обновления для готового self-host / server deployment.
## Как части проекта связаны между собой
В упрощённом виде структура проекта работает так:
- `server/` поднимает игру, управляет комнатой и держит состояние матча;
- `client/` подключается к серверу и отображает интерфейс игрокам, хосту, зрителям и стримеру;
- `shared/` задаёт общие контракты между клиентом и сервером;
- `scenarios/` поставляет игровые данные и сценарную логику;
- `tests/` проверяет, что критичные части системы корректно работают вместе;
- `scripts/` собирает и упаковывает релизные артефакты;
- `docs/` объясняет всё это разным аудиториям;
- `locales/` обеспечивает локализацию интерфейса и связанных UI-текстов.
## Куда вносить изменения
Ниже — простой ориентир по типам задач.
### Если меняется интерфейс
Смотри:
- `client/`
- `locales/`, если затронуты тексты интерфейса
### Если меняется серверная логика
Смотри:
- `server/`
### Если меняются события, payload’ы или общие типы
Смотри:
- `shared/`
- затем соответствующие места в `client/` и `server/`
### Если меняются карты, сценарии, special conditions или игровые данные
Смотри:
- `scenarios/`
### Если меняется стримерский режим, overlay или viewer / control flow
Смотри:
- `client/`
- `server/`
- `docs/streaming/`, если меняется пользовательская логика или инструкция
### Если меняется локализация
Смотри:
- `locales/`
- `client/`
- при необходимости `docs/user/`, если меняется человекочитаемая версия правил или объяснений
### Если меняется сборка, упаковка или release-flow
Смотри:
- `scripts/`
- `package.json`
- `docs/dev/release-process.md`
### Если меняется установка или Linux deployment
Смотри:
- `install.sh`
- `docs/host/self-hosting.md`
- `docs/host/linux-nginx.md`
- `docs/host/deployment.md`
### Если меняется документация
Смотри:
- `README.md`
- `MANUAL.md`
- соответствующий раздел в `docs/`
## Канонические документы
Ниже перечислены основные документы, которые считаются актуальной основной документацией проекта.
### Корневые документы
- `README.md`
- `MANUAL.md`
- `AGENTS.md`
### Документы для разработки
- `docs/dev/setup.md`
- `docs/dev/architecture.md`
- `docs/dev/testing.md`
- `docs/dev/content-system.md`
- `docs/dev/release-process.md`
### Документы для стриминга
- `docs/streaming/streamer-quick-start.md`
- `docs/streaming/overlay-guide.md`
- `docs/streaming/overlay-presets.md`
### Документы для игроков
- `docs/user/getting-started.md`
- `docs/user/game-rules.md`
- `docs/user/faq.md`
### Документы для хостов
- `docs/host/self-hosting.md`
- `docs/host/linux-nginx.md`
- `docs/host/deployment.md`
### Внутренние документы
- `docs/internal/qa-checklist.md`
## Документы переходного периода и legacy-материалы
В репозитории могут оставаться старые документы, временные заметки, технические миграции и файлы переходного периода.
К ним стоит относиться так:
- если документ не входит в список канонических выше, он не должен считаться основной точкой правды без отдельной проверки;
- временные и одноразовые материалы должны постепенно переезжать в `docs/internal/notes/` и `docs/internal/migrations/`;
- устаревшие документы не должны дублировать новую структуру документации.
Если старый документ противоречит новому разделу `docs/`, ориентироваться нужно на актуальные канонические документы.
## Документация и уровень детализации
Важно различать уровни документации:
### `README.md`
Короткий вход в проект.
### `MANUAL.md`
Общий пользовательский мануал и единая понятная инструкция.
### `docs/*`
Профильные документы по ролям и сценариям.
### `AGENTS.md`
Обзорная карта репозитория и структуры проекта.
## Практический принцип работы с репозиторием
Перед изменением чего-либо полезно сначала определить тип задачи:
- визуальная правка;
- серверная правка;
- изменение контракта;
- изменение контента;
- изменение локализации;
- изменение стримерского сценария;
- изменение установки или deployment;
- изменение документации.
После этого уже выбирать нужную часть проекта, а не искать вслепую по всему репозиторию.