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

​
Что такое подагенты?

Подагенты — это предварительно настроенные AI-личности, которым Claude Code может делегировать задачи. Каждый подагент:
  • Имеет определённую цель и область экспертизы
  • Использует собственное окно контекста, отдельное от основного разговора
  • Может быть настроен с определёнными инструментами, которые ему разрешено использовать
  • Включает пользовательскую системную подсказку, которая направляет его поведение
Когда Claude Code встречает задачу, которая соответствует области экспертизы подагента, он может делегировать эту задачу специализированному подагенту, который работает независимо и возвращает результаты.

​
Ключевые преимущества

Сохранение контекста

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

Специализированная экспертиза

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

Переиспользуемость

После создания подагенты можно использовать в разных проектах и делиться ими с вашей командой для согласованных рабочих процессов.

Гибкие разрешения

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

​
Быстрый старт

Чтобы создать свой первый подагент:
1

Откройте интерфейс подагентов

Выполните следующую команду:
/agents
2

Выберите 'Create New Agent'

Выберите, создавать ли подагент на уровне проекта или на уровне пользователя
3

Определите подагент

  • Рекомендуется: Сначала сгенерируйте с помощью Claude, а затем настройте, чтобы сделать его своим
  • Подробно опишите свой подагент и когда его следует использовать
  • Выберите инструменты, к которым вы хотите предоставить доступ (или оставьте пусто, чтобы унаследовать все инструменты)
  • Интерфейс показывает все доступные инструменты, что облегчает выбор
  • Если вы генерируете с помощью Claude, вы также можете отредактировать системную подсказку в своём редакторе, нажав e
4

Сохраните и используйте

Ваш подагент теперь доступен! Claude будет использовать его автоматически, когда это уместно, или вы можете вызвать его явно:
> Use the code-reviewer subagent to check my recent changes

​
Конфигурация подагента

​
Расположение файлов

Подагенты хранятся как файлы Markdown с фронтматтером YAML в двух возможных местах:
ТипРасположениеОбластьПриоритет
Подагенты проекта.claude/agents/Доступны в текущем проектеНаивысший
Подагенты пользователя~/.claude/agents/Доступны во всех проектахНиже
Когда имена подагентов конфликтуют, подагенты на уровне проекта имеют приоритет над подагентами на уровне пользователя.

​
Агенты плагинов

Плагины могут предоставлять пользовательские подагенты, которые беспрепятственно интегрируются с Claude Code. Агенты плагинов работают идентично определённым пользователем агентам и появляются в интерфейсе /agents. Расположение агентов плагинов: Плагины включают агентов в своём каталоге agents/ (или пользовательские пути, указанные в манифесте плагина). Использование агентов плагинов:
  • Агенты плагинов появляются в /agents рядом с вашими пользовательскими агентами
  • Могут быть вызваны явно: “Use the code-reviewer agent from the security-plugin”
  • Могут быть вызваны автоматически Claude, когда это уместно
  • Могут быть управляемы (просмотрены, проверены) через интерфейс /agents
Подробности о создании агентов плагинов см. в справочнике компонентов плагинов.

​
Конфигурация на основе CLI

Вы также можете определить подагенты динамически, используя флаг CLI --agents, который принимает объект JSON: 
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
Приоритет: Подагенты, определённые через CLI, имеют более низкий приоритет, чем подагенты на уровне проекта, но более высокий приоритет, чем подагенты на уровне пользователя. Вариант использования: Этот подход полезен для:
  • Быстрого тестирования конфигураций подагентов
  • Подагентов, специфичных для сеанса, которые не нужно сохранять
  • Скриптов автоматизации, которым нужны пользовательские подагенты
  • Обмена определениями подагентов в документации или скриптах
Подробную информацию о формате JSON и всех доступных опциях см. в документации справочника CLI.

​
Формат файла

Каждый подагент определяется в файле Markdown со следующей структурой: 
---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
model: sonnet  # Optional - specify model alias or 'inherit'
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

Include specific instructions, best practices, and any constraints
the subagent should follow.

​
Поля конфигурации

ПолеОбязательноОписание
nameДаУникальный идентификатор, использующий строчные буквы и дефисы
descriptionДаОписание на естественном языке цели подагента
toolsНетСписок инструментов, разделённых запятыми. Если опущено, наследует все инструменты из основного потока
modelНетМодель для использования этим подагентом. Может быть псевдонимом модели (sonnet, opus, haiku) или 'inherit' для использования модели основного разговора. Если опущено, по умолчанию используется настроенная модель подагента

