feat(claude): add 4 workers + tech-analyst subagents

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
This commit is contained in:
lekss361 2026-05-11 14:36:34 +03:00
parent b19ca1ed41
commit 5b741578e6

View file

@ -247,6 +247,60 @@ GitHub Actions:
Sentry release tracking: `SENTRY_RELEASE=$IMAGE_TAG` пишется в `backend/.env.runtime` на VPS через `sed` (НЕ полная перезапись файла — там user-managed `COUCHDB_PASSWORD` и пр.). 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 ## When working on a task
### 1. Understand context — ВСЕГДА vault-first ### 1. Understand context — ВСЕГДА vault-first