---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
disallowedTools: tool4  # Optional - explicitly disallowed tools
model: sonnet  # Optional - sonnet, opus, haiku, or inherit
permissionMode: default  # Optional - permission mode
maxTurns: 20  # Optional - limit agentic turns
skills: skill1, skill2  # Optional - skills to preload into context
mcpServers: server1  # Optional - MCP servers to make available
memory: user  # Optional - persistent memory scope (user, project, local)
background: false  # Optional - run as background task
effort: high  # Optional - reasoning effort (low, medium, high, xhigh, max)
isolation: worktree  # Optional - git worktree isolation
initialPrompt: "Start by analyzing the codebase"  # Optional - auto-submitted first turn
hooks:  # Optional - component-scoped hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

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.

---
name: secure-researcher
description: Research agent with scoped MCP access and restricted permissions
permissionMode: acceptEdits
mcpServers:
  notion:
    type: http
    url: https://mcp.notion.com/mcp
  github:
    type: http
    url: https://api.github.com/mcp
tools: Read, Grep, Glob
---

You are a research agent. You may query Notion and GitHub through the
configured MCP servers, and read local files, but you cannot write or
execute commands outside of accepted edits.

claude --agent secure-researcher

---
name: full-access-agent
description: Agent with all available tools
---

---
name: limited-agent
description: Agent with specific tools only
tools: Read, Grep, Glob, Bash
---

---
name: conditional-agent
description: Agent with filtered tool access
tools: Read, Bash(npm:*), Bash(test:*)
---

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"
  }
}'

