Как использовать subagents в Claude Code для борьбы с переполнением контекста: полное руководство

Вы всё ещё пихаете всё в один контекст? Зря

Помните эту боль: агент начинает диалог как гений, а через 20 сообщений превращается в овоща. Забывает базовые инструкции, повторяется, выдаёт ерунду. Это не баг — это контекстный блот. Мы разбирали его в статье «Как победить контекстный блот и "зону тупости" в агентах: архитектура subagents от Deep Agents». С тех пор Anthropic встроил subagents прямо в Claude Code. Теперь не нужно писать велосипеды — используйте YAML frontmatter и Dynamic Workflows.

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

Что такое subagent в Claude Code и зачем он нужен?

Subagent — это дочерний процесс с собственным изолированным контекстом. Вы даёте ему задачу, он выполняет её в песочнице и возвращает результат. Родительский агент при этом не видит всей кухни subagent — только итог. Это как нанять архитектора, который проектирует фундамент, вместо того чтобы самому читать СНиПы и чертить планы.

В Claude Code 2026 subagents управляются через Dynamic Workflows — декларативное описание в YAML-файлах с frontmatter. Вы просто прописываете, кому какую задачу поручить, и Claude сам запускает параллельные цепочки, объединяя результаты.

Всё это стало возможным благодаря архитектуре, которую мы детально описали в «Архитектура Claude Code: как управлять контекстом, Subagents и писать эффективный CLAUDE.md». Тогда же выяснилось, что ваш CLAUDE.md — часто мусор. Subagents решают и эту проблему: каждый subagent получает только ту часть документации, которая ему нужна.

Как НЕ надо делать: типичная ошибка с одним гигантским промптом

# НЕПРАВИЛЬНО: всё в одном агенте
name: "MonolithAgent"
system: |
  Ты — суперагент. Ты умеешь писать код, ревьювить, деплоить и анализировать архитектуру.
  Сейчас тебе нужно: 1) прочитать 5000 строк кода, 2) найти баги, 3) исправить их,
  4) написать тесты, 5) задеплоить. Вся история чата и файлы проекта будут в контексте.
...

Что произойдёт? После 3-4 сообщений агент начнёт терять нить. К 10-му забудет, что уже исправил. К 20-му — начнёт галлюцинировать. Стоимость — космос. Знакомо?

Правильный подход: YAML frontmatter и Dynamic Workflows

Вместо одного монолита — набор subagents. Каждый отвечает за свой срез. Контекст подгружается только необходимый. Результаты передаются через handoffs — специальные точки передачи данных между агентами.

1 Создайте файл subagent — например, .claude/subagents/code-review.yaml

В этом файле описывается, что делает subagent, какие файлы он видит и куда возвращает результат.

# .claude/subagents/code-review.yaml
---
name: code-review
workflow:
  type: sequential
  steps:
    - name: analyze
      subagent: code-review-analyzer
    - name: report
      subagent: code-review-reporter

trigger:
  on: ["pull_request.opened", "pull_request.synchronize"]
  context:
    include_files: ["src/**/*.ts", "!node_modules"]

handoff:
  output: ".claude/results/code-review-{pr_id}.md"
---

Здесь workflow определяет два последовательных шага — сначала анализ, потом генерация отчёта. trigger указывает, когда запускать subagent. handoff — куда писать результат. Обратите внимание: мы не тащим весь проект — только TypeScript-файлы в src.

2 Определите внутренние subagents для шагов

Каждый шаг — тоже subagent, со своим контекстом. Вот пример анализатора:

# .claude/subagents/code-review-analyzer.yaml
---
name: code-review-analyzer
instructions: |
  Ты — эксперт по code review. Просмотри переданный код и найди:
  - утечки памяти
  - неоптимальные запросы к БД
  - потенциальные race conditions
  - нарушение code style проекта (читай .eslintrc)

  Не оценивай общую архитектуру — этим займётся другой subagent.
context:
  include_files: true
  max_tokens: 4000
handoff:
  input: "upstream"
  output: "downstream"
---

Флаг context.include_files: true означает, что в контекст попадёт содержимое файлов из триггера. max_tokens: 4000 жёстко ограничивает размер контекста — это и есть механизм борьбы с переполнением. Subagent физически не сможет обработать больше 4000 токенов, что вынуждает его быть сфокусированным.

3 Подключите subagent к основному проекту через .claude/workflows.yaml

# .claude/workflows.yaml
workflows:
  - name: "code-review-pipeline"
    triggers:
      - event: pull_request
        action: opened
    steps:
      - agent: code-review
        options:
          assign_to: "claude-codex"  # можно назначить другого агента

