Подробный обзор основных агентов: 9 специализированных субагентов

Что вы сможете делать после изучения

Понимать обязанности и сценарии использования 9 специализированных агентов
Знать, какого агента вызывать для различных задач разработки
Освоить способы взаимодействия агентов для построения эффективного рабочего процесса
Избегать ограничений «универсального ИИ», используя специализированных агентов для повышения эффективности

Ваша текущая ситуация

Часто поручаете Claude задачи, но получаете недостаточно профессиональные или глубокие ответы
Не уверены, когда использовать команды /plan, /tdd, /code-review и другие
Считаете, что советы ИИ слишком общие и не хватает конкретики
Хотите систематизированный рабочий процесс разработки, но не знаете, как его организовать

Когда использовать этот подход

Этот урок поможет вам при выполнении следующих задач:

Планирование перед разработкой сложных функций
Написание новых функций или исправление багов
Ревью кода и аудит безопасности
Исправление ошибок сборки
Сквозное тестирование
Рефакторинг и очистка кода
Обновление документации

Основная идея

Everything Claude Code предоставляет 9 специализированных агентов, каждый из которых фокусируется на определённой области. Как в реальной команде вы обращаетесь к разным экспертам, так и для разных задач разработки следует вызывать разных агентов.

Агент vs Команда

Агент: специализированный ИИ-помощник с экспертными знаниями и инструментами в определённой области
Команда: быстрый способ вызова агента или выполнения определённой операции

Например: команда /tdd вызывает агента tdd-guide для выполнения процесса разработки через тестирование.

Обзор 9 агентов

Агент	Роль	Типичный сценарий	Ключевые возможности
planner	Эксперт по планированию	Составление плана перед разработкой сложных функций	Анализ требований, обзор архитектуры, декомпозиция шагов
architect	Архитектор	Проектирование системы и технические решения	Оценка архитектуры, рекомендации паттернов, анализ компромиссов
tdd-guide	Наставник по TDD	Написание тестов и реализация функций	Процесс Red-Green-Refactor, обеспечение покрытия
code-reviewer	Ревьюер кода	Проверка качества кода	Проверка качества, безопасности, поддерживаемости
security-reviewer	Аудитор безопасности	Обнаружение уязвимостей	OWASP Top 10, утечка ключей, защита от инъекций
build-error-resolver	Специалист по ошибкам сборки	Исправление TypeScript/ошибок сборки	Минимальные исправления, вывод типов
e2e-runner	Эксперт по E2E-тестированию	Управление сквозным тестированием	Тесты Playwright, управление нестабильными тестами, артефакты
refactor-cleaner	Специалист по рефакторингу	Удаление мёртвого и дублирующегося кода	Анализ зависимостей, безопасное удаление, документирование
doc-updater	Специалист по документации	Генерация и обновление документации	Генерация codemap, AST-анализ

Подробное описание

1. Planner — Эксперт по планированию

Когда использовать: при реализации сложных функций, изменении архитектуры или крупном рефакторинге.

Лучшая практика

Перед написанием кода используйте /plan для создания плана реализации. Это поможет избежать пропуска зависимостей, выявить потенциальные риски и определить правильный порядок реализации.

Ключевые возможности:

Анализ и уточнение требований
Обзор архитектуры и выявление зависимостей
Детальная декомпозиция шагов реализации
Выявление рисков и планы их снижения
Планирование стратегии тестирования

Формат вывода:

markdown

# Implementation Plan: [Feature Name]

## Overview
[2-3 предложения с кратким описанием]

## Requirements
- [Requirement 1]
- [Requirement 2]

## Architecture Changes
- [Change 1: путь к файлу и описание]
- [Change 2: путь к файлу и описание]

## Implementation Steps

### Phase 1: [Phase Name]
1. **[Step Name]** (File: path/to/file.ts)
   - Action: конкретное действие
   - Why: причина
   - Dependencies: None / Requires step X
   - Risk: Low/Medium/High

## Testing Strategy
- Unit tests: [файлы для тестирования]
- Integration tests: [процессы для тестирования]
- E2E tests: [пользовательские сценарии для тестирования]

## Risks & Mitigations
- **Risk**: [описание]
  - Mitigation: [способ решения]

## Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2

Примеры сценариев:

Добавление нового API-эндпоинта (требуется миграция БД, обновление кэша, документация)
Рефакторинг основного модуля (затрагивает множество зависимостей)
Добавление новой функции (включает фронтенд, бэкенд, базу данных)

2. Architect — Архитектор

Когда использовать: при проектировании архитектуры системы, оценке технических решений, принятии архитектурных решений.

Ключевые возможности:

Проектирование архитектуры системы
Анализ технических компромиссов
Рекомендации паттернов проектирования
Планирование масштабируемости
Учёт безопасности

Архитектурные принципы:

Модульность: единая ответственность, высокая связность, низкая связанность
Масштабируемость: горизонтальное масштабирование, stateless-дизайн
Поддерживаемость: чёткая структура, единообразные паттерны
Безопасность: глубокая защита, минимальные привилегии
Производительность: эффективные алгоритмы, минимум сетевых запросов

Распространённые паттерны:

Паттерны фронтенда:

Композиция компонентов, паттерн Container/Presenter, кастомные хуки, глобальное состояние через Context, разделение кода

Паттерны бэкенда:

Паттерн Repository, сервисный слой, паттерн Middleware, событийно-ориентированная архитектура, CQRS

Паттерны данных:

Нормализация БД, денормализация для производительности чтения, Event Sourcing, слой кэширования, eventual consistency

Формат Architecture Decision Record (ADR):

markdown

