From 5b741578e67ddc0201023e32b74e9cea32173e02 Mon Sep 17 00:00:00 2001
From: lekss361 <claudestars@proton.me>
Date: Mon, 11 May 2026 14:36:34 +0300
Subject: [PATCH] feat(claude): add 4 workers + tech-analyst subagents
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Worker agents (write code):
- backend-engineer (blue, sonnet)
- frontend-engineer (green, sonnet)
- devops-engineer (orange, sonnet)
- database-expert (purple, sonnet)

Analyst/planner (read-only, no code):
- tech-analyst (yellow, sonnet) — decomposes vague/cross-domain
  requests into structured plans for workers. Has read-only tools
  (Read/Glob/Grep, MCP obsidian/postgres read APIs, WebSearch) but
  NO Write/Edit/execute_sql/destructive Bash.

CLAUDE.md updated:
- Workers (4) vs Analyst (1) classification
- Routing rules: trivial → main, single-domain → worker direct,
  vague/cross-domain → tech-analyst first
- Cross-domain orchestration pattern with explicit flow

Each agent file:
- Pre-loaded vault MOC pointers for the domain
- Tech stack + conventions specific to the layer
- 5-8 critical pitfalls from real bugs this sprint
- Explicit deny-list of cross-scope operations
---
 CLAUDE.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index f19d327d..e8af0f36 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -247,6 +247,60 @@ GitHub Actions:
 
 Sentry release tracking: `SENTRY_RELEASE=$IMAGE_TAG` пишется в `backend/.env.runtime` на VPS через `sed` (НЕ полная перезапись файла — там user-managed `COUCHDB_PASSWORD` и пр.).
 
+## Specialized subagents
+
+В `.claude/agents/` лежит 5 subagent'ов — 4 worker'a + 1 analyst/planner. Каждый имеет:
+- Свой context window (не засоряет main session)
+- Restricted tool set (не делает что-то вне его scope)
+- Pre-loaded knowledge о доменных конвенциях
+
+### Workers (4) — пишут код
+
+| Agent | Когда использовать |
+|---|---|
+| **backend-engineer** (blue) | Работа в `backend/app/` — FastAPI, Celery, scrapers, services, ETL |
+| **frontend-engineer** (green) | Работа в `frontend/` — Next.js pages, components, hooks, admin UI |
+| **devops-engineer** (orange) | `docker-compose*.yml`, `Caddyfile`, `.github/workflows/`, deploy issues, SSH operations |
+| **database-expert** (purple) | `data/sql/NN_*.sql` migrations, Alembic, EXPLAIN ANALYZE, index design, schema changes |
+
+### Analyst (1) — планирует, не пишет
+
+| Agent | Когда использовать |
+|---|---|
+| **tech-analyst** (yellow) | Нечёткий запрос ("надо ускорить", "что чинить дальше"), cross-domain задачи (2+ слоя), рефакторинг-разборы, аудит. **Read-only** — возвращает план, главный session раздаёт worker'ам. |
+
+### Routing rules
+
+- **Тривиальная задача** (typo, rename, обновить one-liner) — main session сам, без делегирования
+- **Single-domain task с чёткими шагами** → один соответствующий worker через `Agent(subagent_type="backend-engineer", ...)`
+- **Нечёткая задача / cross-domain (2+ слоя)** → **сначала** `tech-analyst` → план → main session раздаёт worker'ам по плану
+- **Pure exploration** (поиск файлов / понимание структуры) — встроенный `Explore` (Haiku, дёшево)
+- **Crisis fix** (горящий prod баг) — пропускаешь tech-analyst, идёшь напрямую к worker'у
+
+### Cross-domain pattern (рекомендуемый)
+
+Для задач затрагивающих 2+ слоя:
+
+```
+User request
+  ↓
+tech-analyst → структурированный план: Шаг 1 (database-expert) → Шаг 2 (backend-engineer) → Шаг 3 (frontend-engineer)
+  ↓
+Main session (ты) показывает план пользователю → получает approval
+  ↓
+Main session запускает worker'ов в order'е (по dependencies)
+  ↓
+Каждый worker возвращает summary → main session собирает в финальный отчёт
+```
+
+### Что считается "max 4 worker agents"
+
+По best practices (Anthropic, community) — **больше 4 worker-агентов** снижает productivity (классификация "кто что делает" становится сложнее). У нас 4 worker'а + analyst/planner — последний не считается worker'ом (read-only, не пишет код), а оркестратором.
+
+### Subagents не могут спавнить друг друга
+
+Только main session может вызывать subagents через `Agent` tool. Если worker обнаружил что нужна работа из чужого scope — возвращает control в main session, main делегирует следующему.
+
 ## When working on a task
 
 ### 1. Understand context — ВСЕГДА vault-first