Субагенты и контекстная изоляция

В предыдущей статье мы разобрали слэш-команды — простейший способ кодифицировать повторяющийся запрос. Субагент — другой уровень абстракции: не шаблон промпта, а полноценный изолированный экземпляр Claude со своим контекстным окном, своим системным промптом и своими правами доступа к инструментам. Когда задача «утонет» в вашем основном диалоге — многотомные логи, git-история, результаты тестов — субагент выполняет её в отдельном пространстве и возвращает только итог.

Как работает изоляция

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

Что субагент получает при старте:

• Системный промпт — тело его markdown-файла плюс детали окружения (рабочий каталог, версия инструментов). Не полный системный промпт Claude Code.
• CLAUDE.md и память — все уровни иерархии памяти, которые загружаются в основной сессии. Исключение: встроенные субагенты Explore и Plan намеренно их не грузят, чтобы оставаться быстрыми и дешёвыми.
• Git-статус — снимок состояния репозитория на момент старта родительской сессии.
• Прелоадированные навыки — если в frontmatter указано поле skills, их содержимое инжектируется в контекст сразу.

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

flowchart TD
    User(["Вы"])
    Main["Основная сессия\n(контекстное окно)"] 
    Agent1["Субагент A\n(изолированный контекст)"]
    Agent2["Субагент B\n(изолированный контекст)"]
    
    User -->|"запрос"| Main
    Main -->|"делегирует задачу + краткий контекст"| Agent1
    Main -->|"делегирует задачу + краткий контекст"| Agent2
    Agent1 -->|"возвращает только итог"| Main
    Agent2 -->|"возвращает только итог"| Main
    
    subgraph SubA ["Субагент A"]
        Agent1
        T1["Read / Bash / Grep..."] 
        M1["Свой CLAUDE.md\n+ память"]
        Agent1 --- T1
        Agent1 --- M1
    end
    
    subgraph SubB ["Субагент B"]
        Agent2
        T2["Read / Bash / Grep..."]
        M2["Свой CLAUDE.md\n+ память"]
        Agent2 --- T2
        Agent2 --- M2
    end

Встроенные субагенты

Claude Code поставляется с несколькими преднастроенными субагентами, которые Claude выбирает автоматически:

Explore — самый частый гость: когда Claude нужно понять структуру проекта перед реализацией, он запускает Explore в Haiku, а тонны grep-результатов оседают в отдельном контексте, не засоряя ваш диалог.

Отключить конкретный субагент можно через permissions.deny в settings.json:

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(Plan)"]
  }
}

Создание кастомного субагента

Субагент — это markdown-файл с YAML-frontmatter. Структура та же, что и у слэш-команд, но семантика другая: тело файла становится системным промптом субагента, а не инструкцией для основного Claude.

---
name: code-reviewer
description: Reviews code for quality, security, and best practices. Use proactively after significant code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
color: blue
---

You are a senior code reviewer. When invoked, analyze the specified code and provide
specific, actionable feedback organized by severity (critical / warning / suggestion).
For each finding: describe the issue, show the affected code, and propose a fix.

Положить файл можно в два места:

Субагенты в .claude/agents/ стоит коммитить в репозиторий — тогда команда получит их автоматически.

Важно: файлы подхватываются только при старте сессии. Если создали файл вручную на диске — перезапустите claude. Субагенты, созданные через /agents, применяются немедленно.

Все поля frontmatter

Обязательны только name и description. Остальное — по необходимости:

---
name: db-analyst          # уникальный идентификатор (строчные + дефисы)
description: Analyze query performance and suggest indexes. Use when user mentions slow queries.
tools: Read, Bash, Grep   # allowlist инструментов
disallowedTools: Write    # denylist (применяется первым, если заданы оба)
model: haiku              # sonnet | opus | haiku | fable | inherit | полный ID
permissionMode: acceptEdits  # default | acceptEdits | auto | dontAsk | bypassPermissions | plan
maxTurns: 20             # максимум агентных шагов
effort: high             # low | medium | high | xhigh | max
isolation: worktree      # запустить в изолированном git worktree
memory: project          # user | project | local — persistent memory
skills:
  - api-conventions      # навыки, прелоадируемые в контекст
color: green             # red | blue | green | yellow | purple | orange | pink | cyan
background: true         # всегда запускать в фоне
---

Несколько деталей, которые легко пропустить:

model: haiku — субагенты можно запускать на более дешёвой модели. Рутинный code review, поиск по кодовой базе, анализ логов — всё это прекрасно работает на Haiku с долей цены Sonnet.

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

bypassPermissions в permissionMode — снимает все защитные запросы. Использовать только в изолированных окружениях (Docker, sandbox). Подробности — в статье Модель разрешений, безопасность и доверие.

mcpServers — можно дать субагенту доступ к MCP-серверу, которого нет в основной сессии, и изолировать его инструменты от основного контекста:

---
name: browser-tester
description: Test features in a real browser using Playwright
mcpServers:
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
---

Use Playwright to navigate, screenshot, and interact with web pages.

Подробнее об MCP — в разделе MCP и интеграции с внешними инструментами.

Как вызвать субагент

Три способа, от мягкого к жёсткому:

Естественный язык — Claude сам решит, делегировать ли задачу:

Use the code-reviewer subagent to look at my auth changes

@-упоминание — гарантирует, что именно этот субагент будет вызван для задачи:

@"code-reviewer (agent)" посмотри на изменения в auth/

Режим для всей сессии — флаг --agent запускает Claude Code так, что основной тред сам работает с системным промптом субагента:

claude --agent code-reviewer

