Мультиагентные системы: финальный мастер-проект

📖 Теория

Что такое мультиагентные системы?

Мультиагентная система — это координация нескольких Claude агентов для выполнения сложной задачи. Каждый агент специализируется на своей части работы, результаты объединяются в финальный результат.

Когда использовать мультиагентный подход?

• Задача распадается на независимые подзадачи
• Нужна параллельная обработка (экономия времени)
• Требуется специализация (разные expertise)
• Объём работы превышает возможности одного агента

Workflow инструмент

Claude Code предоставляет Workflow инструмент для оркестрации:

Workflow({
  script: `
    export const meta = {
      name: 'review-code',
      description: 'Code review across dimensions'
    }

    const results = await parallel([
      () => agent('Review for bugs', { label: 'bugs' }),
      () => agent('Review for security', { label: 'security' }),
      () => agent('Review for performance', { label: 'perf' })
    ])

    return { results }
  `
})

Основные примитивы

Parallel vs Pipeline

// Parallel: все агенты стартуют одновременно
await parallel([
  () => agent('Review file1.js'),
  () => agent('Review file2.js'),
  () => agent('Review file3.js')
])

// Pipeline: каждый агент ждёт предыдущего
await pipeline([file1, file2, file3], file => 
  agent(`Review ${file}`)
)

Pipeline без барьера: если один файл review завершился, verify стартует сразу, не дожидаясь других reviews.

Structured Output

Агенты возвращают структурированный JSON для координации:

const review = await agent('Review for bugs', {
  schema: {
    findings: [{
      file: 'string',
      line: 'number',
      severity: 'enum[critical,major,minor]',
      description: 'string'
    }]
  }
})

// review.findings — массив объектов
review.findings.forEach(f => {
  if (f.severity === 'critical') {
    // автоматически создать задачу
  }
})

Resume и Error Handling

Workflow сохраняет прогресс:

Workflow({
  script: 'path/to/script.js',
  resumeFromRunId: 'wf_abc123'  // продолжить с сохранённого состояния
})

Если агент упал, исправьте скрипт и resume — завершённые агенты не перезапускаются.

🛠 Практика

Пример 1: Code Review по измерениям

Создай workflow для code review изменённых файлов по 4 измерениям: bugs, security, performance, style. Каждое измерение — отдельный агент.

export const meta = {
  name: 'multi-dimensional-review',
  description: 'Review changed files across 4 dimensions',
  phases: [
    { title: 'Review' },
    { title: 'Report' }
  ]
}

const DIMENSIONS = [
  { key: 'bugs', prompt: 'Review for bugs and correctness issues' },
  { key: 'security', prompt: 'Review for security vulnerabilities' },
  { key: 'performance', prompt: 'Review for performance problems' },
  { key: 'style', prompt: 'Review for code style and readability' }
]

phase('Review')
const reviews = await parallel(
  DIMENSIONS.map(d => () =>
    agent(d.prompt, {
      label: `review:${d.key}`,
      schema: {
        findings: [{
          file: 'string',
          line: 'number',
          severity: 'string',
          issue: 'string'
        }]
      }
    })
  )
)

phase('Report')
const allFindings = reviews.flatMap(r => r.findings)
const critical = allFindings.filter(f => f.severity === 'critical')

return {
  total: allFindings.length,
  critical: critical.length,
  findings: allFindings
}

Пример 2: E2E Testing Pipeline

Создай workflow для E2E тестирования: найти все test файлы, запустить каждый параллельно, собрать результаты.

export const meta = {
  name: 'e2e-testing',
  description: 'Run E2E tests in parallel',
  phases: [
    { title: 'Discover' },
    { title: 'Execute' },
    { title: 'Report' }
  ]
}

phase('Discover')
const discovery = await agent('Find all .test.js files in tests/e2e/', {
  schema: { files: ['string'] }
})

phase('Execute')
const results = await parallel(
  discovery.files.map(file => () =>
    agent(`Run test ${file}`, {
      label: `test:${file}`,
      schema: {
        passed: 'boolean',
        duration: 'number',
        failures: ['string']
      }
    })
  )
)

phase('Report')
const passed = results.filter(r => r.passed).length
const failed = results.filter(r => !r.passed).length