# ADR-001: Использование Redis для хранения векторов семантического поиска

## Context
Необходимо хранить и запрашивать 1536-мерные векторы эмбеддингов для семантического поиска по рынкам.

## Decision
Использовать функцию векторного поиска Redis Stack.

## Consequences

### Positive
- Быстрый поиск по векторной схожести (<10мс)
- Встроенный алгоритм KNN
- Простое развёртывание
- Хорошая производительность (до 10K векторов)

### Negative
- Хранение в памяти (высокая стоимость для больших наборов данных)
- Единая точка отказа (без кластера)
- Поддержка только косинусного сходства

### Alternatives Considered
- **PostgreSQL pgvector**: медленнее, но с персистентным хранением
- **Pinecone**: управляемый сервис, выше стоимость
- **Weaviate**: больше функций, сложнее настройка

## Status
Accepted

## Date
2025-01-15

3. TDD Guide — Наставник по TDD

Когда использовать: при написании новых функций, исправлении багов, рефакторинге кода.

Основной принцип

TDD Guide требует, чтобы весь код сначала покрывался тестами, а затем реализовывался, обеспечивая покрытие тестами 80%+.

Рабочий процесс TDD:

Шаг 1: Сначала пишем тест (RED)

typescript

describe('searchMarkets', () => {
  it('returns semantically similar markets', async () => {
    const results = await searchMarkets('election')

    expect(results).toHaveLength(5)
    expect(results[0].name).toContain('Trump')
    expect(results[1].name).toContain('Biden')
  })
})

Шаг 2: Запускаем тест (проверяем, что он падает)

bash

npm test
# Тест должен упасть — мы ещё не реализовали функцию

Шаг 3: Пишем минимальную реализацию (GREEN)

typescript

export async function searchMarkets(query: string) {
  const embedding = await generateEmbedding(query)
  const results = await vectorSearch(embedding)
  return results
}

Шаг 4: Запускаем тест (проверяем, что он проходит)

bash

npm test
# Теперь тест должен пройти

Шаг 5: Рефакторинг (IMPROVE)

Удаляем дублирующийся код
Улучшаем именование
Оптимизируем производительность
Повышаем читаемость

Шаг 6: Проверяем покрытие

bash

npm run test:coverage
# Проверяем покрытие 80%+

Обязательные типы тестов:

Модульные тесты (обязательно): тестирование отдельных функций
Интеграционные тесты (о��язательно): тестирование API-эндпоинтов и операций с БД
E2E-тесты (для критичных процессов): тестирование полных пользовательских сценариев

Обязательные граничные случаи:

Null/Undefined: что если входные данные null?
Пустые значения: что если массив/строка пустые?
Неверные типы: что если передан неправильный тип?
Границы: минимальные/максимальные значения
Ошибки: сетевые сбои, ошибки БД
Состояния гонки: параллельные операции
Большие данные: производительность на 10k+ элементах
Специальные символы: Unicode, эмодзи, SQL-символы

4. Code Reviewer — Ревьюер кода

Когда использовать: сразу после написания или изменения кода.

Обязательное использование

Code Reviewer — обязательный агент, все изменения кода должны проходить через его проверку.

Чек-лист проверки:

Проверки безопасности (CRITICAL):

Захардкоженные учётные данные (API-ключи, пароли, токены)
Риск SQL-инъекций (конкатенация строк в запросах)
XSS-уязвимости (неэкранированный пользовательский ввод)
Отсутствие валидации ввода
Небезопасные зависимости (устаревшие, с уязвимостями)
Риск обхода путей (пути к файлам, контролируемые пользователем)
CSRF-уязвимости
Обход аутентификации

Качество кода (HIGH):

Большие функции (>50 строк)
Большие файлы (>800 строк)
Глубокая вложенность (>4 уровней)
Отсутствие обработки ошибок (try/catch)
Операторы console.log
Изменённые паттерны
Новый код без тестов

Производительность (MEDIUM):

Неэффективные алгоритмы (O(n²) когда возможен O(n log n))
Ненужные перерисовки в React
Отсутствие мемоизации
Большой размер бандла
Неоптимизированные изображения
Отсутствие кэширования
N+1 запросы

Лучшие практики (MEDIUM):

Эмодзи в коде/комментариях
TODO/FIXME без связанного тикета
Отсутствие JSDoc для публичных API
Проблемы доступности (отсутствие ARIA-меток, плохой контраст)
Плохие имена переменных (x, tmp, data)
Необъяснённые магические числа
Непоследовательное форматирование

Формат вывода проверки:

markdown

[CRITICAL] Hardcoded API key
File: src/api/client.ts:42
Issue: API key exposed in source code
Fix: Move to environment variable

const apiKey = "sk-abc123";  // ❌ Bad
const apiKey = process.env.API_KEY;  // ✓ Good

Критерии одобрения:

✅ Одобрено: нет CRITICAL или HIGH проблем
⚠️ Предупреждение: только MEDIUM проблемы (можно осторожно мержить)
❌ Блокировка: обнаружены CRITICAL или HIGH проблемы

5. Security Reviewer — Аудитор безопасности

Когда использовать: после написания кода, обрабатывающего пользовательский ввод, аутентификацию, API-эндпоинты или конфиденциальные данные.

Критически важно

Security Reviewer отмечает утечки ключей, SSRF, инъекции, небезопасное шифрование и уязвимости OWASP Top 10. При обнаружении CRITICAL проблем требуется немедленное исправление!

Основные обязанности:

