创建自定义 subagents

Posted on 三月 6, 2026

创建自定义 subagents

在 Claude Code 中创建和使用专门的 AI subagents，用于特定任务的工作流和改进的上下文管理。

什么是 Subagents

Subagents 是处理特定类型任务的专门 AI 助手。每个 subagent 在自己的 context window 中运行，具有：

自定义系统提示
特定的工具访问权限
独立的权限

Subagents 帮助您

保留上下文：将探索和保持在主对话之外
强制执行约束：限制 subagent 可以使用的工具
跨项目重用配置：使用用户级 subagents
专门化行为：为特定领域使用专注的系统提示
控制成本：将任务路由到更快、更便宜的模型

内置 subagents

Explore

Model: Haiku（快速、低延迟）
Tools: 只读工具
Purpose: 文件发现、代码搜索、代码库探索

Plan

Model: 从主对话继承
Tools: 只读工具
Purpose: 用于规划的代码库研究

General-purpose

Model: 从主对话继承
Tools: 所有工具
Purpose: 复杂研究、多步骤操作、代码修改

快速入门：创建您的第一个 subagent

使用 /agents 命令

在 Claude Code 中运行：/agents
选择 Create new agent
选择 User-level 或 Project-level
描述 subagent 或使用 Claude 生成
选择工具和模型
保存并尝试

手动创建 subagent 文件

Subagents 在带有 YAML frontmatter 的 Markdown 文件中定义：

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

配置 subagents

Subagent 范围

Location	Scope	Priority
`--agents` CLI 标志	当前会话	1（最高）
`.claude/agents/`	当前项目	2
`~/.claude/agents/`	所有项目	3
插件的 `agents/` 目录	启用插件的位置	4（最低）

支持的 frontmatter 字段

Field	Required	Description
`name`	Yes	唯一标识符（小写字母和连字符）
`description`	Yes	Claude 何时应委托给此 subagent
`tools`	No	Subagent 可以使用的工具
`disallowedTools`	No	要拒绝的工具
`model`	No	`sonnet`、`opus`、`haiku` 或 `inherit`
`permissionMode`	No	权限模式
`maxTurns`	No	subagent 停止前的最大代理轮数
`skills`	No	预加载的 skills
`mcpServers`	No	此 subagent 可用的 MCP servers
`hooks`	No	Lifecycle hooks
`memory`	No	持久内存范围：`user`、`project` 或 `local`
`background`	No	始终作为后台任务运行
`isolation`	No	设置为 `worktree` 进行隔离

选择模型

Model alias: sonnet、opus、haiku
inherit: 使用与主对话相同的模型
Omitted: 默认为 inherit

控制 subagent 能力

可用工具

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

限制可以生成的 subagents

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

权限模式

Mode	Behavior
`default`	标准权限检查
`acceptEdits`	自动接受文件编辑
`dontAsk`	自动拒绝权限提示
`bypassPermissions`	跳过所有权限检查
`plan`	Plan mode（只读探索）

启用持久内存

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

You are a code reviewer. Update your agent memory with patterns
and conventions you discover.

Scope	Location	何时使用
`user`	`~/.claude/agent-memory/<name>/`	所有项目中记住学习
`project`	`.claude/agent-memory/<name>/`	特定于项目，可共享
`local`	`.claude/agent-memory-local/<name>/`	特定于项目，不检入

为 subagents 定义 hooks

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

使用 subagents

理解自动委托

Claude 根据任务描述和 subagent 的 description 字段自动委托。

明确请求特定的 subagent：

1	Use the code-reviewer subagent to look at my recent changes

在前台或后台运行

前台 subagents 阻塞主对话直到完成
后台 subagents 在您继续工作时并发运行

常见模式

隔离高容量操作

1	Use a subagent to run the test suite and report only the failing tests

并行运行研究

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

链接 subagents

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

恢复 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]

示例 subagents

代码审查者

---
name: code-reviewer
description: Expert code review specialist. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer.

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

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

调试器

---
name: debugger
description: Debugging specialist for errors and test failures.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

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
- Specific code fix
- Testing approach

数据库查询验证器

---
name: db-reader
description: Execute read-only database queries.
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.

验证脚本：

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

if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

后续步骤

本文档来自 Claude Code 官方文档