Теперь при каждом открытом PR запускается цепочка subagents. Основной агент не участвует — он только получает финальный отчёт через handoff. Круто, правда?

Почему это убивает контекстный блот?

Вернёмся к тому, с чего начали. В предыдущей статье мы разбирали, что «зона тупости» наступает, когда в контексте смешиваются разноплановые инструкции. Subagents решают это радикально: каждый subagent получает изолированный контекст, содержащий только релевантные данные.

Более того, вы можете управлять, что попадает в контекст, через context.include_files и context.max_tokens. Никакого автоматического скармливания всего проекта. Только то, что нужно для задачи.

Расширенный пример: параллельный запуск нескольких subagents

Иногда нужно выполнить несколько независимых проверок одновременно. Dynamic Workflows поддерживают параллельные шаги:

# .claude/subagents/security-scan.yaml
---
name: security-scan
workflow:
  type: parallel
  steps:
    - name: dependency-check
      subagent: dep-vulnerability-scanner
    - name: secret-scan
      subagent: secret-scanner
    - name: code-analysis
      subagent: static-analysis
  aggregator:
    type: merge
    output: ".claude/results/security-{commit_sha}.md"
---

Три subagent запускаются одновременно. После завершения каждого их результаты объединяются агрегатором в один отчёт. Суммарный контекст каждого subagent — не больше 4K токенов. Итоговый отчёт — ещё 2K. Основной агент получает только скомпанованный результат. Как говорится, «удивительно, но факт» — модель не тонет.

Куда девается CLAUDE.md? Всё ещё актуально

Если вы думаете, что subagent'ы отменяют необходимость писать CLAUDE.md — нет. Но его роль меняется. Subagent'ы могут читать не весь файл, а только его секции, используя context с конкретными разделами. Например:

context:
  include_claudemd_sections: ["Code Style", "Testing"]
  max_tokens: 2000

Так CLAUDE.md перестаёт быть мусором и становится артефактом, который агенты используют точечно. Подробнее о том, как именно кэшируется CLAUDE.md и почему его начало должно быть информативным, читайте в нашем разборе «CLAUDE.md убивает код: исследование ETH Zurich».

Семь граблей, на которые вы наступите (и как их обойти)

1. Не указали max_tokens для subagent. По умолчанию subagent получает столько же контекста, сколько родитель. Если не ограничить — бессмысленно. Всегда ставьте лимит.
2. Забыли про handoff. Без него результат subagent не передаётся дальше, и родитель ничего не получает. Проверяйте пути в handoff.output.
3. Слишком много вложенности. Subagent может вызывать subagent, который вызывает ещё subagent. Каждый уровень добавляет latency. Оптимум — 2–3 уровня.
4. Игнорирование кэширования. Claude Code кэширует первые 2000 символов YAML-файлов. Помещайте самые важные инструкции в начало.
5. Попытка передать в subagent весь git diff. Если diff огромен — контекстная зона тупости гарантирована. Дробите на мелкие изменения.
6. Неправильный trigger. Subagent может запускаться на каждое изменение файла, а не только на PR. Настройте триггеры аккуратно.
7. Нет fallback'а. Если subagent не справился или превысил лимит токенов — процесс виснет. Добавьте обработку ошибок через on_error в workflow.

Когда subagent'ы не помогают

Честно: если ваша задача — просто переименовать одну переменную, не нужно запускать целый workflow. Subagent'ы оправданы, когда:

• задача требует анализа большого объёма кода (более 10 000 токенов)
• нужно выполнить несколько независимых проверок параллельно
• вы хотите строго разделить ответственность между разными ролями (например, linting и security)
• ваш проект использует разные стеки, и для каждого нужен свой контекст

В статье о совместной работе нескольких Claude Code мы показали, как handoffs и rollup'ы помогают объединять результаты от разных subagent'ов в единый отчёт — по сути, это следующий уровень организации.

Резюме: делайте subagent'ы, не ждите

Контекстный блот — это хроническая болезнь монолитных агентов. Subagents в Claude Code — лекарство, которое уже вшито в инструмент. Не нужно писать фреймворки. Достаточно YAML-файлов и понимания, как изолировать контекст.

Начните с малого: один subagent для code review. Потом добавьте subagent для тестов. Потом для деплоя. Вы увидите, что агент перестаёт тупить, а счёт за токены падает. Парадокс: дробя контекст, вы делаете систему умнее.

Если захотите зайти ещё дальше — поэкспериментируйте с subagent'ами в worktrees и CI/CD для полностью автономной разработки. Там каждый subagent живёт в своей ветке — идеальная песочница.

Подписаться на канал