return {
  total: results.length,
  passed,
  failed,
  details: results
}

Пример 3: Review → Verify Pipeline

Создай workflow: code review каждого файла, затем adversarial verification каждого finding. Используй pipeline для цепочки review → verify.

export const meta = {
  name: 'review-and-verify',
  description: 'Review files, then verify each finding',
  phases: [
    { title: 'Review' },
    { title: 'Verify' }
  ]
}

const FILES = ['src/auth.js', 'src/payment.js', 'src/user.js']

const results = await pipeline(FILES, async file => {
  phase('Review')
  const review = await agent(`Review ${file} for bugs`, {
    label: `review:${file}`,
    schema: {
      findings: [{
        line: 'number',
        issue: 'string',
        severity: 'string'
      }]
    }
  })

  phase('Verify')
  const verified = await parallel(
    review.findings.map(f => () =>
      agent(`Adversarially verify: ${f.issue}`, {
        label: `verify:${file}:${f.line}`,
        schema: {
          isReal: 'boolean',
          reasoning: 'string'
        }
      })
    )
  )

  return {
    file,
    findings: review.findings.map((f, i) => ({
      ...f,
      verified: verified[i]
    }))
  }
})

const confirmedFindings = results
  .flatMap(r => r.findings)
  .filter(f => f.verified.isReal)

return { confirmed: confirmedFindings }

Пример 4: Deployment Pipeline

Создай workflow для deployment: lint → test → build → deploy. Каждый этап зависит от предыдущего.

export const meta = {
  name: 'deployment-pipeline',
  description: 'Full deployment pipeline with stages',
  phases: [
    { title: 'Lint' },
    { title: 'Test' },
    { title: 'Build' },
    { title: 'Deploy' }
  ]
}

phase('Lint')
const lint = await agent('Run eslint on src/', {
  schema: { passed: 'boolean', errors: ['string'] }
})
if (!lint.passed) {
  return { error: 'Lint failed', details: lint.errors }
}

phase('Test')
const test = await agent('Run npm test', {
  schema: { passed: 'boolean', failures: ['string'] }
})
if (!test.passed) {
  return { error: 'Tests failed', details: test.failures }
}

phase('Build')
const build = await agent('Run npm run build', {
  schema: { success: 'boolean', output: 'string' }
})
if (!build.success) {
  return { error: 'Build failed', output: build.output }
}

phase('Deploy')
const deploy = await agent('Deploy to production', {
  schema: { deployed: 'boolean', url: 'string' }
})

return {
  success: true,
  deployedUrl: deploy.url
}

Пример 5: Интеграция с gstack

Используй gstack скиллы внутри workflow для экспертизы.

export const meta = {
  name: 'feature-with-gstack',
  description: 'Full feature development with gstack experts'
}

// CEO reviews idea
const ceoReview = await agent('Use /office-hours for feature: user notifications', {
  label: 'ceo-review'
})

// Tech Lead reviews architecture
const techReview = await agent('Use /plan-eng-review for notification system', {
  label: 'tech-review'
})

// Designer reviews UI
const designReview = await agent('Use /design-review for notification UI', {
  label: 'design-review'
})

// Implementation
const implementation = await agent('Implement notification system', {
  label: 'implementation'
})

// QA tests
const qa = await agent('Use /qa for notification flow', {
  label: 'qa-testing'
})

// Security audit
const security = await agent('Use /cso for notification security', {
  label: 'security-audit'
})

// Deploy
const deploy = await agent('Use /ship for notification deployment', {
  label: 'deployment'
})

return { status: 'shipped', reviews: [ceoReview, techReview, designReview, qa, security] }

📝 Финальный проект

🎓 После урока вы умеете

• Создавать Workflow скрипты с meta, phases, agent()
• Использовать parallel() для независимых задач
• Использовать pipeline() для зависимых задач
• Возвращать structured output через JSON schema
• Обрабатывать ошибки и resume workflow
• Комбинировать мультиагентные системы с gstack и MCP
• Понимать, когда мультиагентный подход эффективнее одного агента

⚠️ Best Practices

1. Размер workflow

По умолчанию: до 15 агентов. Если больше — явно спросите у пользователя разрешение.

