子代理是对 Claude Code / Claude Agent 生态系统最有用的增强之一：它们让你把复杂的工作流拆分为更小的、专精的 AI “队友”，保留主线程上下文，并安全地限制工具访问。本文解释子代理是什么、如何创建和调用它们（CLI、文件系统和 SDK）、构建它们时应遵循的设计原则，以及可复制改造的具体示例代码。
什么是子代理？
子代理是一种预先配置、范围狭窄的 AI 助手，Claude Code（或 Claude Agent SDK）可以将工作委派给它。每个子代理：
- 具有唯一名称和清晰的用途描述。
- 在与主对话分离的独立上下文窗口中运行（因此冗长的细节不会污染编排器的上下文）。
- 可配置为仅使用有限的工具（文件读写、bash、grep、MCP 工具等），并可指定模型选择。
- 包含系统提示（子代理的角色与指令），用于引导行为与约束。
这些特性使子代理非常适合令牌消耗大的任务（研究、检索大型日志）、安全敏感的任务（扫描或潜在破坏性的工具）或重复且规范明确的任务（风格检查、测试运行）。
Anthropic 一直在快速迭代：Claude Code CLI 和 Agent SDK 已重构并扩展为 Claude Agent SDK，引入了插件支持用于打包代理及相关自定义项（斜杠命令、MCP 服务器、钩子），而 Skills 提供了一种在 Claude.ai、Claude Code 和 Agent SDK 之间复用领域工作流的方式。这些更新让团队与项目间共享、安装和版本化子代理更为容易。如果你计划构建生产级工作流，应评估插件/Skills 的打包方式以及基于 SDK 的部署模式。
子代理为何重要
它们之所以立刻有用的三个原因：
- 上下文保持 —— 冗长或嘈杂的搜索、测试运行或扫描在子代理内进行，而不会淹没主上下文。这减少了令牌浪费，也让结果更易于推理。
- 专业化专长 —— 你可以在针对任务定制的系统提示中编码领域知识与行为（例如，一个专注于密钥、依赖问题和不安全 shell 用法的
security-auditor）。 - 更安全的权限 —— 按子代理限制工具可用性可降低影响范围（文档审查者可能仅有只读工具；测试运行者有
Bash但没有Edit）。 - 并行化：你可以并发启动多个子代理（例如：
style-checker、security-scanner、test-runner），然后收集它们的简要结果 —— 对昂贵、独立的检查是巨大加成。
在 Claude Code 中使用子代理的先决条件
在开始构建子代理之前，请确保具备以下条件：
1) 安装并认证 Claude Code
安装 Claude Code CLI 或使用 Web/IDE 集成。CometAPI 的快速入门与设置文档列出了支持的安装方法（npm 全局包或原生安装器），并展示如何使用 claude --version / claude doctor 验证安装。你还需要一个 CometAPI 账号（如快速入门中所述，使用 CometAPI 的密钥访问 Claude code 比官方模型更便宜也更便捷）。
2) Node/环境（适用于某些安装路径）与基础 shell 工具
如果通过 npm 包安装，你需要具备 Node.js（示例中常见为 Node 18+）。若计划使用 Agent SDK（JavaScript/TypeScript 或 Python），你需要在项目中安装 SDK 依赖。许多教程假设使用标准开发工具（git、bash，可选用于 GitHub 工作流的 gh CLI）。
3) 项目布局与 CLAUDE.md
最佳实践是在仓库层级保留辅助文档（CLAUDE.md），并将项目范围的代理置于 .claude/agents/ 下，便于团队成员继承。CLAUDE.md 文件会自动被拉入 Claude 的上下文，并帮助在各会话中一致地引导行为；每个子代理是一个带 YAML frontmatter 的 Markdown 文件。最小示例：
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.
Return results in JSON with fields: summary, issues.
name是小写标识符。description指导自动调用与匹配。tools限制工具访问（省略则继承全部）。model可以是sonnet、opus、haiku或inherit。
4) 权限与 MCP 服务器（可选但常见）
如果你的工作流使用 Model Context Protocol（MCP）服务器或外部工具（Puppeteer、Sentry、自定义 REST 工具），请确保 MCP 服务器已配置并可达。对于敏感操作（写入、bash、git commit），请谨慎制定允许列表，并基于每个代理的 tools 进行范围限定。
如何在 Claude Code 中创建子代理
你可以通过三种主要方式创建子代理：交互式 CLI（/agents）、作为文件系统中的 Markdown 文件，或通过 Agent SDK 以编程方式创建。以下是分步选项：
Claude Code 支持三种实用的子代理创建方式：
- 交互式 CLI
/agents界面 —— 在会话内迭代创建最快。 - 基于文件系统 —— 在
.claude/agents/（项目级）或~/.claude/agents/（用户级）中创建带 YAML frontmatter 的 Markdown 文件。项目级代理优先级更高。 - 编程式（Agent SDK） —— 在调用
query()时通过agents参数在代码中定义子代理；推荐用于 SDK 驱动的应用。当需要动态创建或嵌入到应用中时，这种方式最理想。
快速交互流程（推荐的第一步）
- 在终端启动 Claude Code 或在 VS Code 打开命令面板。
- 使用斜杠命令运行子代理界面：
/agents
- 选择“Create New Agent”，选择项目级或用户级作用域，填写名称/描述/工具/系统提示并保存。你可以先用 Claude 生成草稿，再进行细化。一旦保存，该代理即可在
/agents中使用，且可显式或自动调用。
基于文件系统的子代理（Markdown + YAML frontmatter）
子代理以带 YAML frontmatter 的 Markdown 文件存储。放置位置：
- 项目作用域：
.claude/agents/*.md（优先级最高） - 用户作用域：
~/.claude/agents/*.md
基础文件结构：
---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash # optional; omit to inherit
model: sonnet # optional; or 'inherit'
---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet
一些实现注意事项：
name必须为小写并使用连字符。- 省略
tools将让子代理继承主线程的全部工具；显式列出工具可实施最小权限模型。 - 使用
model: 'inherit'可与主线程行为保持一致，或指定模型别名（如sonnet、opus、haiku）。
CLI 中的 JSON 定义（临时/会话内使用）
你可以在启动会话时内联定义临时子代理：
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer.",
"prompt": "You are a senior code reviewer. Focus on security and best practices.",
"tools": ,
"model": "sonnet"
}
}'
CLI 定义的代理适用于脚本化运行或实验；它们的优先级低于项目级代理，但高于用户级代理。
编程式定义（Agent SDK —— 推荐用于应用）
如果你正在构建应用或自动化流程，请通过 Agent SDK 的 agents 参数以编程方式定义子代理（这是最集成的选项）。示例（TypeScript）：
import { query } from '@anthropic-ai/claude-agent-sdk';
async function runReview() {
const result = await query({
prompt: "Assess the authentication module for security issues",
options: {
agents: {
"code-reviewer": {
description: "Expert code review specialist",
prompt: `You are a code review specialist...`,
tools: ,
model: "sonnet"
},
"test-runner": {
description: "Runs the test suite and analyzes failures",
prompt: `You run tests and summarize failures...`,
tools: ,
model: "sonnet"
}
}
}
});
console.log(result);
}
如果你偏好文件系统模式，SDK 也会加载 .claude/agents/ 中的代理文件。对于动态工作流和 CI 集成，编程式代理非常强大。
对于 Python，claude-agent-sdk 包提供类似模式：你可以使用 query() 或 ClaudeSDKClient 并以编程方式配置选项、工具和 MCP 服务器。参见 Python SDK 仓库的快速开始示例。
如何调用子代理
自动委派
当用户提示与某个子代理的用途匹配时，Claude Code 可以自动选择该子代理。这对于在后台编排中让主代理自动将任务路由到合适的专家非常有用。依赖清晰的子代理描述和聚焦的系统提示，可提高自动选择的准确性。
显式调用（为清晰性所推荐）
你可以在对话中显式调用某个代理：
> Use the code-reviewer subagent to check my recent changes
显式调用具有确定性，推荐用于希望避免意外委派的生产流程。
SDK 编排器模式
SDK 应用中的常见模式：
- Fork + 汇总：并行启动多个子代理，收集每个代理的简洁答案，然后由主代理进行总结/合并。
- 监督循环：编排器分配任务给子代理，检查结果，并决定接受或请求重新计算/澄清。
- 沙箱执行：将潜在危险的能力（部署、运行脚本）交给受严格约束的代理，并在执行前要求显式的人类审批钩子。
这些模式可映射到使用 Agent SDK 的会话管理、钩子与 MCP 工具的实际实现。
如何让子代理更有用、安全且可组合
1) 单一职责与清晰提示
每个子代理都应有一个清晰的目标与系统提示，明确边界、成功标准与输出格式。如果期望输出是结构化的（JSON、项目符号列表、代码补丁），请精确指示子代理，以减少解析错误。
2) 工具的最小权限
仅授予子代理所需的工具。例如，文档审查者不需要 Write 或 Bash。默认使用只读，必要时显式提升工具权限。这样可降低风险并简化审计。
3) 返回紧凑、结构化的输出
子代理应返回简洁的最终答案，而不是冗长的思考过程。常见模式是：在子代理上下文内执行重工作，然后返回简短摘要及附件（补丁、文件引用、JSON）。这最大化了对编排器的上下文效率。
4) 可测试性与版本化
将子代理文件纳入版本控制，创建在小输入上运行的 CI 测试，并固定模型与工具集。如果依赖 Skills 和插件，请采用插件市场/版本化模式来管理升级与回滚。
5) 审计钩子与人类参与的检查点
使用 SDK 钩子拦截工具调用（PreToolUse 钩子），并对破坏性操作要求人工批准。记录所有工具调用以支持可重放审计。SDK 提供钩子与权限机制以支持此模式。
应用示例 —— 一个小型、类生产的管线
下面是一个紧凑示例，展示典型组件：一个文件系统代理、一个使用两个代理（一个用于审查，一个用于测试）的 SDK 调用，以及一个简单的编排。
1) 文件系统代理：.claude/agents/code-reviewer.md
---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
"summary": "one-line summary",
"issues": ,
"recommended_changes":
}
2) 编程式编排（Node.js）
import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';
async function runPipeline() {
const result = query({
prompt: 'Run PR checks: security review then unit tests.',
options: {
agents: {
'code-reviewer': {
description: 'Use PROACTIVELY after code changes; output JSON with issues.',
prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
tools: ,
model: 'sonnet'
},
'test-runner': {
description: 'Run test suite and summarize failing tests.',
prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
tools:
}
}
}
});
for await (const message of result) {
// Implement streaming logic: messages may include subagent outputs
console.log(message);
}
}
runPipeline().catch(console.error);
注意：code-reviewer 存储在仓库中，供团队复用；SDK 调用演示了编程式代理的优先级与 tools 的范围限定可防止意外写入。
高阶主题与模式
动态代理配置
创建参数化的代理工厂，根据环境（开发 vs 生产）或严重级别（如 strict vs balanced 安全模式）选择模型与工具集。SDK 示例展示了如何在运行时生成代理定义。
并行化
并行启动多个只读分析代理（风格、安全、测试覆盖率），并在主线程中聚合它们的 JSON 输出。这能显著缩短大型仓库的总耗时。
插件提供的代理
插件可以随插件清单打包子代理；它们会与自定义代理一起出现在 /agents 中，并可显式调用。用此方式在团队间分发标准化代理。
最推荐在何处使用 Claude Code CLI
令人振奋的是，CometAPI 现已全面支持强大的 Claude Code CLI。 你只需安装 Claude Code，并使用获取的 Comet API 密钥与基础地址进行认证，即可在 Claude Code 上使用 Comet API 的模型。
为什么通过 CometAPI 使用 Claude Code？
顶级人工智能能力：使用专为开发者打造的模型，轻松生成、调试与优化代码。
- 灵活的模型选择：我们提供全面的模型组合，助你更顺畅地开发。
- 无缝集成：API 始终可用。几分钟内将 Claude Code 直接集成到你现有的工作流。
- 通过 CometAPI 使用 Claude Code 将更省成本。CometAPI 提供的 Claude API 比官方价格便宜 20%，并随官方更新最新模型。
准备好使用 Claude Code CLI 了吗？请参阅 API 指南 获取详细说明。
如果你想了解更多 AI 技巧、指南与资讯，请关注我们的 VK、X 和 Discord！
另请参阅 如何通过 CometAPI 安装并运行 Claude Code？
最后思考
将子代理视为可复用、可版本化的微型人格。小步起步：为一个仓库创建 doc-reviewer 和 test-runner，将它们检入 .claude/agents/，并使用无头 claude -p 在 CI 中自动化。迭代你的提示，添加结构化输出，并收紧工具权限。
最有用的心智模型是：把 Claude 想象为项目经理，把子代理视为团队中的专家。经理清晰地委派任务，聚合专家的交付物，并撰写最终报告。随着时间推移，你会看到在可靠性、可测试性以及自动化大块开发者工作流的能力方面的改进。