Обнаружение уязвимостей: выявление OWASP Top 10 и распространённых проблем безопасности
Обнаружение ключей: поиск захардкоженных API-ключей, паролей, токенов
Валидация ввода: проверка надлежащей санитизации всего пользовательского ввода
Аутентификация/авторизация: проверка правильного контроля доступа
Безопасность зависимостей: проверка npm-пакетов на уязвимости
Лучшие практики безопасности: обеспечение безопасных паттернов кодирования

Проверки OWASP Top 10:

Инъекции (SQL, NoSQL, Command)
- Параметризованы ли запросы?
- Санитизирован ли пользовательский ввод?
- Безопасно ли используется ORM?
Нарушенная аутентификация
- Хешируются ли пароли (bcrypt, argon2)?
- Правильно ли валидируются JWT?
- Безопасны ли сессии?
- Есть ли MFA?
Раскрытие конфиденциальных данных
- Принудительно ли используется HTTPS?
- Хранятся ли ключи в переменных окружения?
- Шифруются ли PII в состоянии покоя?
- Санитизируются ли логи?
XML External Entity (XXE)
- Безопасно ли настроен XML-парсер?
- Отключена ли обработка внешних сущностей?
Нарушенный контроль доступа
- Проверяется ли авторизация на каждом маршруте?
- Являются ли ссылки на объекты косвенными?
- Правильно ли настроен CORS?
Неправильная конфигурация безопасности
- Изменены ли учётные данные по умолчанию?
- Безопасна ли обработка ошибок?
- Установлены ли заголовки безопасности?
- Отключен ли режим отладки в продакшене?
Межсайтовый скриптинг (XSS)
- Экранируется/санитизируется ли вывод?
- Установлен ли Content-Security-Policy?
- Экранирует ли фреймворк по умолчанию?
Небезопасная десериализация
- Безопасно ли десериализуется пользовательский ввод?
- Актуальны ли библиотеки десериализации?
Использование компонентов с известными уязвимостями
- Актуальны ли все зависимости?
- Чист ли npm audit?
- Мониторятся ли CVE?
Недостаточное логирование и мониторинг
- Логируются ли события безопасности?
- Мониторятся ли логи?
- Настроены ли оповещения?

Распространённые паттерны уязвимостей:

1. Захардкоженные секреты (CRITICAL)

javascript

// ❌ CRITICAL: Hardcoded secrets
const apiKey = "sk-proj-xxxxx"

// ✅ CORRECT: Environment variables
const apiKey = process.env.OPENAI_API_KEY
if (!apiKey) {
  throw new Error('OPENAI_API_KEY not configured')
}

2. SQL-инъекция (CRITICAL)

javascript

// ❌ CRITICAL: SQL injection vulnerability
const query = `SELECT * FROM users WHERE id = ${userId}`

// ✅ CORRECT: Parameterized queries
const { data } = await supabase
  .from('users')
  .select('*')
  .eq('id', userId)

3. XSS (HIGH)

javascript

// ❌ HIGH: XSS vulnerability
element.innerHTML = userInput

// ✅ CORRECT: Use textContent or sanitize
element.textContent = userInput

Формат отчёта по безопасности:

markdown

# Security Review Report

**File/Component:** [path/to/file.ts]
**Reviewed:** YYYY-MM-DD
**Reviewer:** security-reviewer agent

## Summary
- **Critical Issues:** X
- **High Issues:** Y
- **Medium Issues:** Z
- **Low Issues:** W
- **Risk Level:** 🔴 HIGH / 🟡 MEDIUM / 🟢 LOW

## Critical Issues (Fix Immediately)

### 1. [Issue Title]
**Severity:** CRITICAL
**Category:** SQL Injection / XSS / Authentication / etc.
**Location:** `file.ts:123`

**Issue:**
[Описание уязвимости]

**Impact:**
[Что произойдёт при эксплуатации]

**Proof of Concept:**
```javascript
// Пример эксплуатации

Remediation:

javascript

// ✅ Безопасная реализация

References:

OWASP: [link]
CWE: [number]


### 6. Build Error Resolver — Специалист по ошибкам сборки

**Когда использовать**: при сбое сборки или появлении ошибок типов.

::: tip Минимальные исправления
Основной принцип Build Error Resolver — **минимальные исправления**: только исправление ошибок, без архитектурных изменений или рефакторинга.
:::

**Основные обязанности**:
1. **Исправление ошибок TypeScript**: исправление ошибок типов, проблем вывода, ограничений дженериков
2. **Исправление ошибок сборки**: решение проблем компиляции, разрешения модулей
3. **Проблемы зависимостей**: исправление ошибок импорта, отсутствующих пакетов, конфликтов версий
4. **Ошибки конфигурации**: решение проблем tsconfig.json, webpack, Next.js
5. **Минимальные изменения**: внесение минимально возможных изменений для исправления ошибки
6. **Без архитектурных изменений**: только исправление ошибок, без рефакторинга или редизайна

**Диагностические команды**:
```bash
# Проверка типов TypeScript (без вывода)
npx tsc --noEmit

# TypeScript с красивым выводом
npx tsc --noEmit --pretty

# Показать все ошибки (не останавливаться на первой)
npx tsc --noEmit --pretty --incremental false

# Проверить конкретный файл
npx tsc --noEmit path/to/file.ts

# Проверка ESLint
npx eslint . --ext .ts,.tsx,.js,.jsx

# Сборка Next.js (продакшен)
npm run build

Процесс исправления ошибок:

1. Сбор всех ошибок

a) Запустить полную проверку типов
   - npx tsc --noEmit --pretty
   - Собрать ВСЕ ошибки, не только первую

b) Классифицировать ошибки по типу
   - Сбой вывода типов
   - Отсутствующие определения типов
   - Ошибки импорта/экспорта
   - Ошибки конфигурации
   - Проблемы зависимостей