2. Naming и labels

Используйте понятные labels для агентов:

agent('Review auth.js', { label: 'review:auth' })
agent('Verify finding in auth.js:42', { label: 'verify:auth:42' })

3. Schema validation

Всегда валидируйте возвращаемые данные:

const result = await agent('...', { schema: { items: ['string'] } })
if (!result.items || result.items.length === 0) {
  log('No items found')
}

4. Phases для читаемости

Разбивайте workflow на логические фазы:

phase('Discovery')
// ...agents
phase('Analysis')
// ...agents
phase('Report')
// ...agents

5. Resume для больших workflow

Сохраняйте промежуточные результаты:

// Первый запуск
Workflow({ script: './review.js' })

// Если упало — исправьте и resume
Workflow({ 
  script: './review.js',
  resumeFromRunId: 'wf_abc123' 
})

💡 Продвинутые паттерны

Map-Reduce

// Map: параллельно обработать файлы
const mapped = await parallel(
  files.map(f => () => agent(`Process ${f}`, { schema: { result: 'number' } }))
)

// Reduce: объединить результаты
const total = mapped.reduce((sum, r) => sum + r.result, 0)

Conditional Branching

const analysis = await agent('Analyze codebase complexity')

if (analysis.complexity === 'high') {
  // Глубокий review
  return await parallel([
    () => agent('Deep security review'),
    () => agent('Deep performance review'),
    () => agent('Deep architecture review')
  ])
} else {
  // Быстрый review
  return await agent('Quick sanity check')
}

Retry с экспоненциальным backoff

async function retryAgent(prompt, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await agent(prompt)
    } catch (e) {
      if (i === maxRetries - 1) throw e
      await sleep(2 ** i * 1000)  // 1s, 2s, 4s
    }
  }
}

🔗 Связанные уроки

• Урок 12: Agent tool — базовые возможности субагентов
• Урок 13: Workflow scripts — введение в оркестрацию
• Урок 14: Pipeline vs Parallel — детали примитивов
• Урок 16: Structured output — JSON schema для агентов
• Урок 31: gstack — использование в workflow
• Урок 32: Superpowers — методология разработки
• Урок 34: MCP серверы — интеграция в workflow

🐛 Troubleshooting

Workflow не запускается

# Проверить синтаксис скрипта
node --check workflow.js

# Проверить meta блок
# Он должен быть ПЕРВЫМ в файле и быть pure literal

Агенты возвращают undefined

Проверьте schema — агент может не вернуть нужные поля:

const result = await agent('...', { 
  schema: { items: ['string'] }
})

if (!result.items) {
  log('Warning: agent did not return items')
  result.items = []  // fallback
}

Workflow слишком медленный

• Используйте parallel() вместо последовательных await
• Не запускайте агентов для trivial задач
• Batch операции (один агент обрабатывает несколько файлов)

Resume не работает

# Получить runId из предыдущего запуска
# Он возвращается в результате Workflow вызова

# Используйте его:
Workflow({
  scriptPath: './workflow.js',
  resumeFromRunId: 'wf_abc123'
})

🎉 Поздравляем!

Вы завершили курс "Claude Code 2.1+ Лайфхаки"!

Теперь вы владеете:

• ✅ Основами Claude Code: команды, скиллы, инструменты
• ✅ Продвинутыми инструментами: планирование, субагенты, workflow
• ✅ gstack framework: виртуальная инженерная команда
• ✅ Superpowers методологией: структурированная разработка
• ✅ Auto Memory системой: знания между сессиями
• ✅ MCP серверами: интеграция с GitHub, браузером, документацией
• ✅ Мультиагентными системами: оркестрация десятков агентов

📚 Дальнейшее обучение

• Продвинутый курс: "Claude Agent SDK для создания своих агентов"
• Специализация: "Claude SaaS — монетизация AI продуктов"
• Практика: "AI Content Factory — генерация контента с Claude"

🌟 Следующие шаги

1. Примените знания на реальном проекте
2. Создайте свой workflow для вашей команды
3. Поделитесь результатами в сообществе
4. Станьте контрибьютором gstack или Superpowers

Удачи в разработке с Claude Code!