8.2 子代理的创建与配置

面向经管学生、研究者与从业者的 AI 智能体设计教材

8.2 配图

Claude Code 提供三种创建子代理的方式。三者各有适用场景，下表概览：

方式	命令 / 操作	持久性	适用场景
/agents 交互式命令	在对话中输入 /agents	保存到文件	日常创建和管理（推荐）
手动编写 agent.md	在 .claude/agents/ 下创建文件	文件持久化	需要精确控制每个字段
--agents CLI 标志	启动时传入 JSON	仅当前会话	快速测试或自动化脚本

使用 /agents 命令创建

/agents 是管理子代理最直接的入口。在 Claude Code 对话中输入 /agents，会打开一个交互式界面，支持查看、创建、编辑和删除子代理。

创建流程分 8 步：

1. 运行 /agents，选择 Create new agent
2. 选择存储位置：Project（.claude/agents/，仅当前项目）或 Personal（~/.claude/agents/，所有项目可用）
3. 选择 Generate with Claude，用自然语言描述子代理的用途
4. 选择工具权限：只读工具 或 全部工具
5. 选择运行模型：Sonnet / Opus / Haiku
6. 选择背景颜色（用于在界面中区分不同子代理）
7. 配置记忆：User scope / Project scope / None
8. 按 s 或 Enter 保存，或按 e 在编辑器中打开微调

以创建一个财报分析师子代理为例：

▶ Claude Code

/agents

→ Create new agent → Project
→ Generate with Claude

描述：A financial statement analyzer that reads annual reports,
calculates profitability ratios (gross margin, net margin, ROE),
solvency ratios, and operating efficiency metrics.
It should cross-validate figures and flag anomalies above 20%.

→ 选择工具：Read-only tools + Bash(python *)
→ 选择模型：Sonnet
→ 选择颜色：蓝色
→ 记忆：Project scope
→ 按 s 保存

Claude 会根据描述自动生成 name、description 和系统提示词，保存为 .claude/agents/financial-analyzer.md。保存后子代理立即可用，不需要重启会话。

命令行快速查看

在终端运行 claude agents（注意没有斜杠），可以在不启动交互会话的情况下列出所有已配置的子代理，按来源分组显示，并标注同名时哪个处于活跃状态。

手动编写 agent.md 文件

对于需要精确控制每个配置字段的场景，可以直接在 .claude/agents/ 或 ~/.claude/agents/ 目录下创建 Markdown 文件。文件格式是 YAML frontmatter + Markdown 正文，frontmatter 定义元数据和配置，正文就是子代理的系统提示词。

以财报分析师为例：

▶ Agent

---
name: financial-analyzer
description: >
  Analyzes financial statements and calculates key ratios.
  Use when the user asks to analyze financial reports,
  calculate financial ratios, or evaluate company
  financial health.
model: sonnet
tools:
  - Read
  - Grep
  - Bash(python *)
memory: project
---

## 角色定位

你是一位财务报表分析专家。

## 核心职责

1. 提取三大财务报表关键指标
2. 计算盈利能力（毛利率、净利率、ROE）、偿债能力（资产负债率、流动比率）和运营效率（总资产周转率）
3. 进行同比/环比分析，识别异常波动
4. 将分析结果保存到指定路径

## 输出格式

分析结果以 Markdown 表格形式呈现，包含：
- 指标名称、当期值、上期值、同比变化
- 异常指标的文字说明
- 整体财务健康评估

## 质量标准

- 所有数值交叉验证（资产 = 负债 + 所有者权益）
- 计算保留两位小数
- 异常波动（>20%）必须标注并给出可能原因

子代理只接收 agent.md 中的系统提示词和基本环境信息（如工作目录），不会继承主对话的完整系统提示。但它会自动遵循项目的 CLAUDE.md 规则。

手动添加的文件需要重启会话才能加载，或者运行 /agents 立即刷新。

关于 description 字段

description 是 Claude 决定是否委派任务的核心依据。写法上建议用英文，清晰描述该子代理处理什么类型的任务、在什么场景下应该被调用。模糊的描述会导致委派不准确，过于宽泛的描述会导致不该触发时也触发。

完整字段参考

