Claude Code的Agent创建与应用

Claude Code 提供了强大的智能体（Agent）系统，允许开发者创建具有特定角色、专业知识和行为模式的自定义 AI 助手。本教程详细介绍 Agent 的概念体系、配置文件结构、创建流程和实战应用，帮助您从零开始构建专属的智能编程助手，提升开发效率。

本文不讨论广义的"Agent"概念，而是专注于解析 Claude Code 的 Agent 系统。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• Claude Code安装及配置国内大模型完整教程，确保 Claude Code 已正确安装并可正常使用。
• Agent概念详解，此教程详细介绍了 Agent 的基本概念，本教程关于此内容不再赘述。

资源下载

• 示例项目travel-planner网盘下载地址，包含本教程全部 Agent 示例文件。

1. 什么是 Claude Code Agent

1.1 Agent 的概念

在 Claude Code 中，Agent（智能体） 是一个拥有独立角色定义、专业知识体系和行为模式的 AI 助手实例。与通用的 Claude Code 对话不同，Agent 被赋予了特定的身份定位、能力边界和交互规则，使其能够：

• 聚焦：只关注某一类任务（如代码审查、文档编写）
• 专业：按照预设的质量标准和流程规范工作
• 垂直：拥有特定技术栈或业务场景的专业知识
• 一致：每次调用都产出风格统一的成果

1.2 Agent 与普通对话的区别

2. Agent 系统架构

2.1 架构总览

Claude Code 的 Agent 系统由以下几个核心组件构成：

2.2 Agent 的定义结构

每个 Agent 定义文件是一个 Markdown 文件，由两部分组成：

第一部分：前端元数据（Frontmatter）

位于文件开头的 --- 分隔块中，使用 YAML 格式定义 Agent 的基本属性：

---
name: 旅行规划师
description: 当您需要制定旅行计划、推荐景点、规划行程路线时使用此Agent
model: sonnet
color: green
---

第二部分：指令体（Instructions Body）

位于 Frontmatter 之后，使用 Markdown 格式编写 Agent 的行为规则和专业知识：

您是一位经验丰富的旅行规划师，热爱探索世界各地的独特文化和美食。
您最擅长的是根据旅行者的兴趣、预算和时间，设计出既充实又不赶路的行程。

## 工作流程
1. 了解需求：询问旅行目的地、天数、预算、同行人员
2. 主题定位：根据兴趣确定行程主题
3. 行程设计：每日安排核心活动
...

元数据字段说明

2.3 Agent 选择器的工作原理

当用户输入请求时，Claude Code 的 Agent 选择器会执行以下匹配流程：

1. 扫描定义：遍历 .claude/agents/ 目录下所有 Agent 定义文件
2. 语义匹配：将用户请求与每个 Agent 的 description 字段进行语义相似度匹配
3. 选择最优：选择匹配度最高的 Agent
4. 加载指令：将选中 Agent 的指令体作为系统提示加载到当前会话

匹配成功后，Agent 携带其专属角色和指令开始工作。

description 字段中的语义描述越精确，Agent 被正确选中的概率越高。可以在描述中添加 <example> 标签来提供示例场景，帮助选择器更准确匹配。

3. Claude Code 内置 Agent

Claude Code 提供了多种内置 Agent，每种都有其特定的能力边界和最佳使用场景。

3.1 Agent 类型一览

3.2 各类型详解

general-purpose（通用）

能力范围：所有工具均可使用，可执行代码读写、命令执行、文件操作等全部功能。

适用场景：

- 日常编码任务         - Bug修复          - 功能开发
- 代码重构             - 项目初始化       - 依赖管理

Explore（探索）

能力范围：只读模式，可使用 Glob、Grep、Read、WebFetch、WebSearch 等搜索和读取工具，不能使用 Edit、Write 等写入操作。

适用场景：

- 大规模代码库搜索    - 文件查找与定位    - 命名规范扫描
- 项目结构分析        - 代码模式挖掘      - 技术调研

Plan（规划）

能力范围：与 Explore 相同的只读能力，专注于架构分析和实现规划。

适用场景：

- 功能设计文档        - 技术方案评审      - 架构选型分析
- 实施步骤规划        - 风险评估          - 多方案对比

claude-code-guide（Claude Code 指南）

