Содержание

Проблема единого контекста

Один агент vs Команда субагентов

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

Два способа решения

Ручная декомпозиция:                Автоматическая делегация:

Человек                             Человек
├── Задача 1 → Агент A              └── "Сделай фичу X"
├── Задача 2 → Агент B                      │
└── Задача 3 → Агент C                      ▼
                                     Родительский агент
Человек собирает результат           ├── Субагент 1 (исследование)
                                     ├── Субагент 2 (реализация)
                                     └── Субагент 3 (тесты)

                                     Родитель собирает результат

Жизненный цикл субагента

Родитель не следит за процессом работы субагента. Он отправляет задачу и ждёт результат. Это асинхронная модель — как задача в трекере, а не парное программирование.

Что наследует субагент

Самая частая ошибка — забыть, что субагент не видит контекст чата. Всё важное нужно передать в описании задачи явно.

Параллельность субагентов

Родитель: "Добавить экспорт в CSV"
         │
         ├── Субагент 1: исследовать текущий код экспорта
         ├── Субагент 2: найти и изучить тесты экспорта
         └── Субагент 3: проверить зависимости в package.json
         │
         ▼ (все три завершились)
Родитель: синтезирует результаты, планирует реализацию

Ключевое ограничение

Субагент — это чёрный ящик. Вход: задача. Выход: результат. Всё остальное теряется.

Claude Code — Agent tool

Родительский агент вызывает Agent tool с параметрами: prompt, subagent_type, isolation, run_in_background.

Agent tool — полноценный инструмент, доступный модели наравне с Read, Edit, Bash. Субагент получает чистый контекст и возвращает только результат.

Claude Code — AGENTS.md