以下是 agent.md frontmatter 支持的全部字段。只有 name 和 description 是必填的，其余均为选填。

字段	类型	必填	说明
name	string	是	唯一标识符，使用小写字母和连字符（kebab-case）
description	string	是	描述何时委派给此子代理，Claude 据此决定是否触发
model	string	否	运行模型：sonnet、opus、haiku、完整模型 ID（如 claude-opus-4-6）或 inherit。默认 inherit
tools	list	否	允许使用的工具白名单。省略则继承主对话全部工具
disallowedTools	list	否	禁止使用的工具黑名单，从继承列表中移除
permissionMode	string	否	权限模式：default、acceptEdits、dontAsk、bypassPermissions、plan
maxTurns	number	否	子代理停止前的最大轮次
skills	list	否	启动时注入子代理上下文的 Skills 列表（完整内容注入，非仅可用）
mcpServers	list	否	此子代理可用的 MCP 服务器（内联定义或引用已配置的服务器名）
hooks	object	否	限定在此子代理范围内的生命周期钩子
memory	string	否	持久记忆作用域：user（跨项目）、project（项目级，可版本控制）、local（项目级，不入版本控制）
background	boolean	否	设为 true 则始终作为后台任务运行。默认 false
effort	string	否	覆盖会话 effort 级别：low、medium、high、max（max 需 Opus 4.6 或更高版本支持）
isolation	string	否	设为 worktree 则在临时 git worktree 中运行，获得仓库隔离副本

工具控制：白名单与黑名单

白名单方式（tools） 明确列出子代理可以使用的工具，未列出的一律不可用：

tools: Read, Grep, Glob, Bash

黑名单方式（disallowedTools） 从继承的工具集中排除特定工具，其余照常使用：

disallowedTools: Write, Edit

这种写法适合只需禁止写操作的场景，比列举所有允许的工具更简洁。如果两者同时设置，Claude Code 先应用 disallowedTools 移除黑名单中的工具，再从剩余工具中解析 tools 白名单。

工具权限的最小化原则

如果子代理的任务只需要读取文件和搜索代码，就不要给它写入权限。工具权限越少，误操作风险越低。一个常见做法是先用只读权限测试，确认需要写入时再放开。

–agents CLI 标志与存储优先级

--agents 标志允许在启动 Claude Code 时通过 JSON 临时定义子代理，仅在当前会话有效，不会写入磁盘。适用于快速测试或自动化脚本：

claude --agents '{
  "earnings-checker": {
    "description": "Validates earnings data extraction",
    "prompt": "你是财报数据校验专家。检查提取的财务数据是否与原始报表一致。",
    "tools": ["Read", "Grep", "Bash"],
    "model": "haiku"
  }
}'

子代理的存储位置决定了可见范围和优先级。当多个位置存在同名子代理时，高优先级的生效：

优先级	位置	作用范围
1（最高）	--agents CLI 标志	当前会话
2	.claude/agents/	当前项目（可版本控制，团队共享）
3	~/.claude/agents/	当前用户所有项目
4（最低）	插件的 agents/ 目录	插件启用处

插件子代理的安全限制

插件中的子代理不支持 hooks、mcpServers 和 permissionMode 字段，这些字段在加载时会被忽略。如果需要这些能力，把 agent 文件复制到 .claude/agents/ 或 ~/.claude/agents/ 中使用。

模型选择策略

不同任务对模型能力的需求不同，合理选择可以在质量和成本之间取得平衡：

模型	写法示例	适用任务
Opus	opus 或 claude-opus-4-6	复杂分析、多步推理、深度写作
Sonnet	sonnet 或 claude-sonnet-4-6	大多数分析和撰写任务
Haiku	haiku	简单的格式转换、数据提取、分类
继承	inherit 或省略	无特殊需求时的默认选择

模型选择不是越强越好，而是要和任务难度匹配。一个常用做法是先用 sonnet 测试，输出质量不足时再切换到 opus。

模型选择技巧

金融数据提取（从年报中抽取特定数值）用 haiku 即可。财务指标的趋势分析和异常识别适合 sonnet。综合多维度数据做投资建议或撰写深度分析报告时，考虑用 opus。