From 96f320cabc3e15bfebc2778018e53e7faba0931f Mon Sep 17 00:00:00 2001
From: Aleksey Sabilin <aleksey@sabilin.com>
Date: Mon, 27 Jul 2026 21:50:59 +0300
Subject: [PATCH] docs: agent pitfalls + token economy rules for Cursor [skip
 ci]

---
 .cursor/rules/agent-pitfalls.mdc | 28 ++++++++++++++++++++++++++++
 .cursor/rules/agents-russian.mdc | 27 +++++++++++++++++++++++++++
 WORKFLOW.md                      | 15 +++++++++++++++
 3 files changed, 70 insertions(+)
 create mode 100644 .cursor/rules/agent-pitfalls.mdc
 create mode 100644 .cursor/rules/agents-russian.mdc

diff --git a/.cursor/rules/agent-pitfalls.mdc b/.cursor/rules/agent-pitfalls.mdc
new file mode 100644
index 0000000..e0de740
--- /dev/null
+++ b/.cursor/rules/agent-pitfalls.mdc
@@ -0,0 +1,28 @@
+---
+description: Типичные ошибки агентов EventHub — shell, git, docker, scope, токены
+alwaysApply: true
+---
+
+# EventHub: типичные ошибки агентов (избегать)
+
+Полный текст: `EventHubBack/.cursor/rules/agent-pitfalls.mdc`. Кратко:
+
+## Shell
+PS ломает кавычки/`$`/`&&` → **`.sh` + `wsl -e bash /mnt/c/.../script.sh`**. Не Windows `npm`/`rebar3`.
+
+## Git
+Commit: **`git commit -F .tmp-msg.txt`** или `~/.cursor/eventhub/git-commit.sh`.  
+**`git clean -fdx`** — не без backup; **не удалять** `.cursor/`, `.idea/`.  
+Push `master` — только по просьбе пользователя.
+
+## Docker dev
+**Балансировка = traefik (1) + eventhub (1)**, не 3 реплики.  
+Host-порты 8080/8445 → scale eventhub >1 невозможен.  
+«Только бэк» — без сборки admin-ui/front.
+
+## Субагенты
+Промпт: shell через WSL, один репо, итог на русском, см. `agent-pitfalls.mdc`.
+
+## Токены
+Один чат = одна задача; `@` точечно; subagents редко и узко; Ask для вопросов, Agent для правок.  
+Полный §6: `EventHubBack/.cursor/rules/agent-pitfalls.mdc`.
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/WORKFLOW.md b/WORKFLOW.md
index 023343c..e7ce9fd 100644
--- a/WORKFLOW.md
+++ b/WORKFLOW.md
@@ -94,6 +94,19 @@ rebar3 ct --suite=api_admins_SUITE
 
 Agent: `~/.cursor/eventhub/compile-back.sh`, `run-api-tests.sh`; см. `~/.cursor/eventhub/OTP-REBAR.md`.
 
+### Экономия токенов (Agent)
+
+| Принцип | Как |
+|---------|-----|
+| Один чат — одна задача | Новый issue → новый чат (§5); после «готово» не продолжать тред |
+| Узкий scope в запросе | «Репо, issue, только X, не Y, done = …» |
+| Меньше tool turns | `.sh` с первого раза; не PS retry; targeted eunit/lint |
+| Subagents редко | Узкий промпт, один репо, без копии всей переписки |
+| Режим | Ask/Plan для обсуждения; Agent для кода и shell |
+| Повторяемое | Скрипты в `~/.cursor/eventhub/`, не заново в чате |
+
+Канон: `EventHubBack/.cursor/rules/agent-pitfalls.mdc` §6.
+
 ### Git-коммиты из WSL (Agent и разработчик)
 
 Коммиты из **Agent Shell / PowerShell** ломаются: Cursor подставляет `--trailer "Co-authored-by: Cursor <cursoragent@cursor.com>"`, а PowerShell падает на `<`.
@@ -364,6 +377,7 @@ error rate > 1% **или** mean request > 500 ms (hold ≥2 мин в фазе)
 - Код фичи — в репозитории-владельце; `EventHubSpec` — для документации и процесса.
 - **Один агент — один репо** (не смешивать Front/Back/Spec/FrontAdmin в одной сессии): `.cursor/rules/one-repo-per-agent.mdc`.
 - **Типовые ошибки агентов** (PS, git clean, docker scale, scope): `EventHubBack/.cursor/rules/agent-pitfalls.mdc`; в промпт субагента включать shell + pitfalls.
+- **Экономия токенов:** один чат — одна задача; узкий scope; subagents редко; Ask vs Agent — см. `agent-pitfalls.mdc` §6 и §2.1 выше.
 - Метки во всех репозиториях держать одинаковыми (`sync-labels.ps1`).
 - Секреты и токены не коммитить; Gitea token — только в env / `~/.cursor/secrets/`.
 - **Git commit/push — через WSL** (`~/.cursor/eventhub/git-commit.sh`, `git-push.sh`); **push — только после подтверждения пользователя** (см. §2.1).
@@ -380,6 +394,7 @@ error rate > 1% **или** mean request > 500 ms (hold ≥2 мин в фазе)
 | Дата | Изменение |
 |------|-----------|
 | 2026-07-27 | Spec sync Back#61: `specialist_id` на POST event; commercial без active sub → 402; trial только `start_trial` |
+| 2026-07-27 | `agent-pitfalls.mdc` §6: экономия токенов (чат, scope, subagents, режимы) |
 | 2026-07-27 | `agent-pitfalls.mdc`: типовые сбои PS/git/docker/scope; промпт субагентам |
 | 2026-07-27 | Spec sync: booking `expired` (Back#60) + Front#31 UX (desktop chrome, empty bookings, agenda copy, Discover covers, nickname, invites badge) |
 | 2026-07-27 | Spec#12: booking-requests + Bookings IA + image_url; правило one-repo-per-agent |