能力范围：专业解答 Claude Code 相关功能问题，包括 CLI 命令、API 使用、配置管理、IDE 集成等。

适用场景：

- "如何配置settings.json？"        - "Claude Code支持哪些模型？"
- "如何使用/help命令？"            - "怎样设置快捷键？"
- "MCP服务器如何配置？"            - "如何切换模型？"

4. 创建自定义 Agent

4.1 环境准备

确保 Claude Code 已全局安装并且项目已初始化：

# 验证 Claude Code 安装
claude --version

# 进入项目目录
cd your-project

4.2 创建 Agents 目录

在项目根目录下创建 Agent 定义目录：

# 创建 agents 目录
mkdir -p .claude/agents

4.3 编写第一个 Agent

让我们创建一个旅行规划师 Agent，这是一个任何人都能理解的生活化场景。在 .claude/agents/ 目录下创建 travel-planner.md，该 Agent 负责制定旅行计划、推荐景点、规划行程路线，提供个性化、有温度的旅行建议。

完整文件内容请前往网盘中的 travel-planner/.claude/agents/travel-planner.md 查看。

4.4 Agent 文件规范详解

命名规范

description 编写技巧

description 字段是 Agent 选择器匹配用户意图的关键。好的描述应该：

# 正确的描述 - 清晰、具体、包含触发场景
description: >
  当您需要制定旅行计划、推荐景点、规划行程路线时使用此Agent。
  提供个性化、有温度的旅行建议，而非简单的景点列表。

# 错误的描述 - 模糊、泛泛而谈
description: 旅行规划

进阶技巧：在描述中使用 <example> 标签提供匹配示例：

description: >
  当您需要制定旅行计划时使用此Agent。
  <example>
  用户：'帮我规划一次日本旅行'
  助手：'我将使用旅行规划师Agent来设计您的行程。'
  </example>
  <example>
  用户：'成都有什么好玩的？'
  助手：'让我用旅行规划师Agent为您推荐。'
  </example>

4.5 指令体编写原则

编写 Agent 的指令体（Instructions Body）时，请遵循以下原则：

原则一：明确角色定位

您是一位经验丰富的旅行规划师，热爱探索世界各地的独特文化和美食。
您最擅长的是根据旅行者的兴趣、预算和时间，设计出既充实又不赶路的行程。

原则二：细化工作规则

## 工作流程
1. **了解需求**：询问旅行目的地、天数、预算、同行人员
2. **主题定位**：根据兴趣确定行程主题
3. **行程设计**：每日安排3-4个核心活动
4. **实用建议**：推荐当地美食、交通方式
5. **输出格式**：按天列表呈现

原则三：约束输出格式

## 输出要求
每次回复必须包含：
- 一句温暖的开场白
- 以表格或列表呈现的行程
- 至少一个"当地人推荐"的小众地点
- 最后的"温馨提示"版块

原则四：提供示例互动

## 示例互动
用户："我想去成都玩3天"
您的回复：[完整的示例回复]

4.6 测试 Agent

创建完成后，在 Claude Code 中输入触发 Agent 的请求：

# 在 Claude Code 中测试
"请帮我规划一次日本7天旅行"

# 或者更精确地触发
"我需要旅行建议，能帮我设计一下成都3天的行程吗？"

如果 Agent 选择器正确匹配，Claude Code 会自动加载 travel-planner.md 中的指令，以"旅行规划师"的身份回应。

5. 多 Agent 协作与工作流

5.1 Agent 的协作模式

在实际场景中，复杂任务往往需要多个 Agent 协同完成。Claude Code 支持以下几种协作模式：

5.2 实战：旅行规划的多 Agent 并行协作

让我们通过一个完整示例，展示如何让多个 Agent 并行工作，一次性为用户提供全方位的旅行规划方案。

场景设定

用户提出需求："帮我规划一次日本7天旅行，预算中等，喜欢文化体验"

系统将同时启动 4 个 Agent，分别从不同维度提供服务。

说明：该并行协作演示需通过工作流（Workflow）或多 Agent 编排机制实现，Claude Code 默认不会因单条用户请求自动并行启动多个 Agent。以下示例用于展示多 Agent 协作的设计思路，帮助理解各 Agent 的角色分工。

Agent 1：行程设计师

负责规划每日行程路线、景点安排、时间节奏，擅长优化路线减少交通时间。

