---
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
experimental:  # Optional - experimental settings block
  cacheTtl: "1h"  # Cache TTL for this subagent: "5m" or "1h" (v2.1.248+)
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

---
name: feature-builder
isolation: worktree
description: Implements features in an isolated git worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

---
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_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

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

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

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

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

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

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

### Дополнительные настройки

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

---

## Когда использовать subagent-ов
| 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 |
Текущая дата: воскресенье, 6 сентября 2026 г.

<query>

---

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

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

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

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

### Лучшие практики для System Prompt

1. **Конкретно опишите роль**

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

3. **Укажите формат вывода**

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

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

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

---

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

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

### 1. Code Reviewer (`code-reviewer.md`)

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

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

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

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

---

### 2. Test Engineer (`test-engineer.md`)

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

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

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

**Когда использовать**: когда вам нужно создать комплексный test suite или проанализировать покрытие

---

### 3. Documentation Writer (`documentation-writer.md`)

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

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

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

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

---

### 4. Secure Reviewer (`secure-reviewer.md`)

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

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

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

**Когда использовать**: когда вам нужны security audits без возможностей модификации

---

### 5. Implementation Agent (`implementation-agent.md`)

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

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

**Специализация**:
- Реализация features
- Генерация кода
- Выполнение build и тестов
- Модификация codebase

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

---

### 6. Debugger (`debugger.md`)

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

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

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

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

---

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

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

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

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

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

---

### 8. Clean Code Reviewer (`clean-code-reviewer.md`)

**Назначение**: review читаемости и maintainability по принципам clean-code

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

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

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

---

### 9. Performance Optimizer (`performance-optimizer.md`)

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

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

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

**Когда использовать**: когда код измеримо медленный и вам нужна targeted optimization

---

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

### Метод 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"]

Текущая дата: воскресенье, 6 сентября 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` приходится &gt;50% расходов сессии)

Полную настройку экспортера см. в разделе OpenTelemetry в [Advanced Features → Telemetry](../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/) - для автоматизации на основе событий

---

**Последнее обновление**: 6 сентября 2026 г.
**Версия Claude Code**: 2.1.263
**Источники**:
- 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