docs: agent pitfalls + token economy rules for Cursor [skip ci]

2026-07-27 21:53:10 +03:00
parent 8f931db0f0
commit 68a57a33c2
5 changed files with 104 additions and 0 deletions
@@ -0,0 +1,14 @@
+---
+description: Типичные ошибки агентов — см. EventHubBack/agent-pitfalls.mdc
+alwaysApply: true
+---
+
+# Agent pitfalls (FrontAdmin)
+
+Канон: **`EventHubBack/.cursor/rules/agent-pitfalls.mdc`**.
+
+FrontAdmin-специфика:
+- `npm` — **только WSL** (`npm-wsl.mdc`).
+- Сложные команды — **`.sh`**, не PowerShell one-liner.
+- Субагент: один репо (`EventHubFrontAdmin`), итог на русском.
+- Токены: §6 `agent-pitfalls.mdc` — не full build/e2e без запроса.
@@ -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 пользователя
@@ -0,0 +1,18 @@
+---
+description: EventHubFrontAdmin — npm/lint/e2e только через WSL (Windows npm сломан)
+alwaysApply: true
+---
+
+# EventHubFrontAdmin: Node / npm (WSL)
+
+**Запрещено:** `npm` / `npx` / `node` из Windows PowerShell/CMD.
+
+**Обязательно:** команды только в **WSL**:
+
+```bash
+wsl -e bash -lc 'cd /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubFrontAdmin && npm run lint'
+wsl -e bash -lc 'cd /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubFrontAdmin && npm run build'
+wsl -e bash -lc 'cd /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubFrontAdmin && npm test'
+```
+
+Push: обычно `master` через `bash ~/.cursor/eventhub/git-push.sh …/EventHubFrontAdmin`
@@ -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.
@@ -0,0 +1,16 @@
+---
+description: Shell — только WSL/bash; не экранировать сложное через PowerShell
+alwaysApply: true
+---
+
+# Shell: WSL, не PowerShell
+
+PowerShell ломает кавычки/`$`/JSON. Сложные команды — **только** через WSL:
+
+```text
+wsl -e bash /mnt/c/Users/alexc/IdeaProjects/eventHub/EventHubFrontAdmin/.tmp-run.sh
+```
+
+или `wsl -e bash -lc 'cd /mnt/c/.../EventHubFrontAdmin && npm run lint'`.
+
+Не использовать Windows `npm`. См. также `npm-wsl.mdc` и правило в EventHubBack `shell-wsl-not-powershell.mdc`.