Создание пользовательских subagents

• Сохранять контекст, отделяя исследование и реализацию от основного разговора
• Применять ограничения, ограничивая доступ subagent к определённым инструментам
• Переиспользовать конфигурации в проектах с помощью subagents уровня пользователя
• Специализировать поведение с помощью сфокусированных системных приглашений для конкретных областей
• Контролировать затраты, маршрутизируя задачи на более быстрые и дешёвые модели, такие как Haiku

​

Встроенные subagents

• Чтобы заблокировать определённый встроенный тип, добавьте его в permissions.deny, как показано в Отключение определённых subagents.
• Чтобы предотвратить делегирование Claude к любому subagent, запретите сам инструмент Agent с помощью permissions.deny.
• Чтобы удалить только встроенные subagents Explore и Plan, установите CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude читает и исследует файлы напрямую вместо делегирования им. Требуется Claude Code версии 2.1.198 или позже.
• В неинтерактивном режиме и Agent SDK установите CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 для удаления всех встроенных типов и предоставления только ваших собственных.

​

Quickstart: создание вашего первого subagent

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

​

Настройка subagents

​

Выберите область subagent

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

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"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

​

Напишите файлы subagent

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

​

Поддерживаемые поля frontmatter

​

Выберите модель

• Model alias: Используйте один из доступных псевдонимов: sonnet, opus, haiku или fable
• Full model ID: Используйте полный ID модели, такой как claude-opus-4-8 или claude-sonnet-5. Принимает те же значения, что и флаг --model
• inherit: Используйте ту же модель, что и основной разговор
• Omitted: Если не указано, по умолчанию inherit и использует ту же модель, что и основной разговор

1. Переменная окружения CLAUDE_CODE_SUBAGENT_MODEL, если установлена на псевдоним модели или ID модели
2. Параметр model для конкретного вызова
3. Frontmatter model определения subagent
4. Модель основного разговора

​

Контролируйте возможности subagent

​

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

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, если только permissionMode subagent не является plan
• ScheduleWakeup
• WaitForMcpServers

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

​

Ограничьте, какие subagents могут быть порождены

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

tools: Agent, Read, Bash

​

Область MCP servers для subagent

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

• --strict-mcp-config и --bare
• Enterprise управляемая конфигурация MCP
• allowedMcpServers и deniedMcpServers политики

​

Режимы разрешений

​

Предварительная загрузка skills в subagents

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

​

Включите постоянную память

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

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

• Системное приглашение subagent включает инструкции для чтения и записи в каталог памяти.
• Системное приглашение subagent также включает первые 200 строк или 25KB MEMORY.md в каталоге памяти, в зависимости от того, что меньше, с инструкциями по курированию MEMORY.md, если она превышает этот лимит.
• Инструменты Read, Write и Edit автоматически включаются, чтобы subagent мог управлять своими файлами памяти.

• project — рекомендуемая область по умолчанию. Это делает знания subagent доступными для совместного использования через систему контроля версий.
• Попросите subagent проверить его память перед началом работы: “Review this PR, and check your memory for patterns you’ve seen before.”
• Попросите subagent обновить его память после завершения задачи: “Now that you’re done, save what you learned to your memory.” Со временем это создаёт базу знаний, которая делает subagent более эффективным.
• Включите инструкции по памяти непосредственно в файл markdown subagent, чтобы он активно поддерживал свою собственную базу знаний:
  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

​

Условные правила с hooks

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

​

Отключите конкретные subagents

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

claude --disallowedTools "Agent(Explore)"

​

Определите hooks для subagents

• В frontmatter subagent: Определите hooks, которые запускаются только во время активности этого subagent
• В settings.json: Определите hooks, которые запускаются в основной сессии при запуске или остановке subagents

​

Hooks в frontmatter subagent

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

​

Hooks уровня проекта для событий subagent

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

​

Работа с subagents

​

Поймите автоматическое делегирование

​

Явно вызывайте subagents

• Естественный язык: назовите subagent в вашем приглашении; Claude решает, делегировать ли
• @-упоминание: гарантирует, что subagent запустится для одной задачи
• Сессионный уровень: вся сессия использует системное приглашение, ограничения инструментов и модель этого subagent через флаг --agent или параметр agent

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@"code-reviewer (agent)" look at the auth changes

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

​

Запустите subagents в переднем плане или фоне

• Foreground subagents блокируют основной разговор до завершения. Запросы разрешений передаются вам по мере их возникновения.
• Background subagents работают параллельно, пока вы продолжаете работать. Начиная с v2.1.186, когда фоновый subagent достигает вызова инструмента, требующего разрешения, приглашение появляется в вашей основной сессии и называет subagent, который спрашивает. Одобрите, чтобы позволить subagent продолжить, или нажмите Esc, чтобы отклонить этот вызов инструмента без остановки subagent. До v2.1.186 фоновые subagents автоматически отклоняли любой вызов инструмента, который иначе потребовал бы приглашения.

