diff --git a/.cursor/rules/agent-pitfalls.mdc b/.cursor/rules/agent-pitfalls.mdc new file mode 100644 index 0000000..53b0a99 --- /dev/null +++ b/.cursor/rules/agent-pitfalls.mdc @@ -0,0 +1,102 @@ +--- +description: Типичные ошибки агентов EventHub — shell, git, docker, scope, токены (корень + субагенты) +alwaysApply: true +--- + +# EventHub: типичные ошибки агентов (избегать) + +Канон. Субагентам: включать в промпт «следуй `agent-pitfalls.mdc` + `shell-wsl-not-powershell.mdc`». + +## 1. Shell / PowerShell + +| Симптом | Причина | Как правильно | +|---------|---------|---------------| +| `unexpected EOF`, `ParserError`, пустой curl | PS ломает `"`, `$`, heredoc, `&&` | Файл `.sh` → `wsl -e bash /mnt/c/.../script.sh` | +| `bash: syntax error near '('` | `grep -E ^(...)` без кавычек в PS | Только внутри `.sh` | +| `{{.Names}}: command not found` | `docker --format "{{…}}"` в PS | Формат в `.sh` или простой `docker ps` | +| `&&` is not valid | PowerShell не bash | Отдельные команды или `.sh` | + +**Запрещено в PS:** `wsl -e bash -lc "…\"…"`, `curl -d "{\"x\":…}"`, heredoc commit, `npm`/`rebar3`. + +## 2. Git + +| Симптом | Как правильно | +|---------|---------------| +| `Co-authored-by: Cursor <…>` / `<` ParserError | `git commit -F .tmp-msg.txt` из PS **или** `~/.cursor/eventhub/git-commit.sh` в WSL | +| `#` в `-m` обрезает сообщение | `-F` файл; в тексте `Refs EventHub/EventHubBack#N` | +| `editor` / not a terminal | Не `git commit` без `-F` в WSL; из Windows: `git commit -F file` | +| Сотни `M` после reset на `/mnt/c` | `git config core.filemode false` (локально); не «чинить» код | +| Удалились `.cursor/`, `.idea/` | **`git clean -fdx` только с backup** env + certs; IDE-директории **не трогать** | +| Push заблокирован Auto-review | Push в `master` — только по явной просьбе; `request_smart_mode_approval` | + +**`git clean` / reset к origin:** сначала сохранить `docker/.env*`, `.env.development`, `docker/traefik/certs/*`. + +## 3. Docker dev (Swarm локально) + +| Ошибка | Правильно | +|--------|-----------| +| «Балансировка» → 3× eventhub | **dev:** `traefik=1` + **`eventhub=1`** (см. `EventHubDevOps/docs/STANDS.md`) | +| `host-mode port already in use` | У eventhub опубликованы 8080/8445 — **нельзя** scale >1; LB = traefik | +| Собрали admin-ui/front без просьбы | «Только бэк» → eventhub (+ traefik если нужен HTTPS), **без** Front/Admin образов | +| Эмулятор не остановился | `docker service scale eventhub_bot-emulator-users=0` | +| `No such image: eventhub:latest` | Сначала `docker build -t eventhub:latest …` или `docker/build-images.sh` | +| Admin API dev не отвечает на :443 | Traefik без ports → **`http://127.0.0.1:8445`**; stage → SSH + `--resolve …:443:127.0.0.1` | + +## 4. Scope (не додумывать) + +- Делать **ровно** запрос; не раздувать (полный `build-images.sh`, 3 ноды, admin-ui, spec commit). +- Перед scale/deploy — прочитать compose и STANDS.md. +- Секреты: `gitea.ps1` / `.sh` + env; не inline `source secrets` в PS one-liner. + +## 5. Субагенты (Task) + +В промпт субагента добавлять: + +```text +Shell: только WSL + .sh (см. shell-wsl-not-powershell.mdc, agent-pitfalls.mdc). +Один репо. Итог на русском. Не push без явного OK. +``` + +## 6. Экономия токенов / лимитов моделей + +### Контекст чата +- **Один чат — одна задача**; после «готово / CI зелёный» — новый чат на следующий шаг (см. `WORKFLOW.md` §5). +- Workspace: для Back-задачи достаточно **`EventHubBack`** (+ Spec при необходимости); не держать все репо без нужды. +- **`@` точечно** — файл/папка, не `@Codebase` без причины. +- Не просить «проанализируй все transcripts» — они огромные. + +### Дешёвые vs дорогие действия +| Дорого | Дешевле | +|--------|---------| +| Task explore «very thorough» | `grep` + 1–2 файла | +| Полный `build-images.sh` | Только нужный образ | +| Весь лог CI (80k строк) | API job + 20 строк вокруг ошибки | +| Несколько subagents «на всякий» | 1 subagent, узкий промпт | +| Browser deep-walk stage | Smoke-скрипт / один URL | + +### Меньше итераций +- Сразу **`.sh`**, не 5 попыток PS one-liner (каждая = новый turn). +- Git перед commit: **один** `status` + `diff`, не три раза подряд. +- Тесты: `rebar3 eunit --module=…` если трогали один модуль; не полный suite без нужды. +- Docker: не rebuild, если `docker images` уже есть нужный tag. + +### Модели и режимы +- **Ask / Plan** — вопросы и варианты без tool calls. +- **Agent** — только когда нужны команды и правки. +- Bugbot / Security Review — не на каждый мелкий diff. + +### Scope в запросе (шаблон) +```text +Репо: EventHubBack +Issue: #N +Scope: только … +Не: front, docker, push, spec +Done: eunit / lint / … +``` + +### Subagents +- Редко; промпт = issue + файлы + done, **без** всей переписки. +- `one-repo-per-agent` — меньше контекста и ошибок. + +### Повторяемое — в скрипты +Токены verify, smoke creds, stage deploy — **`~/.cursor/eventhub/*.sh`**, не заново через SSH в каждом чате. diff --git a/.cursor/rules/agents-russian.mdc b/.cursor/rules/agents-russian.mdc new file mode 100644 index 0000000..d691a6d --- /dev/null +++ b/.cursor/rules/agents-russian.mdc @@ -0,0 +1,27 @@ +--- +description: Ответы субагентов и итоги работы — на русском +alwaysApply: true +--- + +# EventHub: язык ответов агентов + +## Правило +Все **вызванные / фоновые агенты** (Task subagents) пишут пользователю и parent-агенту **на русском**: +- итоги, вердикты, чеклисты, UX-оценки; +- комментарии в Gitea (как и раньше — только русский); +- краткие status-апдейты в конце задачи. + +## Допустимо на английском +- Идентификаторы кода, API paths, commit subject если в репо уже принят EN-стиль сообщений (можно и RU — главное единообразие в рамках задачи); +- цитаты из логов CI / stack traces без перевода; +- имена файлов, SHA, URL. + +## Родитель-координатор +Тоже отвечает пользователю по-русски. + +## Промпт субагенту (обязательно) +- «Return summary in Russian» +- «Shell: WSL + `.sh` only — `shell-wsl-not-powershell.mdc`, `agent-pitfalls.mdc`» +- «One repo per agent — `one-repo-per-agent.mdc`» +- «Экономия токенов: §6 agent-pitfalls — узкий scope, без лишних subagents/explore» +- Не push / не `git clean -fdx` без явного OK пользователя diff --git a/.cursor/rules/one-repo-per-agent.mdc b/.cursor/rules/one-repo-per-agent.mdc new file mode 100644 index 0000000..28ea348 --- /dev/null +++ b/.cursor/rules/one-repo-per-agent.mdc @@ -0,0 +1,29 @@ +--- +description: Один агент — один репозиторий; не смешивать Front и Back +alwaysApply: true +--- + +# EventHub: отдельные агенты по репозиториям + +## Правило +При работе с **несколькими репозиториями** EventHub запускай **отдельного агента на каждый репо**. Не смешивай Front и Back (и Spec/FrontAdmin) в одном агенте. + +| Репо | Зона | +|------|------| +| `EventHubFront` | клиентский SPA | +| `EventHubBack` | Erlang API | +| `EventHubSpec` | спеки, UI-PARITY, контракты | +| `EventHubFrontAdmin` | admin SPA | + +## Запрещено +- Один агент правит и Front, и Back в одной сессии +- Коммиты/`Refs`/`Fixes` не в тот репо (Front-код → issue Back, и наоборот) +- Закрывать/комментировать issue чужого репо «заодно» + +## Как делать +1. Спека/issue → агент **Spec** (или короткий foreground), если только доки. +2. API → отдельный агент **Back** (`Back#N`, eunit, push Back). +3. UI → отдельный агент **Front** (`Front#N`, lint/IFT, push Front). +4. Родитель-координатор только маршрутизирует; не пишет код сразу в два репо. + +Кросс-репо фича (например Bookings inbox): **сначала Back**, потом **Front** (или параллельно двумя агентами), Spec — третьим или после стабилизации API. diff --git a/.cursor/rules/otp-rebar-wsl.mdc b/.cursor/rules/otp-rebar-wsl.mdc new file mode 100644 index 0000000..0898924 --- /dev/null +++ b/.cursor/rules/otp-rebar-wsl.mdc @@ -0,0 +1,24 @@ +--- +description: EventHubBack — Erlang/rebar3 только в WSL (asdf OTP 28.2) +alwaysApply: true +--- + +# EventHubBack: OTP / rebar (WSL) + +Сборка и тесты бэка — **только в WSL**, не через Windows `erl`/`rebar3`. +Windows npm для соседних Front-репо тоже не использовать — см. `EventHubFront/.cursor/rules/npm-wsl.mdc`. + +| Tool | Version | Path | +|---|---|---| +| Erlang/OTP | 28.2 | `/home/alexc/.asdf/installs/erlang/28.2/bin` | +| rebar3 | 3.27.0 | `/home/alexc/.asdf/installs/rebar/3.27.0/bin` | + +Перед командами: + +```bash +cd /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubBack +source scripts/wsl-dev-env.sh +``` + +Или agent-скрипт: `bash ~/.cursor/eventhub/compile-back.sh` +Подробнее: `~/.cursor/eventhub/OTP-REBAR.md`, `EventHubSpec/WORKFLOW.md` §2.1. diff --git a/.cursor/rules/shell-wsl-not-powershell.mdc b/.cursor/rules/shell-wsl-not-powershell.mdc new file mode 100644 index 0000000..da0b704 --- /dev/null +++ b/.cursor/rules/shell-wsl-not-powershell.mdc @@ -0,0 +1,59 @@ +--- +description: EventHub — команды только через WSL/bash; PowerShell для сложного запрещён +alwaysApply: true +--- + +# EventHub: как запускать команды (обязательно) + +## Проблема +PowerShell в Cursor **ломает** кавычки, `$`, JSON, heredoc и вложенный `bash -lc "..."`. Из‑за этого агенты снова и снова получают `unexpected EOF`, `Invalid JSON`, пустой curl. + +## Правило +1. **Нельзя** гонять сложные one-liner’ы в PowerShell (npm, curl+JSON, python -c, git commit heredoc, вложенный bash с кавычками). +2. **Можно** в PowerShell только простые вещи: `cd`, `git status`, `ls`, одиночный `wsl …` без вложенных кавычек в аргументе. +3. Рабочий способ — **WSL bash** или **файл `.sh` + `wsl -e bash /path/to/script.sh`**. + +## Канон (копируй) + +### Вариант A — скрипт (предпочтительно) +1. Запиши команды в файл, например `EventHubBack/.tmp-run.sh` или `~/.cursor/eventhub/….sh` (LF, `#!/usr/bin/env bash`). +2. Запусти **без** вложенных кавычек в PowerShell: + +```text +wsl -e bash /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubBack/.tmp-run.sh +``` + +### Вариант B — один простой WSL вызов +Только если внутри **одинарные** кавычки bash и нет `"`/`$` конфликтов с PS: + +```text +wsl -e bash -lc 'cd /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubFront && npm run lint' +``` + +В PowerShell для `-lc` используй **одинарные** кавычки снаружи (`'...'`), внутри — обычный bash. + +### Запрещено +```text +wsl -e bash -lc ".... python -c \"import...\" ...." # ломается +curl ... -d "{\"email\":\"$x\"}" # в PS ломается +git commit -m "$(cat <<'EOF' ...)" # в PS не так +npm / npx / node из Windows # сломан +``` + +## Стек → команда + +| Задача | Как | +|-----|-----| +| Front lint/build/e2e | `wsl -e bash` + `cd …/EventHubFront && npm …` | +| Front перед push main | сначала `npm run test:e2e:ift` в WSL, потом `~/.cursor/eventhub/git-push-main.sh` | +| Back rebar/eunit | `source scripts/wsl-dev-env.sh` в WSL | +| Git commit/push | `~/.cursor/eventhub/git-commit.sh` / `git-push.sh` / `git-push-main.sh` | +| JSON/API/python | скрипт `.sh` или `.py` на диске, запуск из WSL | + +## Перед push Front +1. WSL: `npm run lint && npm run build` (ловит синтаксис/TS) +2. WSL: `npm run test:e2e:ift` +3. Только потом push. **Не пушить**, если lint/build/IFT красные. + +## Частые сбои (подробнее) +См. **`agent-pitfalls.mdc`**: git `-F` вместо heredoc, `&&` в PS, docker dev scale, `git clean` vs `.cursor/`.