完整文件内容请前往网盘中的 travel-planner/.claude/agents/itinerary-designer.md 查看。

Agent 2：预算规划师

负责计算旅行总预算、每日花费分配，提供省钱技巧，擅长在保证体验的前提下控制成本。

完整文件内容请前往网盘中的 travel-planner/.claude/agents/budget-planner.md 查看。

Agent 3：文化体验官

负责推荐当地特色体验、隐藏美食和文化礼仪，让旅行从"看风景"升级为"体验生活"。

完整文件内容请前往网盘中的 travel-planner/.claude/agents/culture-guide.md 查看。

Agent 4：应急管家

负责识别旅行风险、提供应急预案和必备物品清单，让旅行既安心又从容。

完整文件内容请前往网盘中的 travel-planner/.claude/agents/emergency-manager.md 查看。

5.3 完整执行演示

用户输入

"帮我规划一次日本7天旅行，预算中等，喜欢文化体验"

系统响应

完整输出

# 日本7天深度旅行计划

## 行程概览（行程设计师）
**路线**：东京(2天) → 箱根(1天) → 京都(3天) → 大阪(1天)

### Day 1: 东京·现代与传统
- 上午 9:00 浅草寺 + 仲见世商店街
- 中午 12:00 上野公园附近吃鳗鱼饭
- 下午 14:00 上野国立博物馆
- 傍晚 17:00 晴空塔观夜景
- 晚上 推荐：浅草居酒屋一条街

...

5.5 多 Agent 并行协作的核心设计原则

通过上述示例，我们可以总结出设计并行 Agent 的关键原则：

原则一：职责正交（不重叠）

每个 Agent 负责一个独立维度，互不干扰：

正确的职责划分：
- 行程设计师 → 每日路线和景点
- 预算规划师 → 费用明细和省钱技巧
- 文化体验官 → 深度体验和文化礼仪
- 应急管家 → 风险预案和必备物品

错误的职责划分（互相重叠）：
- 行程设计师 → 每日路线和费用
- 预算规划师 → 费用和景点推荐
- 文化体验官 → 景点和礼仪

原则二：输出统一（便于汇总）

所有 Agent 使用统一的数据结构和格式规范，便于主会话整合：

正确：统一输出规范
- 每个Agent都用Markdown格式
- 每个部分都有清晰的一级标题
- 使用统一的分区标题体系（如"预算""文化""应急"）
- 数据部分使用表格呈现

错误：混乱的输出
- 有的用JSON，有的用纯文本
- 标题层级不一致
- 数据格式五花八门

原则三：互不依赖（可并行）

每个 Agent 的输入只依赖用户原始需求，不依赖其他 Agent 的输出：

正确：独立输入
- 行程设计师 ← 用户需求
- 预算规划师 ← 用户需求
- 文化体验官 ← 用户需求
- 应急管家 ← 用户需求

错误：链式依赖（无法并行）
- 预算规划师 ← 行程设计师 ← 用户需求（串行）

原则四：主会话负责整合

并行 Agent 生成内容后，由主会话负责统一整合和呈现：

## 主会话的职责
1. 接收用户请求
2. 并行调用所有相关 Agent
3. 等待所有 Agent 完成
4. 将各 Agent 输出按预定模板整合
5. 一次性呈现给用户

5.6 可套用此模式的更多场景

旅行规划的多 Agent 并行模式可以轻松迁移到其他领域：

5.7 团队级 Agent 共享

在团队协作中，可以将 Agent 定义文件纳入版本控制，实现团队标准化：

# 在项目根目录下
your-project/
├── .claude/
│   ├── agents/
│   │   ├── travel-planner.md      # 旅行规划师
│   │   ├── budget-planner.md      # 预算规划师
│   │   ├── culture-guide.md       # 文化体验官
│   │   └── emergency-manager.md   # 应急管家
│   └── settings.json              # 项目级配置
└── ...

团队共享的好处： 1. 标准化：所有团队成员使用相同的 Agent 配置，输出质量一致 2. 持续改进：Agent 指令通过 PR 评审不断完善 3. 新人友好：新成员通过项目中的 Agent 定义快速了解团队规范 4. 零配置：克隆项目后 Agent 自动可用

6. 总结

本教程全面介绍了 Claude Code Agent 智能体的创建与应用：

