From 79e4528eeb23721bbce4a4345b7f728043bacc34 Mon Sep 17 00:00:00 2001 From: bot-backend Date: Thu, 2 Jul 2026 17:28:05 +0300 Subject: [PATCH] chore(claude): port delegation limits to repo rules, fix git-pr staleness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - new rules/delegation.md (always-loaded): subagent budget, oversized escalation, единые пороги дробления, parallel-default — портировано из memory 2026-06-27 - git-pr.md: parallel-default вместо sequential (supersedes), list_pull_reviews, фактические worktree settings, typos - CLAUDE.md: merge-политика 2026-06-27, tradein/delegation в списке rules, auto-* vs Task-spawn различие --- .claude/rules/delegation.md | 27 +++++++++++++++++++++++++++ .claude/rules/git-pr.md | 20 ++++++++++++-------- CLAUDE.md | 10 ++++++---- 3 files changed, 45 insertions(+), 12 deletions(-) create mode 100644 .claude/rules/delegation.md diff --git a/.claude/rules/delegation.md b/.claude/rules/delegation.md new file mode 100644 index 00000000..51a4b223 --- /dev/null +++ b/.claude/rules/delegation.md @@ -0,0 +1,27 @@ +# Delegation & task sizing + +> Без `paths:` — загружается в каждой сессии. Канон лимитов делегирования (портировано из memory-фидбека 2026-06-27). + +## Бюджет одного сабагента (hard limits) + +- **1 сабагент = 1 узкий deliverable.** Ориентиры: ~≤10 мин работы, ~≤20 tool-calls, ~≤150k токенов. + Эмпирика 2026-06-27: агент-аудитор на 186k tok / 33 calls упал на StructuredOutput; 5 мелких параллельных прошли. +- Поверхность больше бюджета → **дели на N узких сабагентов** (parallel при непересекающихся файлах, sequential при зависимостях). НЕ один большой. +- Read-only разведка (найти файлы/понять структуру) → лёгкий Explore-agent, не general-purpose worker. +- Промпт сабагенту: конкретный deliverable + формат ответа + границы («что НЕ делать»). Расплывчатый scope = дубли и мусор. + +## Эскалация oversized-задачи (worker) + +Issue/задача выглядит больше одного захода (эвристика: >5 файлов, ИЛИ >500 строк diff, ИЛИ >2ч) → **НЕ исполнять целиком**: +- bot-pipeline: комментарий с планом сплита + label `status/needs-analysis`, снять claim +- interactive: вернуть main-сессии план сплита вместо результата + +## Единые пороги дробления (analyst / main) + +- Estimate S(<2h) / M(2-8h) / **L(>8h) → обязан дробиться дальше** (до S/M) +- Issue ≥1.5 дня → 3-4 sub-PR (Foundation → Schema → Workers → Integration), каждый ~200-500 строк — см. git-pr.md § Split big issues +- 1 sub-issue ≈ 1-2 worker-захода, single-scope (не смешивать backend+frontend в одном issue) + +## Параллелизм + +Default = parallel на непересекающихся файлах (per-task worktree). Sequential — только overlap / hot-files / зависимый стек (git-pr.md § Parallel vs sequential PRs). diff --git a/.claude/rules/git-pr.md b/.claude/rules/git-pr.md index fddbd6dd..a0e9d1f5 100644 --- a/.claude/rules/git-pr.md +++ b/.claude/rules/git-pr.md @@ -16,11 +16,11 @@ paths: ``` 1. claude --bg --name "feat-" "task description" → supervisor создаёт worktree от forgejo/main автоматически - (settings worktree.baseRef=default, bgIsolation=git) + (settings worktree.baseRef=fresh, bgIsolation=worktree) 2. Session работает: код → commit → push → mcp__forgejo__create_pull_request 3. PR URL появляется в agent view как row с зелёной/жёлтой/красной ● status dot 4. User делает review через external Claude window (post-push) -5. После merge — `Ctrl+X dwa раза` в agent view = удаление session + worktree +5. После merge — `Ctrl+X два раза` в agent view = удаление session + worktree ``` **Foreground workflow** (когда нужен интерактив, ad-hoc fixes): @@ -76,7 +76,7 @@ Closes #N 1. `mcp__forgejo__get_pull_request` (или `curl -sH "$H" "$REPO/pulls/"`) → читай `state`, `mergeable`, `head.sha` 2. `state == merged` → stop polling -3. Новый review/comment: `mcp__forgejo__list_pr_reviews` / `list_issue_comments`. Парсь marker `` +3. Новый review/comment: `mcp__forgejo__list_pull_reviews` / `list_issue_comments`. Парсь marker `` - **SHA guard**: `marker.sha7 == head.sha[:7]` — иначе устаревший approval до fixup-push, игнорируй - `verdict=approve` + SHA match → `mcp__forgejo__merge_pull_request` (squash + delete branch) - `verdict=changes` → fixup commits + push в `forgejo feat/` + re-poll @@ -91,16 +91,20 @@ Closes #N - Diff содержит литеральный secret/token/password/credential (40-char hex, API keys, JWT, и т.д.) — security tripwire. - PR меняет правила самого пайплайна: блок `## Auto-merge policy` здесь, `Critical rules` в CLAUDE.md, `_autonomous_pickup.md` (claim/kill-switch/merge-FSM), `auto-code-reviewer.md` или любой `work-as-*.md` — **self-extending guard** (расширение/снятие собственных merge-прав всегда через human, предотвращает bot-loop). -## Sequential PRs +## Parallel vs sequential PRs -**Одна задача → один PR → merge → следующая.** Параллельно ТОЛЬКО если scope'ы строго orthogonal (разные файлы). +**Default = параллельно**, если scope'ы НЕ пересекаются по файлам: каждая задача в своём worktree (`git worktree add` / isolation:"worktree"), своя ветка, свой PR. -Опасные файлы для конфликтов: `backend/app/api/v1/parcels.py`, `frontend/src/types/site-finder.ts`, OverviewTab/LandTab/MarketTab. +**Sequential обязателен когда:** +- Пересечение файлов / hot-files: `backend/app/api/v1/parcels.py`, `frontend/src/types/site-finder.ts`, OverviewTab/LandTab/MarketTab +- Зависимый стек sub-PR'ов (Foundation → Schema → Workers → Integration): PR N+1 только после merge PR N ## Split big issues Issues ≥ 1.5 day → 3-4 sub-PRs: **Foundation → Schema → Workers → Integration**. Каждый ~200-500 lines. PR N+1 только после merge PR N. +Бюджет одного subagent-захода и правила эскалации oversized-задач: `.claude/rules/delegation.md`. + ## Review workflow (no conflict) - **Pre-push** (локально): spawn `code-reviewer` subagent на staged changes → lint pass (security, correctness, conventions). Блокирует push при 🔴 критикал. @@ -112,12 +116,12 @@ Issues ≥ 1.5 day → 3-4 sub-PRs: **Foundation → Schema → Workers → Inte - **Параллелизм**: 3-5 sessions одновременно (>5 = bottleneck на review, не на Claude per Anthropic метрика) - **Pin (`Ctrl+T`)** для long-running sessions (scraper monitors, deploy watchers) — supervisor не убьёт через 1h idle -- **Cleanup**: `Ctrl+X dwa раза` после merge → session + worktree удалены атомарно +- **Cleanup**: `Ctrl+X два раза` после merge → session + worktree удалены атомарно - **NEVER** parallel sessions на one file — каждая ест в own worktree, last-merge wins (используй sequential PR rule выше) **Manual `git worktree add` deprecated** — используй `claude --bg --name X`, supervisor сам isolation делает с `baseRef: default` (свежая ветка от main, не от твоей stale-сессии). -**Worktree cleanup** (cron weekly): `scripts/cleanup-merged-worktrees.sh` — удаляет worktrees для merged branches. Запускать вручную или wee­k­ly cron. +**Worktree cleanup** (cron weekly): `scripts/cleanup-merged-worktrees.sh` — удаляет worktrees для merged branches. Запускать вручную или weekly cron. ## Запреты diff --git a/CLAUDE.md b/CLAUDE.md index 60980af9..4378fa5c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,7 @@ Live: `https://gendsgn.ru/` — Свердловская обл. (ЕКБ, ПЗЗ 2. **Branch + PR mandatory.** Никаких direct push в main. `feat/...` / `fix/...` / `refactor/...` / `docs/...` / `chore/...` → ветка от `forgejo/main` → `mcp__forgejo__create_pull_request` → PR URL пользователю. После PR create — сразу `Skill loop` polling. `gh` CLI bypassed (2026-05-16). **Полные правила: `.claude/rules/git-pr.md`**. -3. **Agent-first workflow.** Main session orchestrates ONLY — не пишет код inline. Любая задача >1 файл / >50 строк → subagent. Pre-push: spawn `code-reviewer` subagent на staged changes. Post-push review — внешнее окно Claude (НЕ дублировать). +3. **Agent-first workflow.** Main session orchestrates ONLY — не пишет код inline. Любая задача >1 файл / >50 строк → subagent. Pre-push: spawn `code-reviewer` subagent на staged changes. Post-push review — внешнее окно Claude (НЕ дублировать). Лимиты размера subagent-задачи: `.claude/rules/delegation.md`. 4. **psycopg v3 only.** `import psycopg2` → ModuleNotFoundError. `CAST(:x AS type)` в SQL — никогда `:x::type`. **Полные правила: `.claude/rules/backend.md` + `sql.md`**. @@ -41,14 +41,16 @@ Live: `https://gendsgn.ru/` — Свердловская обл. (ЕКБ, ПЗЗ | `database-expert` | `data/sql/**.sql`, Alembic, EXPLAIN ANALYZE | | `devops-engineer` | `docker-compose*.yml`, `Caddyfile`, `.github/workflows/**`, `.forgejo/workflows/**` | | `code-reviewer` | Pre-push lint (security, correctness, conventions) | -| `deep-code-reviewer` | Тщательный review критичных PR (миграции / auth / scrapers) + merge authority при ✅ APPROVE | +| `deep-code-reviewer` | Тщательный review критичных PR (миграции / auth / scrapers) + merge authority при ✅ APPROVE (не эксклюзивно: self-merge разрешён любой сессии с 2026-06-27) | | `qa-tester` | Post-deploy smoke (playwright / curl / SQL) сразу после merge+deploy — rule #7 | +`auto-*` в `.claude/agents/` — standalone bot-персоны (`/work-as-*`), НЕ для Task-spawn; общий контракт — `_autonomous_pickup.md`. + **Routing:** тривиально (typo, 1-line) → main session. Single-domain clear → worker. Cross-domain / нечётко → `tech-analyst` first. Worker → `code-reviewer` → main commits → push → PR. ## Where to look -- **Path-scoped rules:** `.claude/rules/` (backend, frontend, sql, git-pr, deploy, ui-tokens, ui-conventions, ui-microcopy) — auto-loaded при работе с соответствующими файлами через `paths:` frontmatter +- **Path-scoped rules:** `.claude/rules/` (backend, frontend, sql, git-pr, deploy, tradein, delegation, ui-tokens, ui-conventions, ui-microcopy) — auto-loaded при работе с соответствующими файлами через `paths:` frontmatter - **Personal preferences:** `~/.claude/CLAUDE.md` (cross-project: no auto-commit, no Co-Authored-By, no @claude) - **Workflow memory:** `~/.claude/projects//memory/MEMORY.md` index - **Vault MOCs:** `meta/`, `domains//-MOC.md`, `decisions/`, `fixes/`, `limitations/`, `code/patterns/` @@ -56,7 +58,7 @@ Live: `https://gendsgn.ru/` — Свердловская обл. (ЕКБ, ПЗЗ ## Don't (cross-domain — specifics → `.claude/rules/`) -- ❌ Direct push в main / merge без approval +- ❌ Direct push в main; merge вне policy (красный CI / tripwires — git-pr.md § Auto-merge policy) - ❌ `--no-verify` / `--amend` / `git push --force` - ❌ Knowledge-файлы вне vault (`docs/research/`, `notes/`, `wiki/`) - ❌ Hardcode credentials в коде / коммитах