c) Приоритизировать по влиянию
   - Блокируют сборку: исправить первыми
   - Ошибки типов: исправлять по порядку
   - Предупреждения: исправить при наличии времени

2. Стратегия исправления (минимальные изменения)

Для каждой ошибки:

1. Понять ошибку
   - Внимательно прочитать сообщение об ошибке
   - Проверить файл и номер строки
   - Понять ожидаемый vs фактический тип

2. Найти минимальное исправление
   - Добавить недостающие аннотации типов
   - Исправить операторы импорта
   - Добавить проверки на null
   - Использовать приведение типов (в крайнем случае)

3. Проверить, что исправление не ломает другой код
   - Запустить tsc после каждого исправления
   - Проверить связанные файлы
   - Убедиться, что не появились новые ошибки

4. Итерировать до успешной сборки
   - Исправлять по одной ошибке за раз
   - Перекомпилировать после каждого исправления
   - Отслеживать прогресс (X/Y ошибок исправлено)

Распространённые паттерны ошибок и исправления:

Паттерн 1: Сбой вывода типов

typescript

// ❌ ERROR: Parameter 'x' implicitly has an 'any' type
function add(x, y) {
  return x + y
}

// ✅ FIX: Add type annotations
function add(x: number, y: number): number {
  return x + y
}

Паттерн 2: Ошибки Null/Undefined

typescript

// ❌ ERROR: Object is possibly 'undefined'
const name = user.name.toUpperCase()

// ✅ FIX: Optional chaining
const name = user?.name?.toUpperCase()

// ✅ OR: Null check
const name = user && user.name ? user.name.toUpperCase() : ''

Паттерн 3: Ошибки импорта

typescript

// ❌ ERROR: Cannot find module '@/lib/utils'
import { formatDate } from '@/lib/utils'

// ✅ FIX 1: Проверить правильность paths в tsconfig
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

// ✅ FIX 2: Использовать относительный импорт
import { formatDate } from '../lib/utils'

Стратегия минимальных изменений:

КРИТИЧЕСКИ ВАЖНО: вносить минимально возможные изменения

ДЕЛАТЬ: ✅ Добавлять недостающие аннотации типов ✅ Добавлять необходимые проверки на null ✅ Исправлять импорт/экспорт ✅ Добавлять недостающие зависимости ✅ Обновлять определения типов ✅ Исправлять конфигурационные файлы

НЕ ДЕЛАТЬ: ❌ Рефакторить несвязанный код ❌ Менять архитектуру ❌ Переименовывать переменные/функции (если это не причина ошибки) ❌ Добавлять новую функциональность ❌ Менять логику потока (если это не исправление ошибки) ❌ Оптимизировать производительность ❌ Улучшать стиль кода

7. E2E Runner — Эксперт по E2E-тестированию

Когда использовать: при необходимости генерации, поддержки и запуска E2E-тестов.

Ценность сквозного тестирования

E2E-тесты — последняя линия защиты перед продакшеном, они выявляют интеграционные проблемы, которые пропускают модульные тесты.

Основные обязанности:

Создание тестовых сценариев: написание Playwright-тестов для пользовательских процессов
Поддержка тестов: синхронизация тестов с изменениями UI
Управление нестабильными тестами: выявление и изоляция flaky-тестов
Управление артефактами: сбор скриншотов, видео, трейсов
Интеграция CI/CD: обеспечение надёжной работы тестов в пайплайне
Отчётность: генерация HTML-отчётов и JUnit XML

Команды тестирования:

bash

# Запуск всех E2E-тестов
npx playwright test

# Запуск конкретного тестового файла
npx playwright test tests/markets.spec.ts

# Запуск тестов в headed-режиме (видно браузер)
npx playwright test --headed

# Отладка тестов с инспектором
npx playwright test --debug

# Генерация тестового кода из действий в браузере
npx playwright codegen http://localhost:3000

# Запуск тестов с трейсом
npx playwright test --trace on

# Показать HTML-отчёт
npx playwright show-report

# Обновить снапшоты
npx playwright test --update-snapshots

# Запуск тестов в конкретном браузере
npx playwright test --project=chromium
npx playwright test --project=firefox
npx playwright test --project=webkit

Рабочий процесс E2E-тестирования:

1. Этап планирования тестов

a) Определить ключевые пользовательские сценарии
   - Процессы аутентификации (вход, выход, регистрация)
   - Основная функциональность (создание рынка, торговля, поиск)
   - Платёжные процессы (депозит, вывод)
   - Целостность данных (CRUD-операции)

b) Определить тестовые сценарии
   - Happy path (всё работает нормально)
   - Граничные случаи (пустые состояния, лимиты)
   - Случаи ошибок (сетевые сбои, валидация)

c) Приоритизировать по риску
   - HIGH: финансовые транзакции, аутентификация
   - MEDIUM: поиск, фильтрация, навигация
   - LOW: UI-полировка, анимации, стили

2. Этап создания тестов

Для каждого пользовательского сценария:

1. Написать тест в Playwright
   - Использовать паттерн Page Object Model (POM)
   - Добавить осмысленные описания тестов
   - Добавить утверждения на ключевых шагах
   - Добавить скриншоты в критических точках

2. Сделать тест устойчивым
   - Использовать подходящие локаторы (приоритет data-testid)
   - Добавить ожидание динамического контента
   - Обработать состояния гонки
   - Реализовать логику повторных попыток

3. Добавить сбор артефактов
   - Скриншоты при сбое
   - Запись видео
   - Трейсы для отладки
   - Сетевые логи при необходимости