核心知识回顾： 1. Agent 是什么：具有特定角色和专业知识体系的 AI 助手 2. 如何创建：在 .claude/agents/ 目录下编写 Markdown 定义文件 3. 如何优化：精细设计 description 和指令体，提高匹配精度 4. 多 Agent 并行协作：让多个专家同时工作，一次性提供全方位解决方案 5. 实战应用：旅行规划、求职面试、健身计划、装修设计等 6. 团队协作：通过版本控制共享和持续改进 Agent 配置

建议的学习路径： 1. 从复制生活化 Agent 模板开始（如旅行规划师），快速理解结构 2. 为你的日常需求创建第一个专属 Agent 3. 尝试设计 2-3 个互补的 Agent，体验并行协作的威力 4. 逐步扩展到工作场景（代码审查、文档生成等） 5. 在团队内推广 Agent 标准化配置

Agent 的价值在于： - 个体 Agent：将专业知识和规范固化到 AI 助手的指令中，让每次交互都产出高质量成果 - 多 Agent 并行：让多个专家同时从不同维度解决问题，效率提升 3 倍以上

随着使用经验的积累，你的 Agent 配置将越来越精准，成为个人和团队效率的重要加速器。

7. 常见问题与解决方案

Q1: Agent 没有被正确匹配

问题：输入请求后，Claude Code 没有使用预期的 Agent。

解决方案：

1. 检查 description 字段是否清晰描述了触发场景
2. 确保描述中包含明确的"当...时使用此Agent"句式
3. 检查文件名是否有拼写错误
4. 确认 Agent 文件是否在正确的目录 (.claude/agents/)
5. 检查 frontmatter 格式是否正确（--- 分隔符必须完整）
6. 尝试手动指定：'请以 [Agent名称] 的身份来分析'

Q2: Agent 指令不生效

问题：Agent 被正确匹配，但没有完全遵循指令。

解决方案：

1. 检查指令的清晰度——规则是否明确可执行？
2. 将模糊的要求改为具体的检查清单
3. 为输出格式提供模板示例
4. 减少指令数量，优先保证核心规则被遵守
5. 检查是否有项目级 settings.json 中的配置冲突

Q3: Agent 输出格式不符合预期

问题：Agent 没有按照指定的格式输出。

解决方案：

1. 提供完整的输出模板示例
2. 在指令中明确说明"必须严格按照此格式输出"
3. 使用示范示例（例如表格、代码块加标注）
4. 减少可选字段，增加必需字段约束

Q4: 多个 Agent 之间混淆

问题：设计了多个功能相近的 Agent，经常匹配错误。

解决方案：

1. 检查各 Agent 的 description 是否有重叠
2. 为相似功能的 Agent 添加更明确的区分描述
3. 考虑合并功能高度重叠的 Agent
4. 推荐一个项目中的 Agent 数量控制在 5-8 个以内

Q5: 团队 Agent 如何同步

问题：团队成员如何共享和更新 Agent 配置？

解决方案：

# 1. 将 .claude/agents/ 目录纳入 git 版本控制
git add .claude/agents/
git commit -m "feat(agents): 添加旅行规划相关Agent"

# 2. 通过 PR 评审 Agent 配置变更
# 3. 团队成员拉取最新配置后自动生效
git pull

Q6: Agent 中的敏感信息处理

问题：Agent 指令中涉及 API Key 等敏感信息。

解决方案：

1. 在 Agent 指令中使用占位符而非实际密钥
2. 敏感配置放在 .claude/settings.json 中（加入 .gitignore）
3. 使用环境变量注入：通过 env 字段配置
4. 示例：
   {
     "env": {
       "API_KEY": "${API_KEY}"  // 从系统环境变量读取
     }
   }

Q7: Frontmatter 格式错误

问题：创建 Agent 后无法正常加载。

解决方案：

1. 确保 frontmatter 使用完整的 --- 分隔符（前后各三个短横线）
2. YAML 格式必须正确（冒号后面有空格）
3. 多行文本使用 > 或 | 符号（YAML 块标量）
4. 常见错误示例：

   错误：name:旅行规划师   （冒号后无空格）
   正确：name: 旅行规划师  （冒号后有空格）

   错误：缺少结束的 ---
   正确：前后都有 ---