diff --git a/.cursor/rules/agent-pitfalls.mdc b/.cursor/rules/agent-pitfalls.mdc index e0de740..ee1bb6f 100644 --- a/.cursor/rules/agent-pitfalls.mdc +++ b/.cursor/rules/agent-pitfalls.mdc @@ -1,28 +1,105 @@ --- -description: Типичные ошибки агентов EventHub — shell, git, docker, scope, токены +description: Типичные ошибки агентов EventHub — shell, git, docker, scope, токены (корень + субагенты) alwaysApply: true --- # EventHub: типичные ошибки агентов (избегать) -Полный текст: `EventHubBack/.cursor/rules/agent-pitfalls.mdc`. Кратко: +Канон. Субагентам: включать в промпт «следуй `agent-pitfalls.mdc` + `shell-wsl-not-powershell.mdc`». -## Shell -PS ломает кавычки/`$`/`&&` → **`.sh` + `wsl -e bash /mnt/c/.../script.sh`**. Не Windows `npm`/`rebar3`. +## 1. Shell / PowerShell -## Git -Commit: **`git commit -F .tmp-msg.txt`** или `~/.cursor/eventhub/git-commit.sh`. -**`git clean -fdx`** — не без backup; **не удалять** `.cursor/`, `.idea/`. -Push `master` — только по просьбе пользователя. +| Симптом | Причина | Как правильно | +|---------|---------|---------------| +| `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` | -## Docker dev -**Балансировка = traefik (1) + eventhub (1)**, не 3 реплики. -Host-порты 8080/8445 → scale eventhub >1 невозможен. -«Только бэк» — без сборки admin-ui/front. +**Запрещено в PS:** `wsl -e bash -lc "…\"…"`, `curl -d "{\"x\":…}"`, heredoc commit, `npm`/`rebar3`. -## Субагенты -Промпт: shell через WSL, один репо, итог на русском, см. `agent-pitfalls.mdc`. +## 2. Git -## Токены -Один чат = одна задача; `@` точечно; subagents редко и узко; Ask для вопросов, Agent для правок. -Полный §6: `EventHubBack/.cursor/rules/agent-pitfalls.mdc`. +| Симптом | Как правильно | +|---------|---------------| +| `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 «висит» / ждёт login | **Не** `git push origin` — только `~/.cursor/eventhub/git-push.sh` / `git-push-main.sh` | +| Push заблокирован Auto-review | Push в `master` — только по явной просьбе; `request_smart_mode_approval` | + +**`git clean` / reset к origin:** сначала сохранить `docker/.env*`, `.env.development`, `docker/traefik/certs/*`. + +**Push:** запрещены голые `git push` / `git push origin …`. Канон — `bash ~/.cursor/eventhub/git-push.sh ` (токен из secrets). + +## 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/shell-wsl-not-powershell.mdc b/.cursor/rules/shell-wsl-not-powershell.mdc index 804f74e..d585587 100644 --- a/.cursor/rules/shell-wsl-not-powershell.mdc +++ b/.cursor/rules/shell-wsl-not-powershell.mdc @@ -1,13 +1,71 @@ --- -description: Shell — только WSL/bash; PowerShell-экранирование запрещено для сложного +description: EventHub — команды только через WSL/bash; PowerShell для сложного запрещён alwaysApply: true --- -# Shell: WSL, не PowerShell +# EventHub: как запускать команды (обязательно) -Агенты **не должны** гонять сложные one-liner’ы в PowerShell (ломается экранирование). +## Проблема +PowerShell в Cursor **ломает** кавычки, `$`, JSON, heredoc и вложенный `bash -lc "..."`. Из‑за этого агенты снова и снова получают `unexpected EOF`, `Invalid JSON`, пустой curl. -Канон: файл `.sh` + `wsl -e bash /mnt/c/.../script.sh`, либо -`wsl -e bash -lc 'простая команда без вложенных двойных кавычек'`. +## Правило +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`**. -Полный текст: `EventHubBack/.cursor/rules/shell-wsl-not-powershell.mdc`. +## Канон (копируй) + +### Вариант 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 | + +## Git push (обязательно) + +**Запрещено агентам:** `git push`, `git push origin`, `git push origin HEAD` / `master` напрямую — без токена зависают на HTTPS prompt. + +**Канон:** +```text +bash ~/.cursor/eventhub/git-push.sh /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubBack +bash ~/.cursor/eventhub/git-push-main.sh /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubFront +``` + +Credential store в WSL уже настроен (`credential.helper=store` + `git.sabilin.com`); хелпер всё равно предпочтителен (явный URL с токеном из secrets). + +## Перед push Front +1. WSL: `npm run lint && npm run build` (ловит синтаксис/TS) +2. WSL: `npm run test:e2e:ift` +3. Только потом push через `git-push-main.sh`. **Не пушить**, если lint/build/IFT красные. + +## Частые сбои (подробнее) +См. **`agent-pitfalls.mdc`**: git `-F` вместо heredoc, `&&` в PS, docker dev scale, `git clean` vs `.cursor/`.