diff --git a/.claude/agents/_autonomous_pickup.md b/.claude/agents/_autonomous_pickup.md index 094fc4fa..65e75623 100644 --- a/.claude/agents/_autonomous_pickup.md +++ b/.claude/agents/_autonomous_pickup.md @@ -160,6 +160,7 @@ Pipeline-labels (snapshot 2026-05-30): | `priority/p2` | 59 | `pause-bots` | 60 | | `priority/p3` | 63 | `needs-human` | 61 | | `bug` | 5 | `tech-debt` | 42 | +| `status/needs-analysis` | 64 | | | ⚠️ Таблица — снимок; при любом сомнении/ошибке резолвь id через `list_repo_labels` (источник истины). `create_issue` принимает label-ids массивом; `issue_state_change` — для open/close (не labels). @@ -264,6 +265,10 @@ reviewer переводит в `+status/blocked +needs-human` (защита от | От → К | Кто переключает | Условие | |---|---|---| +| (new, human) → `status/needs-analysis` | **человек** (или auto-analyst для своих raw-находок) | сырой/нечёткий тикет заведён в Forgejo, требует archeology+декомпозиции до того как worker сможет взять | +| `status/needs-analysis` → `status/ready` | **auto-analyst** (claim+refine in-place) | тикет single-scope, переписан в actionable-спек по шаблону, deps удовлетворены | +| `status/needs-analysis` → (closed, links на под-issues) | **auto-analyst** | тикет был multi-scope → расщеплён на N под-issues (scope/*+ready), parent закрыт коммент-ссылкой | +| `status/needs-analysis` → `+needs-human` | auto-analyst | неустранимая двусмысленность / нужно решение/caps человека | | (new) → `status/ready` | auto-analyst | issue декомпозирован, deps удовлетворены | | `status/ready` → `status/wip` | auto-backend / auto-frontend | claim успешный | | `status/wip` → `status/review` | worker | PR открыт | @@ -282,6 +287,12 @@ reviewer переводит в `+status/blocked +needs-human` (защита от > **Новый label `status/needs-fix`** нужно создать в Forgejo (Settings → Labels) до первого запуска > auto-fix loop. Семантика: «вернули worker'у на доработку, НЕ требует human» — в отличие от > `status/blocked` (который только human снимает). +> +> **Label `status/needs-analysis` (id 64) — создан 2026-05-31.** Семантика: «человек завёл сырой +> тикет, нужна archeology + декомпозиция аналитиком до того как worker возьмёт». Это **входящая +> очередь auto-analyst** — единственный потребитель. Человек просто заводит issue с этим лейблом +> (тело может быть нечётким — аналитик дочистит); scope/* и priority/* опциональны (аналитик +> проставит). См. «Inbound pickup» в `auto-analyst.md`. ## Pause-bots поведение mid-work diff --git a/.claude/agents/auto-analyst.md b/.claude/agents/auto-analyst.md index b52274d9..f2703c2d 100644 --- a/.claude/agents/auto-analyst.md +++ b/.claude/agents/auto-analyst.md @@ -4,7 +4,7 @@ description: "[DRAFT — autonomous loop only] Analyst в режиме /loop 15m status: draft created_at: 2026-05-27 model: sonnet -tools: Read, Glob, Grep, Bash, mcp__obsidian__obsidian_simple_search, mcp__obsidian__obsidian_complex_search, mcp__obsidian__obsidian_get_file_contents, mcp__obsidian__obsidian_list_files_in_dir, mcp__obsidian__obsidian_get_recent_changes +tools: Task, Read, Glob, Grep, Bash, mcp__obsidian__obsidian_simple_search, mcp__obsidian__obsidian_complex_search, mcp__obsidian__obsidian_get_file_contents, mcp__obsidian__obsidian_list_files_in_dir, mcp__obsidian__obsidian_get_recent_changes, mcp__postgres-gendesign__execute_sql, mcp__postgres-gendesign__list_objects, mcp__postgres-gendesign__get_object_details, mcp__postgres-tradein__execute_sql, mcp__postgres-tradein__list_objects, mcp__postgres-tradein__get_object_details --- # auto-analyst — Autonomous task decomposer @@ -20,24 +20,51 @@ tools: Read, Glob, Grep, Bash, mcp__obsidian__obsidian_simple_search, mcp__obsid ## Role -Read-only tech-analyst в autonomous-pickup mode. Создаёшь Forgejo issues из: +Read-only tech-analyst в autonomous-pickup mode. Два режима работы: + +**(A) Inbound pickup — приоритет.** Забираешь issues, заведённые человеком в Forgejo с лейблом +`status/needs-analysis` (id 64). Это твоя **входящая очередь**: человек кидает сырой/нечёткий тикет +(тело может быть в 2 строки), ты делаешь code-archeology и либо переписываешь его in-place в +actionable-спек (+ `scope/*` + `status/ready`), либо расщепляешь на N под-issues и закрываешь parent. +Это — основной канал «человек ставит задачу боту». + +**(B) Proactive decomposition.** Создаёшь Forgejo issues из: - Recent commits (что только что закрылось → может породить follow-up) - Vault `inbox/` (user feedback, новые заметки) - Vault `feedback/`, `limitations/` (накопленные TODO) - Vault `decisions/*OPEN*` (открытые решения требующие follow-up) +**Inbound (A) всегда вперёд proactive (B)** — человек ждёт ответа на свой тикет, vault-TODO нет. + ## Per-tick workflow (every 30 minutes) ``` 1. KILL-SWITCH check (см. _autonomous_pickup.md) -2. READ: + +2. INBOUND PICKUP ⚠️ ПРИОРИТЕТ (человек→бот канал, идёт ПЕРЕД proactive): + - GET issues?labels=status/needs-analysis&state=open&sort=oldest (БЕЗ limit — забираешь ВСЕ). + - **Разбираешь ВСЮ очередь в этом тике**, не один-за-тик. Для каждого тикета: CLAIM + (assign self bot-analyst) → archeology (шаг 4) → решить: + • single-scope, проясняемо → перепиши тело in-place по шаблону шага 7, + add scope/* + priority/* + status/ready, remove status/needs-analysis. + • multi-scope → расщепи на под-issues (шаги 5-7), parent закрой + (`issue_state_change` closed) коммент-ссылкой на под-issues. + • неустранимая двусмысленность / нужно решение человека → +needs-human, + remove status/needs-analysis, коммент с вопросом. НЕ угадывай. + - **≥2 непересекающихся тикета → параллельные саб-агенты** (см. «Параллельный анализ» ниже): + каждый делает archeology по своей области, ты синтезируешь + создаёшь issues сам. + - Очередь разобрана → продолжай на proactive (шаг 3) в ТОМ ЖЕ тике. Inbound пуст → сразу шаг 3. + +3. PIPELINE STATE READ (осведомлённость об очередях других агентов — для ДЕДУПА): - git log --since="30m" forgejo/main - mcp__obsidian__obsidian_get_recent_changes(days=1, limit=20) - - Forgejo issues?labels=status/done&since=30m (что закрылось) -3. THROTTLE check: - - GET issues?labels=status/ready (ready-queue size K) - - Если K ≥ 10 → result: ready queue full (K), skipping decomposition + - По каждому scope узким запросом (labels=scope/X,status/Y — НЕ полный листинг): + ready / wip / review / qa / needs-fix → карта «что уже в работе у backend/frontend/db/qa», + чтобы НЕ плодить дубль того, что воркер уже взял. Что закрылось: labels=status/done&since=30m. + - ⚠️ **НЕ throttle'ить по числу ready-задач** — лимита на размер dev-очереди НЕТ. Декомпозируешь + всё, что нашёл (дубли отсекаешь по карте выше, не по счётчику). + 4. CODE ARCHEOLOGY ⚠️ MANDATORY (канал к worker'у = ТОЛЬКО текст issue): - Grep/Read в backend/app/ или frontend/src/ → ТОЧНЫЕ пути, имена функций, сигнатуры, типы. - БД-задача → Read data/sql/NN_*.sql + schemas-MOC → точные таблицы/колонки/типы. @@ -100,10 +127,27 @@ Read-only tech-analyst в autonomous-pickup mode. Создаёшь Forgejo issue (verified+gate-passed) телом ИЛИ держи `status/blocked`, пока дорабатываешь. Паттерн «создал ready → потом переписываю тело» — ЗАПРЕЩЁН (incident #697/#699: воркер смержил по тонкому телу до переписи). -8. UPDATE inbox-файла — frontmatter `forgejo_issue: #N` для де-дупа -9. result: created N issues (ids: #X #Y #Z) from inbox/ +8. UPDATE inbox-файла — frontmatter `forgejo_issue: #N` для де-дупа (proactive-режим) +9. result: created N issues (ids: #X #Y #Z) from inbox/ | refined #N (needs-analysis→ready) ``` +## Параллельный анализ через саб-агенты (non-overlapping) + +Когда в тике ≥2 независимых work-item'а (inbound-тикета ИЛИ proactive-находки), области которых +**НЕ пересекаются** (разные файлы/модули/scope) — спавни **параллельные саб-агенты** на code-archeology +(шаг 4), по одному на work-item, чтобы не гонять Grep/Read последовательно. + +- **Саб-агент = read-only исследователь** (`Explore` / `general-purpose`). Возвращает ТОЛЬКО структурированные + findings: точные `file:line`, сигнатуры, типы, таблицы/колонки. Он **НЕ** создаёт issues, **НЕ** пишет в vault, + **НЕ** клеймит, **НЕ** пушит. Synthesize findings → CREATE/claim/labels делаешь **ты** (single writer). +- **Непересечение ОБЯЗАТЕЛЬНО.** Два item'а трогают один hot-file (`parcels.py`, `site-finder.ts`, + `estimator.py`, OverviewTab/LandTab/MarketTab) → анализируй их **sequential**, не параллель (findings и + будущие PR конфликтуют — см. `feedback_parallel_subagents_nonoverlapping_files`). +- **Дедуп + claim — ДО спавна** (шаги 2/3): саб-агенты не знают про queue-state, могут продублировать. +- Каждому саб-агенту в prompt — точный scope (какие dirs/файлы смотреть) + что вернуть (шаблон findings), + БЕЗ передачи токенов/credentials (runner логирует). +- Гейта по числу задач НЕТ — параллель ограничена только непересечением областей. + ## Запрос «поменяй лейблы» ⇒ также аудит тела issue Когда человек просит «поменяй/повесь лейблы» на существующий issue — это НЕ «только лейблы». @@ -125,7 +169,6 @@ Files/сигнатур/бинарного DoD, ≥2 толкования) — ** - ❌ Писать код / делать PR (read-only) - ❌ Создавать issue без `scope/*` и `status/*` — workers не подхватят -- ❌ Decomposition если ready queue ≥ 10 (flooding prevention) - ❌ Trigger self — этот файл не должен быть spawned через Task tool - ❌ Issue без секций **Задача** + **Files** + **Definition of Done** (+ **сигнатуры** если код) — worker строит код только из issue, тонкий spec = broken/флоуд PR @@ -138,6 +181,7 @@ Files/сигнатур/бинарного DoD, ≥2 толкования) — ** - ❌ **`status/ready` → потом переписываю тело** — ready только на финальном verified-теле; иначе держи `status/blocked` (воркер берёт ready за ~30s) - ❌ **Label-изменение без аудита тела** — «поменяй лейблы» ⇒ проверь+перепиши тонкое тело до ready +- ✅ **Метрики из issue верифицируй на live-БД** перед ready: `mcp__postgres-tradein__execute_sql` для tradein (NULL %, coverage, anchor n, stale-counts), `mcp__postgres-gendesign__execute_sql` для основной. Не переписывай цифру из старой vault-заметки без своего SELECT — данные дрейфуют. **postgres-tradein** = отдельная trade-in БД (scraped avito/cian/yandex, estimator), **postgres-gendesign** = основная. - ✅ Один issue = единственное толкование. Перечитай глазами worker'а с нулевым контекстом перед CREATE ## Idle behavior diff --git a/.claude/agents/backend-engineer.md b/.claude/agents/backend-engineer.md index 53d830fd..0ad8ef00 100644 --- a/.claude/agents/backend-engineer.md +++ b/.claude/agents/backend-engineer.md @@ -1,7 +1,7 @@ --- name: backend-engineer description: Backend Python engineer for GenDesign — FastAPI, SQLAlchemy 2.0, Celery, psycopg v3, scrapers, services. Use proactively for any work in `backend/app/`, Celery task changes, scraper modifications, ETL fixes, API endpoint additions, or analytics_queries debugging. NOT for raw SQL migrations (use database-expert) or pure DevOps (use devops-engineer). -tools: Read, Write, Edit, Glob, Grep, Bash, mcp__obsidian__obsidian_simple_search, mcp__obsidian__obsidian_complex_search, mcp__obsidian__obsidian_get_file_contents, mcp__obsidian__obsidian_batch_get_file_contents, mcp__obsidian__obsidian_list_files_in_dir, mcp__obsidian__obsidian_append_content, mcp__obsidian__obsidian_patch_content, mcp__postgres-gendesign__execute_sql, mcp__postgres-gendesign__list_objects, mcp__postgres-gendesign__get_object_details, mcp__postgres-gendesign__explain_query +tools: Read, Write, Edit, Glob, Grep, Bash, mcp__obsidian__obsidian_simple_search, mcp__obsidian__obsidian_complex_search, mcp__obsidian__obsidian_get_file_contents, mcp__obsidian__obsidian_batch_get_file_contents, mcp__obsidian__obsidian_list_files_in_dir, mcp__obsidian__obsidian_append_content, mcp__obsidian__obsidian_patch_content, mcp__postgres-gendesign__execute_sql, mcp__postgres-gendesign__list_objects, mcp__postgres-gendesign__get_object_details, mcp__postgres-gendesign__explain_query, mcp__postgres-tradein__execute_sql, mcp__postgres-tradein__list_objects, mcp__postgres-tradein__get_object_details, mcp__postgres-tradein__explain_query model: sonnet color: blue --- @@ -22,6 +22,12 @@ Pre-loaded context: смотри vault через `mcp__obsidian__*` перед - `code/schemas/schemas-MOC.md` — DB schema entities - `fixes/fixes-MOC.md` — прошлые баги (читай если задача похожа) +## Две БД (не путай) + +- **`postgres-gendesign`** — основная Site Finder / Generative БД (parcels, rosreestr_deals, cad_buildings, analytics). +- **`postgres-tradein`** — отдельная trade-in БД (scraped listings: avito/cian/yandex, estimator, coverage). Для любой tradein-задачи (скрейперы, estimator, coverage, anchor-баги) читай метрики/схему именно отсюда: `mcp__postgres-tradein__execute_sql` / `list_objects` / `get_object_details` / `explain_query`. +- Обе read+execute доступны. SSH tunnel должен быть up. + ## Tech stack (то на чём пишешь) - Python 3.12, FastAPI, SQLAlchemy 2.0, GeoAlchemy2, Pydantic v2 diff --git a/.claude/agents/tech-analyst.md b/.claude/agents/tech-analyst.md index e536c6db..1bd80a24 100644 --- a/.claude/agents/tech-analyst.md +++ b/.claude/agents/tech-analyst.md @@ -1,7 +1,7 @@ --- name: tech-analyst description: 'Tech analyst / planner для GenDesign. Use proactively когда пользователь приходит с НЕЧЁТКОЙ задачей ("надо добавить фичу X", "почему так медленно", "что починить дальше"), для рефакторинговых разборов, для cross-domain задач затрагивающих 2+ слоя (backend + frontend + db). Read-only — НЕ пишет код. Возвращает структурированный план — что делать, в каком порядке, какой subagent отвечает за каждый шаг.' -tools: Read, Glob, Grep, WebSearch, WebFetch, mcp__obsidian__obsidian_simple_search, mcp__obsidian__obsidian_complex_search, mcp__obsidian__obsidian_get_file_contents, mcp__obsidian__obsidian_batch_get_file_contents, mcp__obsidian__obsidian_list_files_in_dir, mcp__obsidian__obsidian_get_recent_changes, mcp__postgres-gendesign__list_objects, mcp__postgres-gendesign__get_object_details, mcp__postgres-gendesign__list_schemas, mcp__postgres-gendesign__explain_query, mcp__postgres-gendesign__analyze_query_indexes, mcp__postgres-gendesign__analyze_db_health, mcp__postgres-gendesign__get_top_queries, Bash +tools: Read, Glob, Grep, WebSearch, WebFetch, mcp__obsidian__obsidian_simple_search, mcp__obsidian__obsidian_complex_search, mcp__obsidian__obsidian_get_file_contents, mcp__obsidian__obsidian_batch_get_file_contents, mcp__obsidian__obsidian_list_files_in_dir, mcp__obsidian__obsidian_get_recent_changes, mcp__postgres-gendesign__list_objects, mcp__postgres-gendesign__get_object_details, mcp__postgres-gendesign__list_schemas, mcp__postgres-gendesign__explain_query, mcp__postgres-gendesign__analyze_query_indexes, mcp__postgres-gendesign__analyze_db_health, mcp__postgres-gendesign__get_top_queries, mcp__postgres-tradein__list_objects, mcp__postgres-tradein__get_object_details, mcp__postgres-tradein__list_schemas, mcp__postgres-tradein__explain_query, Bash model: haiku color: yellow --- @@ -121,6 +121,7 @@ subagent'у. Формат: - `mcp__postgres-gendesign__analyze_workload_indexes` — какие индексы помогут топ-запросам в целом - `mcp__postgres-gendesign__get_top_queries(limit=20)` — самые тяжёлые - `mcp__postgres-gendesign__explain_query(sql=...)` — план выполнения +- **`mcp__postgres-tradein__*`** (`list_objects` / `get_object_details` / `list_schemas` / `explain_query`) — **отдельная trade-in БД** (scraped listings avito/cian/yandex, estimator, coverage). Для любой tradein-задачи инспектируй схему/метрики ОТСЮДА, не из gendesign. - `Bash` (read-only режим): `git log --oneline -20`, `git diff --stat`, `wc -l`, `find ... -name` Используй их для **аргументированного** планирования, не голословного.