​
Выбор модели

Поле model позволяет вам контролировать, какую AI-модель использует подагент:
  • Псевдоним модели: Используйте один из доступных псевдонимов: sonnet, opus или haiku
  • 'inherit': Используйте ту же модель, что и основной разговор (полезно для согласованности)
  • Опущено: Если не указано, использует модель по умолчанию, настроенную для подагентов (sonnet)
Использование 'inherit' особенно полезно, когда вы хотите, чтобы ваши подагенты адаптировались к выбору модели основного разговора, обеспечивая согласованные возможности и стиль ответов на протяжении всего сеанса.

​
Доступные инструменты

Подагентам может быть предоставлен доступ к любому из внутренних инструментов Claude Code. Полный список доступных инструментов см. в документации инструментов.
Рекомендуется: Используйте команду /agents для изменения доступа к инструментам — она предоставляет интерактивный интерфейс, который перечисляет все доступные инструменты, включая любые подключённые инструменты MCP-сервера, что облегчает выбор нужных вам.
У вас есть два варианта для настройки инструментов:
  • Опустите поле tools, чтобы унаследовать все инструменты из основного потока (по умолчанию), включая инструменты MCP
  • Укажите отдельные инструменты как список, разделённый запятыми, для более детального управления (может быть отредактирован вручную или через /agents)
Инструменты MCP: Подагенты могут получать доступ к инструментам MCP с настроенных MCP-серверов. Когда поле tools опущено, подагенты наследуют все инструменты MCP, доступные основному потоку.

​
Управление подагентами

​
Использование команды /agents (Рекомендуется)

Команда /agents предоставляет комплексный интерфейс для управления подагентами: 
/agents
Это открывает интерактивное меню, где вы можете:
  • Просмотреть все доступные подагенты (встроенные, пользовательские и проектные)
  • Создать новые подагенты с пошаговой настройкой
  • Отредактировать существующие пользовательские подагенты, включая их доступ к инструментам
  • Удалить пользовательские подагенты
  • Увидеть, какие подагенты активны при наличии дубликатов
  • Легко управлять разрешениями инструментов с полным списком доступных инструментов

​
Прямое управление файлами

Вы также можете управлять подагентами, работая непосредственно с их файлами: 
# Create a project subagent
mkdir -p .claude/agents
echo '---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively run the appropriate tests. If tests fail, analyze the failures and fix them while preserving the original test intent.' > .claude/agents/test-runner.md

# Create a user subagent
mkdir -p ~/.claude/agents
# ... create subagent file

​
Эффективное использование подагентов

​
Автоматическое делегирование

Claude Code проактивно делегирует задачи на основе:
  • Описания задачи в вашем запросе
  • Поля description в конфигурациях подагентов
  • Текущего контекста и доступных инструментов
Чтобы поощрить более проактивное использование подагентов, включите фразы типа “use PROACTIVELY” или “MUST BE USED” в ваше поле description.

​
Явный вызов

Запросите конкретный подагент, упомянув его в своей команде: 
> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

​
Встроенные подагенты

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

​
Подагент Plan

Подагент Plan — это специализированный встроенный агент, предназначенный для использования в режиме плана. Когда Claude работает в режиме плана (режим без выполнения), он использует подагент Plan для проведения исследований и сбора информации о вашей кодовой базе перед представлением плана. Ключевые характеристики:
  • Модель: Использует Sonnet для более способного анализа
  • Инструменты: Имеет доступ к инструментам Read, Glob, Grep и Bash для исследования кодовой базы
  • Цель: Поиск файлов, анализ структуры кода и сбор контекста
  • Автоматический вызов: Claude автоматически использует этот агент в режиме плана, когда ему нужно исследовать кодовую базу
Как это работает: Когда вы находитесь в режиме плана и Claude должен понять вашу кодовую базу для создания плана, он делегирует задачи исследования подагенту Plan. Это предотвращает бесконечное вложение агентов (подагенты не могут порождать других подагентов), при этом позволяя Claude собрать необходимый контекст. Пример сценария: 
User: [In plan mode] Help me refactor the authentication module

