Субагенты — одно из самых полезных дополнений к экосистеме Claude Code/Claude Agent: они позволяют разбить сложные рабочие процессы на более мелкие специализированные ИИ-компоненты, сохранить контекст основного потока и безопасно ограничить доступ к инструментам. В этой статье объясняется, что такое субагенты, как их создавать и вызывать (CLI, файловая система и SDK), принципы проектирования вы должны следовать при их построении, и конкретный пример кода вы можете копировать и адаптировать.
Что такое субагенты?
A субагент — это предварительно настроенный, узкоспециализированный ИИ-помощник, которому Claude Code (или Claude Agent SDK) может делегировать работу. Каждый подагент:
- Имеет уникальное имя и четкое описание назначения.
- Работает в своем собственное контекстное окно отдельно от основного разговора (чтобы длинные цепочки деталей не загрязняли контекст организатора).
- Может быть сконфигурирован с ограниченным набором инструменты (чтение/запись файлов, bash, grep, инструменты MCP и т. д.) и с выбором конкретной модели.
- Содержит системную подсказку (личность и инструкции субагента), которая определяет поведение и ограничения.
Благодаря этим свойствам субагенты идеально подходят для задач, требующих большого объема токенов (исследования, поиск в больших журналах), чувствительных к безопасности (сканирование или потенциально разрушительные инструменты) или повторяющихся и четко определенных (проверка стиля, выполнение тестов).
Anthropic быстро совершенствуется: CLAUDE COD CLI и Agent SDK были переработаны и расширены в Клод Агент SDK, была введена поддержка плагинов для объединения агентов и связанных с ними настроек (команды косой черты, серверы MCP, хуки), а также Навыки и умения предоставляют возможность упаковки рабочих процессов домена для повторного использования в Claude.ai, Claude Code и Agent SDK. Эти обновления упрощают поделиться, установить и версия субагентов между командами и проектами. Если вы планируете создавать рабочие процессы для производства, вам следует оценить пакетирование плагинов/навыков и шаблоны развертывания на основе SDK.
Почему субагенты важны
Три причины, по которым они сразу пригодятся:
- Сохранение контекста — Длительные или сложные поисковые запросы, тестовые запуски или сканирования выполняются внутри субагента, а не перегружают основной контекст. Это сокращает потери токенов и упрощает анализ результатов.
- Специализированная экспертиза — вы можете закодировать знания и поведение предметной области в системной подсказке, адаптированной к задаче (например,
security-auditor(сфокусированный на секретах, проблемах зависимостей и небезопасном использовании оболочки). - Более безопасные разрешения — ограничение инструментов на субагента уменьшает радиус взрыва (у рецензента документов могут быть инструменты только для чтения; у тестировщика есть
Bashно нетEdit). - Распараллеливание: Вы можете запустить несколько субагентов для одновременной работы (например:
style-checker,security-scanner,test-runner) и затем собрать их краткие результаты — огромная победа для дорогостоящих независимых проверок.
Предпосылки для использования субагентов в Claude Code
Прежде чем приступить к созданию субагентов, убедитесь, что у вас есть следующее:
1) Клод Код установлен и аутентифицирован
Установите Claude Code CLI или используйте интеграцию с веб-интерфейсом/IDE. Документация по быстрому старту и настройке CometAPI перечислите поддерживаемые методы установки (глобальный пакет npm или собственные установщики) и покажите, как проверить вашу установку с помощью claude --version / claude doctor. Вам также понадобится CometAPI учетная запись (использование ключа CometAPI для доступа к коду Клода дешевле и удобнее, чем официальная модель.) как отмечено в кратком руководстве.
2) Узел/среда (для некоторых путей установки) и базовый инструментарий оболочки
При установке через пакет npm вам понадобится Node.js (в примерах обычно используется Node 18+). Если вы планируете использовать Agent SDK (JavaScript/TypeScript или Python), вам понадобится проект с установленной зависимостью SDK. Многие руководства предполагают наличие стандартных инструментов разработчика (git, bash, опционально). gh CLI для рабочих процессов GitHub).
3) Макет проекта и CLAUDE.md
Лучшая практика — хранить вспомогательную документацию уровня репозитория (CLAUDE.md) и разместить агентов, участвующих в проекте, в .claude/agents/ чтобы участники команды наследовали их. Файлы CLAUDE.md автоматически добавляются в контекст Клода и помогают обеспечить единообразие поведения между сеансами. Каждый субагент — это файл Markdown с заголовком YAML. Минимальный пример:
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.
Return results in JSON with fields: summary, issues.
name— это идентификатор со строчной буквой.descriptionобеспечивает автоматический вызов и сопоставление.toolsограничивает доступ к инструментам (не наследует все).modelможет бытьsonnet,opus,haikuилиinherit.
4) Разрешения и серверы MCP (необязательно, но обычно)
Если ваши рабочие процессы используют серверы Model Context Protocol (MCP) или внешние инструменты (Puppeteer, Sentry, пользовательские инструменты REST), убедитесь, что ваши серверы MCP настроены и доступны. Для конфиденциальных операций (write, bash, git commit) тщательно продумайте список разрешенных и для каждого агента. tools определение области применения.
Как создать субагентов в Claude Code
Вы можете создавать субагенты тремя основными способами: через интерактивный CLI (/agents), как файлы разметки файловой системы, или программно через Agent SDK. Ниже приведены пошаговые инструкции:
Клод Код поддерживает три практических способа создания субагентов:
- Интерактивный интерфейс командной строки
/agentsUI — самый быстрый способ итеративного создания внутри сеанса. - На основе файловой системы — создавать файлы Markdown с заголовком YAML в
.claude/agents/(на уровне проекта) или~/.claude/agents/(на уровне пользователя). Агенты проекта имеют более высокий приоритет. - Программный (Agent SDK) — определить субагентов в коде через
agentsпараметр при вызовеquery(); рекомендуется для приложений на основе SDK. Этот подход идеально подходит, когда субагенты должны создаваться динамически или встраиваться в приложение.
Быстрый интерактивный процесс (рекомендуемый первый шаг)
- Запустите Claude Code в терминале или откройте палитру команд в VS Code.
- Запустите интерфейс субагентов с помощью команды:
/agents
- Выберите Создать нового агента, выберите область действия на уровне проекта или пользователя, заполните поля «Имя», «Описание», «Инструменты» и «Системное приглашение» и сохраните. Вы можете создать черновик с помощью Клода, а затем доработать его. После сохранения агент будет доступен в
/agentsи может быть вызван явно или автоматически.
Субагенты на основе файловой системы (Markdown + YAML frontmatter)
Субагенты хранятся в виде файлов Markdown с заголовком YAML. Поместите их в:
- Объем проекта:
.claude/agents/*.md(наивысший приоритет) - Область действия пользователя:
~/.claude/agents/*.md
Базовая структура файла:
---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash # optional; omit to inherit
model: sonnet # optional; or 'inherit'
---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet
Несколько замечаний по реализации:
nameдолжны быть написаны строчными буквами с дефисами.- Опуская
toolsпозволит субагенту наследовать все инструменты основного потока; явное перечисление инструментов обеспечивает реализацию модели наименьших привилегий. - Используйте
model: 'inherit'для согласованного поведения с основным потоком или укажите псевдоним модели (например,sonnet,opus,haiku).
Определение CLI JSON (использование ad hoc/сеанса)
Вы можете определить временные субагенты непосредственно при запуске сеанса:
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
Определенные с помощью CLI агенты полезны для запуска сценариев или экспериментов; они имеют более низкий приоритет, чем агенты проекта, но более высокий, чем пользовательские агенты.
Программное определение (Agent SDK — рекомендуется для приложений)
Если вы создаете приложение или систему автоматизации, определите субагентов программно с помощью Agent SDK agents параметр (это наиболее интегрированный вариант). Пример (TypeScript):
import { query } from '@anthropic-ai/claude-agent-sdk';
async function runReview() {
const result = await query({
prompt: "Assess the authentication module for security issues",
options: {
agents: {
"code-reviewer": {
description: "Expert code review specialist",
prompt: `You are a code review specialist...`,
tools: ,
model: "sonnet"
},
"test-runner": {
description: "Runs the test suite and analyzes failures",
prompt: `You run tests and summarize failures...`,
tools: ,
model: "sonnet"
}
}
}
});
console.log(result);
}
SDK также принимает агенты на основе файловой системы (он загрузит .claude/agents/ Файлы), если вы предпочитаете этот шаблон. Программные агенты — это мощные инструменты для динамических рабочих процессов и интеграции непрерывной интеграции.
Для Python, claude-agent-sdk Пакет поддерживает похожие шаблоны: вы можете использовать query() or ClaudeSDKClient и программно настраивать параметры, инструменты и серверы MCP. Примеры быстрого старта см. в репозитории Python SDK.
Как вызывать субагентов
Автоматическое делегирование
Клод Код может автоматически Выбирайте субагента, когда запрос пользователя соответствует цели субагента. Это полезно для фоновой оркестровки, когда основной агент автоматически направляет задачи нужному специалисту. Используйте чёткие описания субагентов и конкретные системные подсказки для повышения точности автоматического выбора.
Явный вызов (рекомендуется для ясности)
Вы можете явно вызвать агента в разговоре:
> Use the code-reviewer subagent to check my recent changes
Явный вызов является детерминированным и рекомендуется для производственных потоков, где вы хотите избежать непредвиденного делегирования.
Шаблоны оркестратора SDK
Распространенные шаблоны в приложениях SDK:
- Вилка + сбор: Запустите несколько подагентов параллельно, соберите краткий ответ каждого агента, затем суммируйте/объедините результаты в главном агенте.
- Супервизорный цикл: Оркестратор назначает задачи субагентам, проверяет результаты и либо принимает их, либо запрашивает пересчет/уточнение.
- Выполнение в изолированной среде: Предоставьте потенциально опасные возможности (развертывание, запуск скриптов) строго ограниченному агенту и требуйте явного одобрения человека перед выполнением.
Эти шаблоны соответствуют практическим реализациям с использованием управления сеансами, перехватов и инструментов MCP Agent SDK.
Как создать полезные, безопасные и компонуемые субагенты
1) Единая ответственность и четкие подсказки
Каждый субагент должен иметь одну чёткую цель и системное приглашение, определяющее границы, критерии успеха и формат выходных данных. Если желаемый вывод структурирован (JSON, маркированный список, патч кода), дайте субагенту точные инструкции, чтобы уменьшить количество ошибок парсинга.
2) Наименьшие привилегии для инструментов
Предоставляйте субагенту только те инструменты, которые ему необходимы. Например, рецензенту документов они не нужны. Write or Bash. По возможности используйте режим «только чтение» по умолчанию и при необходимости явно повышайте разрешения для инструментов. Это снижает риск и упрощает аудит.
3) Возвращайте компактные, структурированные результаты
Субагенты должны вернуться краткие, окончательные ответы Вместо длительных отслеживаний мыслей. Распространенная схема: выполнить сложную работу в контексте субагента, а затем вернуть краткий отчёт с вложениями (патчи, ссылки на файлы, JSON). Это максимизирует эффективность контекста для оркестратора.
4) Тестируемость и версионность
Храните файлы субагентов в системе контроля версий, создавайте CI-тесты, которые отрабатывают реальные прогоны с небольшими входными данными, и закрепляйте модели/наборы инструментов. Если вы используете Skills и плагины, используйте шаблоны управления версиями/магазина плагинов для управления обновлениями и откатами.
5) Аудит крючков и контрольных точек с участием человека
Используйте хуки SDK для перехвата вызовов инструментов (хуки PreToolUse) и требуйте одобрения человека для выполнения деструктивных действий. Регистрируйте все вызовы инструментов для воспроизводимых аудитов. SDK предоставляет механизм хуков и разрешений для поддержки этого шаблона.
Пример приложения — небольшой конвейер, подобный производственному
Ниже приведен компактный пример, демонстрирующий типичные элементы: агент файловой системы, вызов SDK, использующий два агента (один для обзора, один для тестов) и простую оркестровку.
1) Агент файловой системы: .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
"summary": "one-line summary",
"issues": ,
"recommended_changes":
}
2) Программная оркестровка (Node.js)
import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';
async function runPipeline() {
const result = query({
prompt: 'Run PR checks: security review then unit tests.',
options: {
agents: {
'code-reviewer': {
description: 'Use PROACTIVELY after code changes; output JSON with issues.',
prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
tools: ,
model: 'sonnet'
},
'test-runner': {
description: 'Run test suite and summarize failing tests.',
prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
tools:
}
}
}
});
for await (const message of result) {
// Implement streaming logic: messages may include subagent outputs
console.log(message);
}
}
runPipeline().catch(console.error);
Примечание: code-reviewer хранится в репозитории для повторного использования командой; вызов SDK демонстрирует, что программные агенты имеют приоритет, а tools область действия предотвращает случайную запись.
Продвинутые темы и шаблоны
Динамическая конфигурация агента
Создайте параметризованные фабрики агентов, которые выбирают модель и наборы инструментов в зависимости от среды (разработка или производство) или уровней серьезности (например, strict vs balanced Режимы безопасности). Примеры SDK показывают, как генерировать определения агентов во время выполнения.
Распараллеливание
Параллельно запустите несколько агентов анализа, доступных только для чтения (стиль, безопасность, тестовое покрытие), и агрегируйте их JSON-вывод в основном потоке. Это значительно сокращает время выполнения для больших репозиториев.
Агенты, предоставляемые плагином
Плагины могут предоставлять субагенты, упакованные вместе с манифестом плагина; они появляются в /agents Наряду с пользовательскими агентами, их можно вызывать явно. Используйте это для распределения стандартизированных агентов между командами.
Где лучше всего использовать Claude code cli
Мы с радостью объявили, что CometAPI теперь полностью поддерживает мощный Claude Code cli. Для использования модели Comet API на Claude Code вам нужно только установить Claude Code и пройти аутентификацию с полученным ключом Comet API и базовым адресом.
Зачем использовать код Клода через CometAPI?
Основные возможности искусственного интеллекта: простая генерация, отладка и оптимизация кода с использованием моделей, созданных специально для разработчиков.
- Гибкий выбор моделей: наш широкий выбор моделей позволит вам разрабатывать более плавно.
- Простая интеграция: API всегда доступны. Интегрируйте Claude Code напрямую в свой рабочий процесс за считанные минуты.
- Использование Claude Code через CometAPI позволит сэкономить еще больше средств. API Claude, предоставляемый CometAPI, на 20% дешевле официальной цены и обновлен до последней версии от официального поставщика.
Готовы ли вы использовать Claude Code cli? Ознакомьтесь с API-руководство для получения подробных инструкций.
Если вы хотите узнать больше советов, руководств и новостей об искусственном интеллекте, подпишитесь на нас VK, X и Discord!
См. также Как установить и запустить Claude Code через CometAPI?
Заключение
Относиться к субагентам как к многоразовые, версионные микроперсоныНачните с малого: сделайте doc-reviewer и еще один test-runner для репо, проверьте их в .claude/agents/и автоматизировать их в CI с помощью headless claude -p. Измените подсказки, добавьте структурированные выходные данные и ужесточите права доступа к инструментам.
Ментальная модель, которая помогает лучше всего: представьте Клода менеджером проекта, а субагентов — специалистами в команде. Менеджер делегирует чётко сформулированные задачи, объединяет результаты работы специалистов и пишет итоговый отчёт. Со временем вы увидите повышение надёжности, улучшение тестируемости и возможность автоматизировать значительные объёмы рабочих процессов разработки.