{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

Create a subagent that reviews code for security vulnerabilities.

# Create a project subagent
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
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.
EOF

# Create a user subagent (available in all projects)
mkdir -p ~/.claude/agents

> 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

> @"code-reviewer (agent)" review the auth module

# Via CLI flag
claude --agent code-reviewer

# Via settings.json
{
  "agent": "code-reviewer"
}

claude agents

**Сценарии использования**:
- Продолжительные исследования, растянутые на несколько сессий
- Итеративная доработка без потери контекста
- Многошаговые workflow с сохранением контекста

---

## Цепочки субагентов

Запуск нескольких субагентов последовательно:
```bash
> First use the code-analyzer subagent to find performance issues,
  then use the optimizer subagent to fix them

---
name: researcher
memory: user
---

You are a research assistant. Use your memory directory to store findings,
track progress across sessions, and build up knowledge over time.

Check your MEMORY.md file at the start of each session to recall previous context.

export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

style Main fill:#e1f5fe,stroke:#333,color:#333
style Sub fill:#f3e5f5,stroke:#333,color:#333
style WT fill:#e8f5e9,stroke:#333,color:#333
style Clean fill:#fff3e0,stroke:#333,color:#333
style Return fill:#fff3e0,stroke:#333,color:#333

- Субагент работает в собственном git worktree на отдельной ветке
- Если субагент не вносит изменений, worktree автоматически удаляется
- Если изменения есть, путь к worktree и имя ветки возвращаются основному агенту для ревью или слияния

---

## Форкнутые субагенты

Форкнутые субагенты (`context: fork`) наследуют полный контекст диалога родительского агента на момент форка, а не начинают с чистого листа. Это удобно для проработки альтернативных вариантов без потери уже проделанной работы.

> **Доступность**: GA начиная с v2.1.117. Во внешних сборках (не от первой стороны) для включения форков задайте `CLAUDE_CODE_FORK_SUBAGENT=1`.

### Конфигурация
```yaml
---
name: alternative-explorer
description: Explore an alternative implementation path while preserving parent context
context: fork
tools: Read, Edit, Bash, Grep, Glob
---

You are a forked subagent. You inherit the parent's full conversation and
may explore an alternative approach. Return your findings and the parent
will decide whether to adopt them.

export CLAUDE_CODE_FORK_SUBAGENT=1
claude

В этом примере субагент `coordinator` может запускать только субагентов `worker` и `researcher`. Он не может запускать никаких других субагентов, даже если они определены в другом месте.

---

## CLI-команда `claude agents`

Команда `claude agents` выводит список всех настроенных агентов, сгруппированных по источнику (встроенные, на уровне пользователя, на уровне проекта):
```bash
claude agents

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

User: Build the authentication module. Use a team - one teammate for the API endpoints,
      one for the database schema, and one for the test suite.

claude --teammate-mode tmux

{
  "teammateMode": "tmux"
}

export CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200

export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=5

User -->|asks| Main
Main -->|delegates| Reviewer
Main -->|delegates| Tester
Main -->|delegates| Docs
Reviewer -->|returns result| Main
Tester -->|returns result| Main
Docs -->|returns result| Main
Main -->|synthesizes| User

### Жизненный цикл субагента
```mermaid
sequenceDiagram
    participant User
    participant MainAgent as Main Agent
    participant CodeReviewer as Code Reviewer<br/>Subagent
    participant Context as Separate<br/>Context Window

    User->>MainAgent: "Build new auth feature"
    MainAgent->>MainAgent: Analyze task
    MainAgent->>CodeReviewer: "Review this code"
    CodeReviewer->>Context: Initialize clean context
    Context->>CodeReviewer: Load reviewer instructions
    CodeReviewer->>CodeReviewer: Perform review
    CodeReviewer-->>MainAgent: Return findings
    MainAgent->>MainAgent: Incorporate results
    MainAgent-->>User: Provide synthesis

A -->|Clean slate| B
A -->|Clean slate| C
A -->|Clean slate| D

B -->|Results only| A
C -->|Results only| A
D -->|Results only| A

style A fill:#e1f5fe
style B fill:#fff9c4
style C fill:#fff9c4
style D fill:#fff9c4

### Ключевые моменты

- Каждый субагент получает **свежее окно контекста** без истории основного диалога
- Субагенту передаётся только **релевантный контекст** для его конкретной задачи
- Результаты **в сжатом виде** возвращаются основному агенту
- Это предотвращает **исчерпание токенов контекста** в длительных проектах

### Аспекты производительности

- **Экономия контекста** - субагенты сохраняют основной контекст, позволяя вести более длительные сессии
- **Задержка** - субагенты стартуют с чистого листа, поэтому сбор начального контекста может добавлять задержку

### Ключевые особенности поведения

- **Вложенный запуск включён по умолчанию, глубина 3 (v2.1.219)** - субагенты могут запускать собственных субагентов на глубину до трёх уровней ниже основного диалога. Задайте `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`, чтобы изменить лимит, или `1`, чтобы отключить вложенность. На предельной глубине Claude Code скрывает инструмент `Agent` от всех субагентов, кроме форков. (История: в v2.1.172-v2.1.216 вложенность по умолчанию доходила до 5 уровней без возможности её изменить; в v2.1.217 вложенность стала опциональной с глубиной 1; в v2.1.219 значение по умолчанию установлено равным 3.) Используйте синтаксис ограничения `Agent(agent_type)` (см. [Ограничение запускаемых субагентов](#restrict-spawnable-subagents)), чтобы контролировать, каких субагентов может запускать данный субагент
- **Разрешения в фоне** - фоновые субагенты автоматически отклоняют любые разрешения, не одобренные заранее
- **Перевод в фон** - нажмите `Ctrl+B`, чтобы перевести выполняющуюся задачу в фоновый режим
- **Транскрипты** - транскрипты субагентов сохраняются по пути `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl`
- **Автосжатие** - контекст субагента автоматически сжимается при заполнении примерно на 95% (переопределяется переменной окружения `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`)
- **Наследование extended thinking (v2.1.198)** - субагенты и сжатие контекста теперь наследуют настройку extended thinking из сессии (ранее она всегда была отключена). Отдельного поля thinking для субагента нет

### Дополнительные параметры

- **Отключение встроенных агентов Explore/Plan** - задайте `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`, чтобы убрать встроенных агентов Explore и Plan (v2.1.198)
- **Добавление текста к каждому промпту субагента** - в неинтерактивном режиме (`--print`) флаг `--append-subagent-system-prompt "<text>"` добавляет текст к системному промпту каждого субагента (v2.1.205)

---

## Когда использовать субагентов
| Scenario | Use Subagent | Why |
|----------|--------------|-----|
| Complex feature with many steps | Yes | Separate concerns, prevent context pollution |
| Quick code review | No | Unnecessary overhead |
| Parallel task execution | Yes | Each subagent has own context |
| Specialized expertise needed | Yes | Custom system prompts |
| Long-running analysis | Yes | Prevents main context exhaustion |
| Single task | No | Adds latency unnecessarily |
Текущая дата: вторник, 4 августа 2026 г.

<query>

---

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

### Принципы дизайна

**Делайте:**
- Начинайте с агентов, сгенерированных Claude, - сгенерируйте начального субагента с Claude, затем итеративно доработайте его
- Проектируйте сфокусированных субагентов - с одной четкой ответственностью, а не одного, который делает всё
- Пишите подробные промпты - включайте конкретные инструкции, примеры и ограничения
- Ограничивайте доступ к инструментам - предоставляйте только инструменты, необходимые для цели субагента
- Используйте контроль версий - добавляйте проектных субагентов в систему контроля версий для командной работы

**Не делайте:**
- Не создавайте пересекающихся субагентов с одинаковыми ролями
- Не давайте субагентам ненужный доступ к инструментам
- Не используйте субагентов для простых одношаговых задач
- Не смешивайте разные зоны ответственности в одном промпте субагента
- Не забывайте передавать необходимый контекст

### Лучшие практики для системного промпта

1. **Конкретно определяйте роль**

2. **Четко определяйте приоритеты**

3. **Указывайте формат вывода**

4. **Включайте шаги действий**

### Стратегия доступа к инструментам

1. **Начинайте с ограничений**: начинайте только с необходимых инструментов
2. **Расширяйте только при необходимости**: добавляйте инструменты по мере появления требований
3. **Read-only, когда возможно**: используйте Read/Grep для агентов анализа
4. **Изолированное выполнение**: ограничивайте команды Bash конкретными паттернами

---

## Примеры субагентов в этой папке

Эта папка содержит готовые к использованию примеры субагентов:

### 1. Ревьюер кода (`code-reviewer.md`)

**Назначение**: комплексный анализ качества и поддерживаемости кода

**Инструменты**: Read, Grep, Glob, Bash

**Специализация**:
- Обнаружение уязвимостей безопасности
- Выявление возможностей оптимизации производительности
- Оценка поддерживаемости кода
- Анализ покрытия тестами

**Используйте, когда**: вам нужны автоматизированные code reviews с фокусом на качество и безопасность

---

### 2. Инженер по тестированию (`test-engineer.md`)

**Назначение**: стратегия тестирования, анализ покрытия и автоматизированное тестирование

**Инструменты**: Read, Write, Bash, Grep

**Специализация**:
- Создание unit tests
- Проектирование integration tests
- Выявление edge cases
- Анализ покрытия (цель >80%)

**Используйте, когда**: вам нужно создать комплексный набор тестов или провести анализ покрытия

---

### 3. Автор документации (`documentation-writer.md`)

**Назначение**: техническая документация, API-документация и пользовательские руководства

**Инструменты**: Read, Write, Grep

**Специализация**:
- Документация API endpoints
- Создание пользовательских руководств
- Архитектурная документация
- Улучшение комментариев в коде

**Используйте, когда**: вам нужно создать или обновить документацию проекта

---

### 4. Ревьюер безопасности (`secure-reviewer.md`)

**Назначение**: code review с фокусом на безопасность и минимальными правами

**Инструменты**: Read, Grep

**Специализация**:
- Обнаружение уязвимостей безопасности
- Проблемы аутентификации/авторизации
- Риски раскрытия данных
- Выявление injection-атак

**Используйте, когда**: вам нужны аудиты безопасности без возможности внесения изменений

---

### 5. Агент реализации (`implementation-agent.md`)

**Назначение**: полные возможности реализации для разработки функций

**Инструменты**: Read, Write, Edit, Bash, Grep, Glob

**Специализация**:
- Реализация функций
- Генерация кода
- Выполнение сборки и тестов
- Изменение кодовой базы

**Используйте, когда**: вам нужен субагент для end-to-end реализации функций

---

### 6. Отладчик (`debugger.md`)

**Назначение**: специалист по отладке ошибок, падений тестов и неожиданного поведения

**Инструменты**: Read, Edit, Bash, Grep, Glob

**Специализация**:
- Анализ первопричин
- Исследование ошибок
- Устранение падений тестов
- Реализация минимального исправления

**Используйте, когда**: вы сталкиваетесь с багами, ошибками или неожиданным поведением

---

### 7. Data Scientist (`data-scientist.md`)

**Назначение**: эксперт по анализу данных для SQL queries и data insights

**Инструменты**: Bash, Read, Write

**Специализация**:
- Оптимизация SQL queries
- Операции BigQuery
- Анализ и визуализация данных
- Статистические insights

**Используйте, когда**: вам нужен анализ данных, SQL queries или операции BigQuery

---

### 8. Ревьюер чистого кода (`clean-code-reviewer.md`)

**Назначение**: ревью читаемости и поддерживаемости в соответствии с принципами clean-code

**Инструменты**: Read, Grep, Glob, Bash

**Специализация**:
- Именование, длина функций и количество аргументов
- Дублирование и мертвый код
- Качество комментариев и намерение
- Структурная ясность вместо излишней хитрости

**Используйте, когда**: вам нужен проход по стилю и поддерживаемости отдельно от ревью корректности

---

### 9. Оптимизатор производительности (`performance-optimizer.md`)

**Назначение**: выявление и устранение узких мест производительности

**Инструменты**: Read, Edit, Bash, Grep, Glob

**Специализация**:
- Алгоритмическая сложность и hot paths
- Выделение памяти и утечки
- Кэширование и оптимизация queries
- Узкие места concurrency и I/O

**Используйте, когда**: код измеримо медленный и вам нужна целевая оптимизация

---

## Инструкции по установке

### Метод 1: попросить Claude (рекомендуется)

Опишите субагента, который вам нужен, и позвольте Claude создать файл:

</query>
```text
Create a project-level subagent that runs tests and fixes failures.
Give it access to Bash, Read, Edit, and Grep.

# Navigate to your project
cd /path/to/your/project

# Create agents directory if it doesn't exist
mkdir -p .claude/agents

# Copy all agent files from this folder
cp /path/to/04-subagents/*.md .claude/agents/

# Remove the README (not needed in .claude/agents)
rm .claude/agents/README.md

# Create user agents directory
mkdir -p ~/.claude/agents

# Copy agents
cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/
cp /path/to/04-subagents/debugger.md ~/.claude/agents/
# ... copy others as needed

ls .claude/agents/

project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md
│       ├── test-engineer.md
│       ├── documentation-writer.md
│       ├── secure-reviewer.md
│       ├── implementation-agent.md
│       ├── debugger.md
│       ├── data-scientist.md
│       ├── clean-code-reviewer.md
│       └── performance-optimizer.md
└── ...

Subagents -->|Use| Memory
Subagents -->|Query| MCP
Subagents -->|Isolated| Context["Clean Context<br/>Window"]

Текущая дата: вторник, 4 августа 2026 г.

<query>

---

## Наблюдаемость

&gt; **Добавлено в v2.1.139.**

API-запросы, исходящие от субагента, несут два дополнительных HTTP-заголовка, чтобы трейсы и логи можно было сопоставить с запустившей их сессией:

</query>
| Header | Description |
|--------|-------------|
| `x-claude-code-agent-id` | UUID of the subagent making the request. |
| `x-claude-code-parent-agent-id` | UUID of the agent that dispatched this subagent (the main agent, or a higher-level subagent in a chain). |
Те же идентификаторы доступны в OpenTelemetry-спанах `claude_code.llm_request` как атрибуты `claude.code.agent.id` и `claude.code.agent.parent_id`. Используйте их, чтобы:

- Относить расходы на API к конкретному типу субагента, а не к родительской сессии
- Восстанавливать цепочку вызовов агентов постфактум (`parent_id` образует дерево)
- Настраивать оповещения о вышедших из-под контроля субагентах (например, один `agent.id`, на который приходится >50% расходов сессии)

Полную настройку экспортёра см. в разделе OpenTelemetry в [Расширенные возможности → Телеметрия](../09-advanced-features/README.md).

## Дополнительные ресурсы

- [Официальная документация по субагентам](https://code.claude.com/docs/en/sub-agents)
- [Справочник по CLI](https://code.claude.com/docs/en/cli-reference) - флаг `--agents` и другие опции CLI
- [Руководство по плагинам](../07-plugins/) - для объединения агентов с другими возможностями
- [Руководство по skills](../03-skills/) - для автоматически вызываемых возможностей
- [Руководство по памяти](../02-memory/) - для сохранения контекста между сессиями
- [Руководство по hooks](../06-hooks/) - для автоматизации, управляемой событиями

---

**Последнее обновление**: 29 июля 2026 г.
**Версия Claude Code**: 2.1.220
**Источники**:
- https://code.claude.com/docs/en/sub-agents
- https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
- https://code.claude.com/docs/en/cli-reference
- https://code.claude.com/docs/en/agent-teams
- https://code.claude.com/docs/en/changelog#2-1-172
- https://code.claude.com/docs/en/changelog
- https://github.com/anthropics/claude-code/releases/tag/v2.1.117
- https://github.com/anthropics/claude-code/releases/tag/v2.1.131
- https://github.com/anthropics/claude-code/releases/tag/v2.1.138
- https://github.com/anthropics/claude-code/releases/tag/v2.1.139
- https://github.com/anthropics/claude-code/releases/tag/v2.1.140
- https://code.claude.com/docs/en/model-config
**Совместимые модели**: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5