Claude: Let me research your authentication implementation first...
[Internally invokes Plan subagent to explore auth-related files]
[Plan subagent searches codebase and returns findings]
Claude: Based on my research, here's my proposed plan...
Подагент Plan используется только в режиме плана. В обычном режиме выполнения Claude использует универсальный агент или другие пользовательские подагенты, которые вы создали.

​
Примеры подагентов

​
Рецензент кода

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is simple and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

​
Отладчик

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not just symptoms.

​
Специалист по данным

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

​
Лучшие практики

  • Начните с агентов, созданных Claude: Мы настоятельно рекомендуем сгенерировать ваш первоначальный подагент с помощью Claude, а затем итерировать его, чтобы сделать его личным. Этот подход даёт вам лучшие результаты — прочную основу, которую вы можете настроить под свои конкретные потребности.
  • Разработайте сосредоточенные подагенты: Создавайте подагенты с единственной, чёткой ответственностью, а не пытайтесь заставить один подагент делать всё. Это улучшает производительность и делает подагентов более предсказуемыми.
  • Напишите подробные подсказки: Включите конкретные инструкции, примеры и ограничения в ваши системные подсказки. Чем больше руководства вы предоставите, тем лучше будет работать подагент.
  • Ограничьте доступ к инструментам: Предоставляйте только инструменты, необходимые для цели подагента. Это улучшает безопасность и помогает подагенту сосредоточиться на релевантных действиях.
  • Контроль версий: Проверьте подагенты проекта в систему контроля версий, чтобы ваша команда могла извлекать выгоду и улучшать их совместно.

​
Продвинутое использование

​
Цепочка подагентов

Для сложных рабочих процессов вы можете связать несколько подагентов: 
> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

​
Динамический выбор подагента

Claude Code интеллектуально выбирает подагентов на основе контекста. Сделайте ваши поля description конкретными и ориентированными на действия для лучших результатов.

​
Возобновляемые подагенты

Подагенты можно возобновить, чтобы продолжить предыдущие разговоры, что особенно полезно для долгосрочных задач исследования или анализа, которые нужно продолжить в нескольких вызовах. Как это работает:
  • Каждому выполнению подагента присваивается уникальный agentId
  • Разговор агента хранится в отдельном файле транскрипта: agent-{agentId}.jsonl
  • Вы можете возобновить предыдущего агента, предоставив его agentId через параметр resume
  • При возобновлении агент продолжает с полным контекстом из своего предыдущего разговора
Пример рабочего процесса: Первоначальный вызов: 
> Use the code-analyzer agent to start reviewing the authentication module

[Agent completes initial analysis and returns agentId: "abc123"]
Возобновите агента: 
> Resume agent abc123 and now analyze the authorization logic as well

[Agent continues with full context from previous conversation]
Варианты использования:
  • Долгосрочные исследования: Разбейте большой анализ кодовой базы на несколько сеансов
  • Итеративное совершенствование: Продолжайте совершенствовать работу подагента без потери контекста
  • Многоэтапные рабочие процессы: Пусть подагент работает над связанными задачами последовательно, сохраняя контекст
Технические детали:
  • Транскрипты агентов хранятся в каталоге вашего проекта
  • Запись отключена при возобновлении, чтобы избежать дублирования сообщений
  • Как синхронные, так и асинхронные агенты могут быть возобновлены
  • Параметр resume принимает ID агента из предыдущего выполнения
Программное использование: Если вы используете Agent SDK или взаимодействуете с AgentTool напрямую, вы можете передать параметр resume: 
{
  "description": "Continue analysis",
  "prompt": "Now examine the error handling patterns",
  "subagent_type": "code-analyzer",
  "resume": "abc123"  // Agent ID from previous execution
}
Отслеживайте ID агентов для задач, которые вы можете захотеть возобновить позже. Claude Code отображает ID агента, когда подагент завершает свою работу.

​
Соображения производительности

  • Эффективность контекста: Агенты помогают сохранить основной контекст, позволяя более длительные общие сеансы
  • Задержка: Подагенты начинают с чистого листа каждый раз, когда они вызываются, и могут добавить задержку, поскольку они собирают контекст, который им требуется для эффективного выполнения своей работы.

​
Связанная документация

  • Плагины - Расширьте Claude Code пользовательскими агентами через плагины
  • Слэш-команды - Узнайте о других встроенных командах
  • Параметры - Настройте поведение Claude Code
  • Хуки - Автоматизируйте рабочие процессы с помощью обработчиков событий