• Попросите Claude запустить задачу в фоне или в переднем плане
• Нажмите Ctrl+B для фонового выполнения работающей задачи

​

Ошибки API в subagents

• Foreground: если лимит скорости, перегрузка или ошибка сервера прерывает subagent, который уже произвёл выходные данные, инструмент Agent возвращает эти частичные выходные данные с примечанием, что subagent был прерван и не завершил свою задачу. Subagent, который не произвёл ничего, или чьим единственным выходом были вызовы инструментов, завершается с ошибкой Agent terminated early due to an API error, за которой следует деталь ошибки. В v2.1.199 лимит скорости, перегрузка или ошибка сервера, которые прервали форму, содержащую только вызовы инструментов, возвращали пустой частичный результат, содержащий только примечание об отключении вместо этого.
• Background: subagent помечается как неудачный, и сообщение, которое Claude получает при завершении, называет ошибку API и включает последний выход subagent, поэтому частичная работа не теряется.

​

Распространённые паттерны

​

Изолируйте высокообъёмные операции

Use a subagent to run the test suite and report only the failing tests with their error messages

​

Запустите параллельное исследование

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

​

Цепочка subagents

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

​

Выберите между subagents и основным разговором

• Задача требует частого взаимодействия или итеративного уточнения
• Несколько фаз имеют значительный общий контекст, такие как планирование, реализация и тестирование
• Вы вносите быстрое, целевое изменение
• Задержка имеет значение. Subagents начинают с нуля и могут потребовать время для сбора контекста

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

​

Порождайте вложенные subagents

​

Управляйте контекстом subagent

​

Что загружается при запуске

• System prompt: собственное приглашение агента плюс детали окружения, которые добавляет Claude Code, а не полное системное приглашение Claude Code. Пользовательские subagents определяют свои в markdown body или поле prompt. Встроенные агенты имеют предопределённые приглашения.
• Task message: приглашение делегирования, которое Claude пишет при передаче работы.
• CLAUDE.md and memory: каждый уровень иерархии памяти, который загружает основной разговор, включая ~/.claude/CLAUDE.md, правила проекта, CLAUDE.local.md и управляемые файлы политики. Встроенные агенты Explore и Plan пропускают это.
• Git status: снимок, сделанный в начале родительской сессии. Отсутствует, когда рабочая директория не является Git репозиторием или когда includeGitInstructions имеет значение false. Explore и Plan пропускают это независимо.
• Preloaded skills: полное содержание любого навыка, названного в поле skills агента. Встроенные агенты не предзагружают навыки.
• Sibling roster: системное напоминание, в котором перечислены main и каждый другой именованный агент в сессии, каждый является допустимым значением to для SendMessage. Требует Claude Code v2.1.206 или позже. Реестр появляется только когда инструменты subagent включают SendMessage и по крайней мере один другой агент имеет имя, независимо от того, назвал ли его Claude при порождении или он работает как товарищ agent team. Это снимок, сделанный при запуске subagent, поэтому агенты, названные позже, не появляются.

​

Возобновите subagents

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• Компактирование основного разговора: Когда основной разговор компактируется, транскрипты subagent не затрагиваются. Они сохраняются в отдельных файлах.
• Сохранение сессии: Транскрипты subagent сохраняются в пределах их сессии. Вы можете возобновить subagent после перезагрузки Claude Code, возобновив ту же сессию.
• Автоматическая очистка: Транскрипты очищаются на основе параметра cleanupPeriodDays, который по умолчанию составляет 30 дней.

​

Auto-compaction

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

​

Разветвление текущего разговора

• Claude может порождать fork, явно запрашивая тип subagent fork. Порождения без типа subagent по-прежнему используют general-purpose subagent, и именованные subagents, такие как Explore, по-прежнему порождаются как раньше.
• Каждый spawn subagent работает в фоне, будь то fork или именованный subagent. Установите CLAUDE_CODE_DISABLE_BACKGROUND_TASKS на 1, чтобы сохранить spawns синхронными.

/fork draft unit tests for the parser changes so far

​

Наблюдение и управление работающими forks

​

Как forks отличаются от именованных subagents

​

Ограничения

​

Примеры subagents

​

Проверяющий кода

---
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 clear 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 the 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.

​

Валидатор запросов к базе данных

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

chmod +x ./scripts/validate-readonly-query.sh

​

Следующие шаги

• Распространяйте subagents с помощью plugins для совместного использования subagents в командах или проектах
• Запустите Claude Code программно с помощью Agent SDK для CI/CD и автоматизации
• Используйте MCP servers для предоставления subagents доступа к внешним инструментам и данным