Полезно, когда вся сессия посвящена одному типу работы — например, рефакторингу под конкретный стиль.

Команда /agents открывает TUI-интерфейс: вкладка Running — живые и завершённые субагенты, Library — все доступные (встроенные, пользовательские, из плагинов). Там же можно создать субагент с помощью мастера или попросить Claude сгенерировать его по описанию.

Фон или foreground

Каждый субагент запускается либо в foreground (блокирует основной диалог до завершения), либо в background (параллельно, пока вы продолжаете работу).

• Foreground: запросы на разрешения «пробрасываются» в ваш терминал — вы их видите и отвечаете.
• Background: субагент работает автономно; если что-то требует разрешения и оно не было выдано заранее — запрос автоматически отклоняется, но субагент продолжает работу.

Claude выбирает режим сам, исходя из задачи. Вы можете попросить явно: «run this in the background» — или нажать Ctrl+B, когда задача уже выполняется.

Параллельное исследование — один из самых эффективных паттернов:

Research the authentication, database, and API modules in parallel using separate subagents

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

Вложенные субагенты и цепочки

Начиная с версии 2.1.172 субагент может порождать собственные субагенты. Полезно, когда делегированная задача сама распадается на параллельные подзадачи:

Use the code-reviewer subagent to find performance issues,
then use the optimizer subagent to fix them

Claude запустит reviewer, получит список проблем, передаст их optimizer-у — промежуточный вывод так и не появится в вашем основном диалоге.

Ограничение на глубину вложенности: background-субагент на уровне глубины 5 уже не может порождать дочерних. Это защита от бесконтрольного разрастания параллельных деревьев.

Возобновить субагент после завершения тоже можно:

Use the code-reviewer subagent to review the authentication module
[Субагент завершился]

Continue that code review and now analyze the authorization logic

Claude возобновит субагент с полной историей его разговора — он помнит, что уже проверил.

Постоянная память субагента

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

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: project
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

# Пример структуры файлов для субагента «code-reviewer»

~/.claude/
└── agent-memory/
    └── code-reviewer/
        └── MEMORY.md          # user-скоуп: общий для всех проектов

<project>/
└── .claude/
    ├── agent-memory/
    │   └── code-reviewer/
    │       └── MEMORY.md      # project-скоуп: коммитится в репозиторий
    └── agent-memory-local/
        └── code-reviewer/
            └── MEMORY.md      # local-скоуп: в .gitignore, только для вас

Субагент автоматически получает инструкцию читать свой MEMORY.md при старте. Рекомендация: явно попросите субагент обновлять память после выполнения задачи: «теперь сохрани, что узнал, в memory». Постепенно накапливается институциональная база знаний.

Когда субагент оправдывает себя

Иногда проще остаться в основном диалоге. Субагент — не панацея:

Используйте субагент, если:

• Задача порождает большой вывод (тесты, логи, документация), который не нужен в основном контексте
• Нужна специфическая комбинация инструментов или разрешений
• Работа самодостаточна и сводится к итоговому резюме
• Хотите запустить несколько независимых исследований параллельно

Останьтесь в основном диалоге, если:

• Задача требует частых уточнений и итераций
• Несколько фаз работы тесно связаны контекстом (план → реализация → тесты)
• Изменение маленькое и точечное
• Важна латентность — субагент стартует с нуля и тратит время на набор контекста

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

Для быстрого вопроса, ответ на который не нужно сохранять в истории, есть /btw — задаёт вопрос в боковом контексте без создания субагента.

Практический пример: агент для code review с памятью

---
name: pr-reviewer
description: Review pull requests for quality, security, and conventions. Use when user asks to review PR or code changes.
tools: Read, Glob, Grep, Bash
model: sonnet
memory: project
color: purple
---

You are a senior engineer doing code review. Review the specified code or PR.

Before reviewing, check your MEMORY.md for:
- Known patterns and conventions in this codebase
- Recurring issues to watch for
- Architectural decisions already made

Provide feedback organized by severity:
- 🔴 Critical: must fix before merge
- 🟡 Warning: strongly recommended
- 🟢 Suggestion: optional improvement

After reviewing, update MEMORY.md with:
- New patterns you discovered
- Issues you found that may recur
- Anything that helps future reviews

Первый раз такой субагент делает код ревью «вслепую», как обычно. Со временем он сам строит карту проекта: знает, что в этой кодовой базе принято логировать через logger.structured(), что utils/auth.ts — исторически проблемное место, что тесты по конвенции должны идти в __tests__/.

Подробнее о том, как организовать набор субагентов, команд и навыков в переиспользуемый бандл — в статье Plugins и marketplace. Матрица выбора между всеми механизмами расширяемости — в Что выбрать: команда, навык, субагент, MCP или хук.

See also

• Слэш-команды: встроенные и кастомные — более лёгкий механизм для шаблонов промптов без изоляции контекста
• Skills — переносимые навыки — переиспользуемая экспертиза в основном контексте, не требующая изоляции
• Hooks — события жизненного цикла — детерминированные shell-команды на событиях SubagentStart/SubagentStop
• Что выбрать: команда, навык, субагент, MCP или хук — решающая матрица для всех механизмов расширяемости
• Модель разрешений, безопасность и доверие — подробнее о bypassPermissions и permissionMode
• CLAUDE.md и система памяти — как иерархия памяти загружается в субагенты
• Управление контекстным окном — почему изоляция субагентов помогает сохранять главный контекст чистым
• Plugins и marketplace — как упаковать субагенты вместе с командами и хуками в один бандл
• Динамические workflows и оркестрация агентов — масштабирование до полноценных агентных команд с независимыми контекстами