Структура Playwright-тестов:

Организация тестовых файлов:

tests/
├── e2e/                       # Сквозные пользовательские сценарии
│   ├── auth/                  # Процессы аутентификации
│   │   ├── login.spec.ts
│   │   ├── logout.spec.ts
│   │   └── register.spec.ts
│   ├── markets/               # Функциональность рынков
│   │   ├── browse.spec.ts
│   │   ├── search.spec.ts
│   │   ├── create.spec.ts
│   │   └── trade.spec.ts
│   ├── wallet/                # Операции с кошельком
│   │   ├── connect.spec.ts
│   │   └── transactions.spec.ts
│   └── api/                   # Тесты API-эндпоинтов
│       ├── markets-api.spec.ts
│       └── search-api.spec.ts
├── fixtures/                  # Тестовые данные и утилиты
│   ├── auth.ts                # Фикстуры аутентификации
│   ├── markets.ts             # Тестовые данные рынков
│   └── wallets.ts             # Фикстуры кошельков
└── playwright.config.ts       # Конфигурация Playwright

Паттерн Page Object Model:

typescript

// pages/MarketsPage.ts
import { Page, Locator } from '@playwright/test'

export class MarketsPage {
  readonly page: Page
  readonly searchInput: Locator
  readonly marketCards: Locator
  readonly createMarketButton: Locator
  readonly filterDropdown: Locator

  constructor(page: Page) {
    this.page = page
    this.searchInput = page.locator('[data-testid="search-input"]')
    this.marketCards = page.locator('[data-testid="market-card"]')
    this.createMarketButton = page.locator('[data-testid="create-market-btn"]')
    this.filterDropdown = page.locator('[data-testid="filter-dropdown"]')
  }

  async goto() {
    await this.page.goto('/markets')
    await this.page.waitForLoadState('networkidle')
  }

  async searchMarkets(query: string) {
    await this.searchInput.fill(query)
    await this.page.waitForResponse(resp => resp.url().includes('/api/markets/search'))
    await this.page.waitForLoadState('networkidle')
  }

  async getMarketCount() {
    return await this.marketCards.count()
  }

  async clickMarket(index: number) {
    await this.marketCards.nth(index).click()
  }

  async filterByStatus(status: string) {
    await this.filterDropdown.selectOption(status)
    await this.page.waitForLoadState('networkidle')
  }
}

Пример теста с лучшими практиками:

typescript

// tests/e2e/markets/search.spec.ts
import { test, expect } from '@playwright/test'
import { MarketsPage } from '../../pages/MarketsPage'

test.describe('Market Search', () => {
  let marketsPage: MarketsPage

  test.beforeEach(async ({ page }) => {
    marketsPage = new MarketsPage(page)
    await marketsPage.goto()
  })

  test('should search markets by keyword', async ({ page }) => {
    // Arrange
    await expect(page).toHaveTitle(/Markets/)

    // Act
    await marketsPage.searchMarkets('trump')

    // Assert
    const marketCount = await marketsPage.getMarketCount()
    expect(marketCount).toBeGreaterThan(0)

    // Verify first result contains search term
    const firstMarket = marketsPage.marketCards.first()
    await expect(firstMarket).toContainText(/trump/i)

    // Take screenshot for verification
    await page.screenshot({ path: 'artifacts/search-results.png' })
  })

  test('should handle no results gracefully', async ({ page }) => {
    // Act
    await marketsPage.searchMarkets('xyznonexistentmarket123')

    // Assert
    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
    const marketCount = await marketsPage.getMarketCount()
    expect(marketCount).toBe(0)
  })
})

Управление нестабильными тестами:

Выявление flaky-тестов:

bash

# Многократный запуск теста для проверки стабильности
npx playwright test tests/markets/search.spec.ts --repeat-each=10

# Запуск конкретного теста с повторными попытками
npx playwright test tests/markets/search.spec.ts --retries=3

Режим изоляции:

typescript

// Пометить flaky-тест для изоляции
test('flaky: market search with complex query', async ({ page }) => {
  test.fixme(true, 'Test is flaky - Issue #123')

  // Код теста здесь...
})

// Или использовать условный пропуск
test('market search with complex query', async ({ page }) => {
  test.skip(process.env.CI, 'Test is flaky in CI - Issue #123')

  // Код теста здесь...
})

Распространённые причины нестабильности и исправления:

1. Состояния гонки

typescript

// ❌ FLAKY: Don't assume element is ready
await page.click('[data-testid="button"]')

// ✅ STABLE: Wait for element to be ready
await page.locator('[data-testid="button"]').click() // Built-in auto-wait

2. Тайминг сети

typescript

// ❌ FLAKY: Arbitrary timeout
await page.waitForTimeout(5000)

// ✅ STABLE: Wait for specific condition
await page.waitForResponse(resp => resp.url().includes('/api/markets'))

3. Тайминг анимаций

typescript

// ❌ FLAKY: Click during animation
await page.click('[data-testid="menu-item"]')

// ✅ STABLE: Wait for animation to complete
await page.locator('[data-testid="menu-item"]').waitFor({ state: 'visible' })
await page.waitForLoadState('networkidle')
await page.click('[data-testid="menu-item"]')

8. Refactor Cleaner — Специалист по рефакторингу

Когда использовать: при необходимости удаления неиспользуемого кода, дублирующегося кода и проведения рефакторинга.

Осторожность

Refactor Cleaner запускает инструменты анализа (knip, depcheck, ts-prune) для выявления мёртвого кода и безопасного удаления. Перед удалением обязательно проведите тщательную проверку!

Основные обязанности:

