docs(claude): add code-reviewer agent — review workflow before push

This commit is contained in:
lekss361 2026-05-11 23:44:32 +03:00
parent 13119f9cb5
commit 053ce29a40

View file

@ -249,7 +249,7 @@ Sentry release tracking: `SENTRY_RELEASE=$IMAGE_TAG` пишется в `backend/
## Specialized subagents ## Specialized subagents
В `.claude/agents/` лежит 5 subagent'ов — 4 worker'a + 1 analyst/planner. Каждый имеет: В `.claude/agents/` лежит 6 subagent'ов — 4 worker'a + 2 read-only (analyst, reviewer). Каждый имеет:
- Свой context window (не засоряет main session) - Свой context window (не засоряет main session)
- Restricted tool set (не делает что-то вне его scope) - Restricted tool set (не делает что-то вне его scope)
- Pre-loaded knowledge о доменных конвенциях - Pre-loaded knowledge о доменных конвенциях
@ -263,19 +263,21 @@ Sentry release tracking: `SENTRY_RELEASE=$IMAGE_TAG` пишется в `backend/
| **devops-engineer** (orange) | `docker-compose*.yml`, `Caddyfile`, `.github/workflows/`, deploy issues, SSH operations | | **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 | | **database-expert** (purple) | `data/sql/NN_*.sql` migrations, Alembic, EXPLAIN ANALYZE, index design, schema changes |
### Analyst (1) — планирует, не пишет ### Read-only (2) — не пишут код
| Agent | Когда использовать | | Agent | Когда использовать |
|---|---| |---|---|
| **tech-analyst** (yellow) | Нечёткий запрос ("надо ускорить", "что чинить дальше"), cross-domain задачи (2+ слоя), рефакторинг-разборы, аудит. **Read-only** — возвращает план, главный session раздаёт worker'ам. | | **tech-analyst** (yellow) | Нечёткий запрос ("надо ускорить", "что чинить дальше"), cross-domain задачи (2+ слоя), рефакторинг-разборы, аудит. Возвращает план, main session раздаёт worker'ам. |
| **code-reviewer** (red) | Review ПОСЛЕ worker'а ДО `git push`. Проверяет: security (secrets, SQL injection, auth bypass), correctness (edge cases, transactions, idempotency), performance (N+1, индексы, re-renders), conventions (ruff/prettier/CLAUDE.md), arch (DRY, dead code). Возвращает verdict ✅/⚠️/❌. |
### Routing rules ### Routing rules
- **Тривиальная задача** (typo, rename, обновить one-liner) — main session сам, без делегирования - **Тривиальная задача** (typo, rename, обновить one-liner) — main session сам, без делегирования
- **Single-domain task с чёткими шагами** → один соответствующий worker через `Agent(subagent_type="backend-engineer", ...)` - **Single-domain task с чёткими шагами** → один соответствующий worker через `Agent(subagent_type="backend-engineer", ...)`
- **Нечёткая задача / cross-domain (2+ слоя)****сначала** `tech-analyst` → план → main session раздаёт worker'ам по плану - **Нечёткая задача / cross-domain (2+ слоя)****сначала** `tech-analyst` → план → main session раздаёт worker'ам по плану
- **После worker'а перед push критичных изменений**`code-reviewer` → если ❌ блок → вернуть worker'у. Опционально для тривиальных.
- **Pure exploration** (поиск файлов / понимание структуры) — встроенный `Explore` (Haiku, дёшево) - **Pure exploration** (поиск файлов / понимание структуры) — встроенный `Explore` (Haiku, дёшево)
- **Crisis fix** (горящий prod баг) — пропускаешь tech-analyst, идёшь напрямую к worker'у - **Crisis fix** (горящий prod баг) — пропускаешь tech-analyst и code-reviewer, идёшь напрямую к worker'у
### Cross-domain pattern (рекомендуемый) ### Cross-domain pattern (рекомендуемый)
@ -295,7 +297,34 @@ Main session запускает worker'ов в order'е (по dependencies)
### Что считается "max 4 worker agents" ### Что считается "max 4 worker agents"
По best practices (Anthropic, community) — **больше 4 worker-агентов** снижает productivity (классификация "кто что делает" становится сложнее). У нас 4 worker'а + analyst/planner — последний не считается worker'ом (read-only, не пишет код), а оркестратором. По best practices (Anthropic, community) — **больше 4 worker-агентов** снижает productivity (классификация "кто что делает" становится сложнее). У нас 4 worker'а + 2 read-only (tech-analyst планирует, code-reviewer проверяет) — read-only не считаются worker'ами.
### Code-reviewer workflow
```
User request → tech-analyst (если cross-domain)
Worker (backend/frontend/devops/database) пишет код
**code-reviewer** проверяет staged changes:
• ✅ APPROVE → main session коммитит + пушит
• ⚠️ MINOR → main session решает (или пускает, или возвращает worker'у)
• ❌ MAJOR → BLOCK push, возвращает worker'у на исправление
Loop until ✅ → git push origin HEAD:main
```
Используй code-reviewer для:
- Backend endpoints (auth, SQL injection vector)
- DB migrations (idempotency, индексы)
- Production deploys (compose changes, secrets)
- Изменения в job_settings / async tasks (race conditions)
Можно пропустить для:
- UI-only style/cosmetic
- Documentation
- Frontend type tweaks
- Trivial fixes (typo, rename)
### Subagents не могут спавнить друг друга ### Subagents не могут спавнить друг друга