Файл AGENTS.md в корне репо или отдельные файлы в .claude/agents/*.md описывают кастомных агентов. Claude Code подхватывает их автоматически.

# AGENTS.md

## code-reviewer
You are a senior code reviewer. Focus on:
- Security vulnerabilities (injection, auth bypass, data exposure)
- Performance anti-patterns (N+1 queries, missing indexes)
- API contract violations

Tools: Read, Grep, Glob
Constraints: Never modify files. Always cite file:line.
Output format: list of findings with severity (critical/warning/info).

## test-writer
You are a test engineer. Given a source file, write comprehensive tests.
Tools: Read, Grep, Glob, Edit, Bash
Constraints: Use existing test framework. Run tests before returning.
Output format: summary of tests added and pass/fail status.

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

Claude Code — параллелизм и изоляция

Worktree + параллелизм + фон — главные преимущества субагентности Claude Code.

Roo Code / Kilo Code — режимы

Пользователь: "Добавить авторизацию"
         │
    Orchestrator
    ├── → Architect: спроектировать
    │   ← архитектурный план
    ├── → Code: реализовать
    │   ← код готов
    ├── → Code: написать тесты
    │   ← тесты написаны
    └── → Debug: проверить
        ← всё работает

    Orchestrator → итог пользователю

Roo Code / Kilo Code — .roomodes

Файл .roomodes в корне проекта определяет кастомные режимы. Совместим между Roo Code и Kilo Code.

{ "customModes": [{
    "slug": "doc-writer",
    "name": "Documentation Writer",
    "roleDefinition": "You are a technical writer...",
    "groups": ["read", "command"],
    "customInstructions": "Always include usage examples."
  },
  { "slug": "security-audit", "groups": ["read"], ... }
]}

OpenCode — agents

Агенты определяются декларативно в opencode.json или как markdown-файлы в .opencode/agents/.

{
  "agents": {
    "reviewer": {
      "model": "anthropic:claude-sonnet-4-20250514",
      "prompt": ".opencode/agents/reviewer.md",
      "permission": ["read", "glob", "grep"]
    },
    "implementer": {
      "model": "anthropic:claude-sonnet-4-20250514",
      "prompt": ".opencode/agents/implementer.md",
      "permission": ["read", "glob", "grep", "edit", "bash"]
    }
  }
}

Сводная таблица: субагенты

Самая продвинутая модель — у Claude Code: worktree-изоляция, параллелизм и фоновый режим. Roo/Kilo Code берут удобством Orchestrator-паттерна. OpenCode — минимальный подход с предустановленными профилями.

Когда разбивать руками vs доверять агенту

Паттерн 1: Fan-out / fan-in

Родитель порождает несколько субагентов одновременно, каждый работает над своей частью, затем родитель собирает и синтезирует результаты.

         Родитель
        /   |   \
       /    |    \
      v     v     v
   Sub-1  Sub-2  Sub-3   ← параллельно
      \     |    /
       \    |   /
        v   v  v
    Родитель собирает
        результаты

Лучший паттерн по скорости — все субагенты работают параллельно. Но требует полной независимости подзадач.

Паттерн 2: Pipeline (конвейер)

Цепочка субагентов, где каждый следующий получает результат предыдущего. Порядок строго определён.

Задача → Sub-1 → результат → Sub-2 → результат → Sub-3 → итог

Пример:
┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Генерация   │───►│  Написать    │───►│  Запустить   │
│  кода        │    │  тесты       │    │  и исправить │
└──────────────┘    └──────────────┘    └──────────────┘

Самый простой паттерн. Подходит для задач с чёткой последовательностью шагов, где каждый этап нуждается в результате предыдущего.

Паттерны 3-4: Specialist и Supervisor

      Родитель
     /   |   \
    v    v    v
Ревьюер Тестер Докум.
(только  (только  (только
чтение)  тесты)   docs)

Родитель: поручает задачу
       │
   Субагент: выполняет
       │
Родитель: проверяет
   ┌────┴────┐
   v         v
  OK     Не OK → повтор
         с правками

Сводная таблица паттернов

На практике паттерны комбинируются: Pipeline из трёх шагов, где на первом — Fan-out для исследования, а на последнем — Supervisor для финальной проверки.

Напоминание и продвинутые сценарии

«Промпты — предложения. Hooks — гарантии.» (лекция 1, секция 3.6)

Hook — реакция на событие жизненного цикла агента, выполняемая хостом, а не моделью. Модель не решает, запускать ли hook, — он срабатывает автоматически.

Claude Code hooks

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "npx prettier --write \"$FILEPATH\""
      }]
    }]
  }
}

Claude Code — типы обработчиков

{ "type": "command", "command": "npx prettier --write \"$FILEPATH\"" }

{ "type": "prompt", "prompt": "Check API naming conventions" }

{ "type": "agent", "prompt": "Review changes for security" }

{ "type": "http", "url": "https://hooks.example.com/notify" }

Exit codes: 0 = OK → продолжить · 1 = не-блокирующая ошибка, stderr в лог · 2 = блокировка, stderr → модели

OpenCode плагины

export const AutoFormatPlugin = async ({ $ }) => {
  return {
    "tool.execute.after": async (input, output) => {
      if (input.tool === "write" || input.tool === "edit") {
        const filePath = output.args?.filePath || ""
        if (filePath.match(/\.(ts|tsx|js|jsx)$/))
          await $`npx prettier --write ${filePath}`
      }
    }
  }
}

Roo Code / Kilo Code — эмуляция hooks

Нативных hooks нет. Эмуляция: MCP-tool + правила + .roomodes.

async function execute({ scope }) {
  const { stdout } = await execAsync(
    `npm run lint -- ${scope || "."}`
  )
  return `ok: ${stdout}`
}

## .roo/rules-code/lint.md
Перед ЛЮБЫМ изменением ОБЯЗАН
вызвать `lint_check`.
- `ok:` → можно изменять
- `fail:` → ЗАПРЕЩЕНО

{
  "customModes": [{
    "slug": "safe-code",
    "name": "Safe Code",
    "groups": ["read","edit","mcp"],
    "customInstructions":
      "Always call lint_check"
  }]
}

Ограничение: это не гарантия — модель может пропустить проверку. Для критичных сценариев недостаточно.

Сводная таблица: hooks

Claude Code — самая зрелая реализация: JSON-конфиг, 20+ событий, четыре типа обработчиков, включая уникальные типы agent и http. OpenCode — больше гибкости через код. Roo/Kilo — только эмуляция.

Стратегия выбора hooks

Правило: для критичных сценариев (безопасность, деплой) — только нативные hooks. Для «мягких» рекомендаций — эмуляция допустима, но страхуйте CI/CD.

Ловушки: контекст и дублирование

Общий принцип: субагент получает только текстовое описание задачи — детали теряются при пересказе. Чем точнее задание, тем меньше ошибок.

Ловушки: зацикливание и оверхед

Правило: все четыре ловушки решаются одним подходом — чёткие границы, лимиты и правильный выбор паттерна оркестрации.

6 вещей, которые стоит запомнить

Практическое задание

Полные примеры кода — в конспекте лекции. Выберите один инструмент (Claude Code / Roo / OpenCode) и выполните оба задания.

Лекция 5 · Безопасность агентов

Остаёмся на связи

Telegram канал

t.me/SazonovMaybeTalks

Сканируйте QR или переходите по ссылке, чтобы получить обновления по следующим материалам.