Обнаружение мёртвого кода: поиск неиспользуемого кода, экспортов, зависимостей
Устранение дублирования: выявление и объединение дублирующегося кода
Очистка зависимостей: удаление неиспользуемых пакетов и импортов
Безопасный рефакторинг: обеспечение того, что изменения не нарушают функциональность
Документирование: отслеживание всех удалений в DELETION_LOG.md

Инструменты обнаружения:

knip: поиск неиспользуемых файлов, экспортов, зависимостей, типов
depcheck: выявление неиспользуемых npm-зависимостей
ts-prune: поиск неиспользуемых TypeScript-экспортов
eslint: проверка неиспользуемых disable-директив и переменных

Команды анализа:

bash

# Запуск knip для поиска неиспользуемых экспортов/файлов/зависимостей
npx knip

# Проверка неиспользуемых зависимостей
npx depcheck

# Поиск неиспользуемых TypeScript-экспортов
npx ts-prune

# Проверка неиспользуемых disable-директив
npx eslint . --report-unused-disable-directives

Рабочий процесс рефакторинга:

1. Этап анализа

a) Параллельный запуск инструментов обнаружения
b) Сбор всех находок
c) Классификация по уровню риска:
   - SAFE: неиспользуемые экспорты, неиспользуемые зависимости
   - CAREFUL: возможно используется через динамический импорт
   - RISKY: публичный API, общие утилиты

2. Оценка рисков

Для каждого элемента на удаление:
- Проверить, импортируется ли где-либо (grep-поиск)
- Проверить отсутствие динамических импортов (grep по строковым паттернам)
- Проверить, является ли частью публичного API
- Просмотреть историю для контекста
- Протестировать влияние на сборку/тесты

3. Процесс безопасного удаления

a) Начать только с SAFE элементов
b) Удалять по одной категории за раз:
   1. Неиспользуемые npm-зависимости
   2. Неиспользуемые внутренние экспорты
   3. Неиспользуемые файлы
   4. Дублирующийся код
c) Запускать тесты после каждой партии
d) Создавать git-коммит для каждой партии

4. Объединение дубликатов

a) Найти дублирующиеся компоненты/утилиты
b) Выбрать лучшую реализацию:
   - Наиболее полная функциональность
   - Лучше протестирована
   - Недавно использовалась
c) Обновить все импорты на выбранную версию
d) Удалить дубликаты
e) Проверить, что тесты проходят

Формат журнала удалений:

Создать/обновить docs/DELETION_LOG.md со следующей структурой:

markdown

# Code Deletion Log

## [YYYY-MM-DD] Refactor Session

### Unused Dependencies Removed
- package-name@version - Last used: never, Size: XX KB
- another-package@version - Replaced by: better-package

### Unused Files Deleted
- src/old-component.tsx - Replaced by: src/new-component.tsx
- lib/deprecated-util.ts - Functionality moved to: lib/utils.ts

### Duplicate Code Consolidated
- src/components/Button1.tsx + Button2.tsx → Button.tsx
- Reason: Both implementations were identical

### Unused Exports Removed
- src/utils/helpers.ts - Functions: foo(), bar()
- Reason: No references found in codebase

### Impact
- Files deleted: 15
- Dependencies removed: 5
- Lines of code removed: 2,300
- Bundle size reduction: ~45 KB

### Testing
- All unit tests passing: ✓
- All integration tests passing: ✓
- Manual testing completed: ✓

Чек-лист безопасности:

Перед удалением чего-либо:

[ ] Запустить инструменты обнаружения
[ ] Grep все ссылки
[ ] Проверить динамические импорты
[ ] Просмотреть историю
[ ] Проверить, является ли публичным API
[ ] Запустить все тесты
[ ] Создать резервную ветку
[ ] Задокументировать в DELETION_LOG.md

После каждого удаления:

[ ] Сборка успешна
[ ] Тесты проходят
[ ] Нет ошибок в консоли
[ ] Закоммитить изменения
[ ] Обновить DELETION_LOG.md

Распространённые паттерны для удаления:

1. Неиспользуемые импорты

typescript

// ❌ Remove unused imports
import { useState, useEffect, useMemo } from 'react' // Only useState used

// ✅ Keep only what's used
import { useState } from 'react'

2. Мёртвые ветки кода

typescript

// ❌ Remove unreachable code
if (false) {
  // This never executes
  doSomething()
}

// ❌ Remove unused functions
export function unusedHelper() {
  // No references in codebase
}

3. Дублирующиеся компоненты

typescript

// ❌ Multiple similar components
components/Button.tsx
components/PrimaryButton.tsx
components/NewButton.tsx

// ✅ Consolidate to one
components/Button.tsx (with variant prop)

9. Doc Updater — Специалист по документации

Когда использовать: при необходимости обновления codemaps и документации.

Синхронизация документации с кодом

Doc Updater запускает /update-codemaps и /update-docs, генерирует docs/CODEMAPS/*, обновляет README и руководства.

Основные обязанности:

Генерация Codemap: создание архитектурных карт из структуры кодовой базы
Обновление документации: обновление README и руководств из кода
AST-анализ: использование TypeScript Compiler API для понимания структуры
Маппинг зависимостей: отслеживание импортов/экспортов между модулями
Качество документации: обеспечение соответствия документации реальному коду

Инструменты анализа:

ts-morph: анализ и манипуляция TypeScript AST
TypeScript Compiler API: глубокий анализ структуры кода
madge: визуализация графа зависимостей
jsdoc-to-markdown: генерация документации из JSDoc-комментариев

Команды анализа:

bash

# Анализ структуры TypeScript-проекта (запуск кастомного скрипта с ts-morph)
npx tsx scripts/codemaps/generate.ts

# Генерация графа зависимостей
npx madge --image graph.svg src/

# Извлечение JSDoc-комментариев
npx jsdoc2md src/**/*.ts

Рабочий процесс генерации Codemap:

1. Анализ структуры репозитория

a) Определить все workspaces/packages
b) Построить карту структуры директорий
c) Найти точки входа (apps/*, packages/*, services/*)
d) Определить паттерны фреймворков (Next.js, Node.js и т.д.)

2. Анализ модулей

Для каждого модуля:
- Извлечь экспорты (публичный API)
- Построить карту импортов (зависимости)
- Определить маршруты (API-роуты, страницы)
- Найти модели БД (Supabase, Prisma)
- Найти модули очередей/воркеров

3. Генерация Codemaps

Структура:
docs/CODEMAPS/
├── INDEX.md              # Обзор всех областей
├── frontend.md           # Структура фронтенда
├── backend.md            # Структура Backend/API
├── database.md           # Схема базы данных
├── integrations.md       # Внешние сервисы
└── workers.md            # Фоновые задачи

Формат Codemap:

markdown

# [Area] Codemap

**Last Updated:** YYYY-MM-DD
**Entry Points:** список основных файлов

## Architecture

[ASCII-диаграмма связей компонентов]

## Key Modules

| Module | Purpose | Exports | Dependencies |
| --- | --- | --- | --- |
| ... | ... | ... | ... |

## Data Flow

[Описание потока данных в этой области]

## External Dependencies

- package-name - Назначение, Версия
- ...

## Related Areas

Ссылки на другие codemaps, взаимодействующие с этой областью

Рабочий процесс обновления документации:

1. Извлечение документации из кода

- Чтение JSDoc/TSDoc-комментариев
- Извлечение разделов README из package.json
- Парсинг переменных окружения из .env.example
- Сбор определений API-эндпоинтов

2. Обновление файлов документации

Файлы для обновления:
- README.md - Обзор проекта, инструкции по настройке
- docs/GUIDES/*.md - Руководства по функциям, туториалы
- package.json - Описание, документация скриптов
- API documentation - Спецификации эндпоинтов

3. Валидация документации

- Проверить существование всех упомянутых файлов
- Проверить валидность всех ссылок
- Убедиться, что примеры работают
- Проверить компиляцию фрагментов кода

Примеры проектных Codemaps:

Codemap фронтенда (docs/CODEMAPS/frontend.md):

markdown

# Frontend Architecture

**Last Updated:** YYYY-MM-DD
**Framework:** Next.js 15.1.4 (App Router)
**Entry Point:** website/src/app/layout.tsx

## Structure

website/src/
├── app/                # Next.js App Router
│   ├── api/           # API-роуты
│   ├── markets/       # Страницы рынков
│   ├── bot/           # Взаимодействие с ботом
│   └── creator-dashboard/
├── components/        # React-компоненты
├── hooks/             # Кастомные хуки
└── lib/               # Утилиты

## Key Components

| Component | Purpose | Location |
| --- | --- | --- |
| HeaderWallet | Wallet connection | components/HeaderWallet.tsx |
| MarketsClient | Markets listing | app/markets/MarketsClient.js |
| SemanticSearchBar | Search UI | components/SemanticSearchBar.js |

## Data Flow

User → Markets Page → API Route → Supabase → Redis (optional) → Response

## External Dependencies

- Next.js 15.1.4 - Framework
- React 19.0.0 - UI library
- Privy - Authentication
- Tailwind CSS 3.4.1 - Styling

Codemap бэкенда (docs/CODEMAPS/backend.md):

markdown

# Backend Architecture

**Last Updated:** YYYY-MM-DD
**Runtime:** Next.js API Routes
**Entry Point:** website/src/app/api/

## API Routes

| Route | Method | Purpose |
| --- | --- | --- |
| /api/markets | GET | List all markets |
| /api/markets/search | GET | Semantic search |
| /api/market/[slug] | GET | Single market |
| /api/market-price | GET | Real-time pricing |

## Data Flow

API Route → Supabase Query → Redis (cache) → Response

## External Services

- Supabase - PostgreSQL database
- Redis Stack - Vector search
- OpenAI - Embeddings

Шаблон обновления README:

При обновлении README.md:

markdown

# Project Name

Краткое описание

## Setup
\`\`\`bash
# Installation
npm install

# Environment variables
cp .env.example .env.local
# Fill in: OPENAI_API_KEY, REDIS_URL, etc.

# Development
npm run dev

# Build
npm run build
\`\`\`

## Architecture

See [docs/CODEMAPS/INDEX.md](docs/CODEMAPS/INDEX.md) for detailed architecture.

### Key Directories

- `src/app` - Next.js App Router страницы и API-роуты
- `src/components` - Переиспользуемые React-компоненты
- `src/lib` - Библиотеки утилит и клиенты

## Features

- [Feature 1] - Description
- [Feature 2] - Description

## Documentation

- [Setup Guide](docs/GUIDES/setup.md)
- [API Reference](docs/GUIDES/api.md)
- [Architecture](docs/CODEMAPS/INDEX.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

Какого агента вызывать

В зависимости от типа задачи выбирайте подходящего агента:

Тип задачи	Рекомендуемый вызов	Альтернатива
Планирование новой функции	`/plan` → planner agent	Ручной вызов planner agent
Проектирование архитектуры	Ручной вызов architect agent	`/orchestrate` → последовательный вызов агентов
Написание новой функции	`/tdd` → tdd-guide agent	planner → tdd-guide
Исправление бага	`/tdd` → tdd-guide agent	build-error-resolver (если ошибка типов)
Ревью кода	`/code-review` → code-reviewer agent	Ручной вызов code-reviewer agent
Аудит безопасности	Ручной вызов security-reviewer agent	code-reviewer (частичное покрытие)
Сбой сборки	`/build-fix` → build-error-resolver agent	Ручное исправление
E2E-тестирование	`/e2e` → e2e-runner agent	Ручное написание Playwright-тестов
Очистка мёртвого кода	`/refactor-clean` → refactor-cleaner agent	Ручное удаление
Обновление документации	`/update-docs` → doc-updater agent	`/update-codemaps` → doc-updater agent

Примеры взаимодействия агентов

Сценарий 1: Разработка новой функции с нуля

1. /plan (planner agent)
   - Создание плана реализации
   - Выявление зависимостей и рисков

2. /tdd (tdd-guide agent)
   - Написание тестов по плану
   - Реализация функции
   - Обеспечение покрытия

3. /code-review (code-reviewer agent)
   - Проверка качества кода
   - Проверка уязвимостей безопасности

4. /verify (команда)
   - Запуск сборки, проверки типов, тестов
   - Проверка console.log, статуса git

Сценарий 2: Исправление ошибок сборки

1. /build-fix (build-error-resolver agent)
   - Исправление ошибок TypeScript
   - Обеспечение успешной сборки

2. /test-coverage (команда)
   - Проверка достаточности покрытия

3. /code-review (code-reviewer agent)
   - Ревью исправленного кода

Сценарий 3: Очистка кода

1. /refactor-clean (refactor-cleaner agent)
   - Запуск инструментов обнаружения
   - Удаление мёртвого кода
   - Объединение дубликатов

2. /update-docs (doc-updater agent)
   - Обновление codemaps
   - Обновление документации

3. /verify (команда)
   - Запуск всех проверок

Резюме урока

Everything Claude Code предоставляет 9 специализированных агентов, каждый из которых фокусируется на определённой области:

planner — планирование сложных функций
architect — проектирование архитектуры системы
tdd-guide — выполнение TDD-процесса
code-reviewer — проверка качества кода
security-reviewer — обнаружение уязвимостей безопасности
build-error-resolver — исправление ошибок сборки
e2e-runner — управление сквозным тестированием
refactor-cleaner — очистка мёртвого кода
doc-updater — обновление документации и codemap

Основные принципы:

Выбирайте подходящего агента в зависимости от типа задачи
Используйте взаимодействие агентов для построения эффективного рабочего процесса
Сложные задачи могут требовать последовательного вызова нескольких агентов
После изменения кода обязательно проводите code review

Анонс следующего урока

В следующем уроке мы изучим Рабочий процесс TDD.
Вы узнаете:
Как использовать /plan для создания плана реализации
Как использовать /tdd для выполнения цикла Red-Green-Refactor
Как обеспечить покрытие тестами 80%+
Как использовать /verify для полной проверки

Приложение: Ссылки на исходный код

Нажмите, чтобы развернуть ссылки на исходный код

Последнее обновление: 2026-01-25

Функция	Путь к файлу	Строки
Planner Agent	agents/planner.md	1-120
Architect Agent	agents/architect.md	1-212
TDD Guide Agent	agents/tdd-guide.md	1-281
Code Reviewer Agent	agents/code-reviewer.md	1-105
Security Reviewer Agent	agents/security-reviewer.md	1-546
Build Error Resolver Agent	agents/build-error-resolver.md	1-533
E2E Runner Agent	agents/e2e-runner.md	1-709
Refactor Cleaner Agent	agents/refactor-cleaner.md	1-307
Doc Updater Agent	agents/doc-updater.md	1-453

Ключевые константы:

Нет

Ключевые функции:

Нет

Подробный обзор основных агентов: 9 специализированных субагентов ​

Что вы сможете делать после изучения ​

Ваша текущая ситуация ​

Когда использовать этот подход ​

Основная идея ​

Обзор 9 агентов ​

Подробное описание ​

1. Planner — Эксперт по планированию ​

2. Architect — Архитектор ​

3. TDD Guide — Наставник по TDD ​

4. Code Reviewer — Ревьюер кода ​

5. Security Reviewer — Аудитор безопасности ​

7. E2E Runner — Эксперт по E2E-тестированию ​

8. Refactor Cleaner — Специалист по рефакторингу ​

9. Doc Updater — Специалист по документации ​

Какого агента вызывать ​

Примеры взаимодействия агентов ​

Сценарий 1: Разработка новой функции с нуля ​

Сценарий 2: Исправление ошибок сборки ​

Сценарий 3: Очистка кода ​

Резюме урока ​

Анонс следующего урока ​

Приложение: Ссылки на исходный код ​

Подробный обзор основных агентов: 9 специализированных субагентов

Что вы сможете делать после изучения

Ваша текущая ситуация

Когда использовать этот подход

Основная идея

Обзор 9 агентов

Подробное описание

1. Planner — Эксперт по планированию

2. Architect — Архитектор

3. TDD Guide — Наставник по TDD

4. Code Reviewer — Ревьюер кода

5. Security Reviewer — Аудитор безопасности

7. E2E Runner — Эксперт по E2E-тестированию

8. Refactor Cleaner — Специалист по рефакторингу

9. Doc Updater — Специалист по документации

Какого агента вызывать

Примеры взаимодействия агентов

Сценарий 1: Разработка новой функции с нуля

Сценарий 2: Исправление ошибок сборки

Сценарий 3: Очистка кода

Резюме урока

Анонс следующего урока

Приложение: Ссылки на исходный код