Agent 系统详解:从使用到自定义开发

0 阅读18分钟

引言:从"单兵作战"到"团队协作"

使用 Claude Code 一段时间后,你可能发现了一个有趣的现象:

  • 场景 1: 让 AI 探索一个陌生的代码库,它会自动切换到"探索模式",系统地分析目录结构和代码关系
  • 场景 2: 让 AI 设计一个复杂功能,它会进入"计划模式",先讨论方案再动手实现
  • 场景 3: 让 AI 写一篇技术博客,它会自动使用"技术写作模式",文风和结构都更加专业

这些"模式"背后,就是 Agent 系统在工作。

💡 什么是 Agent?

简单来说,Agent 就是 具有特定技能和知识的专业 AI "队友"

主 Claude Code (你)
   ├─ Explore Agent (代码库探索专家)
   ├─ Plan Agent (架构设计专家)
   ├─ Backend Architect Agent (后端架构师)
   ├─ Tech Blog Writer Agent (技术写作专家)
   ├─ Code Reviewer Agent (代码审查专家)
   └─ 你的自定义 Agent (...)

类比理解:

  • Claude Code 本身像一个全能工程师,什么都能做但不一定最专业
  • Agent 就像请来的专家顾问,在特定领域有深厚经验
  • 你可以根据任务需要,随时"召唤"合适的专家来帮忙

本文核心内容:

  1. Agent 系统的工作原理
  2. 内置 Agent 的使用(Explore、Plan、Backend Architect 等)
  3. 在 Claude Code 中创建自定义 Agent
  4. 获取官方和第三方 Agent
  5. 优秀的 Agent 框架介绍(BMAD-Method)
  6. 开发中实用的 Agent 示例(问题分析、代码提交等)

"一个人可以走得很快,一群专家可以走得更远"


一、Agent 系统概述

1.1 什么是 Agent?

Agent(代理)是一个具有特定能力和专业知识的 AI 实例,它可以:

  1. 专注于特定领域: 如代码探索、架构设计、技术写作
  2. 拥有专业知识: 在其领域有深度的 Prompt 和工具配置
  3. 独立完成任务: 可以被主 Claude Code 调用,独立工作
  4. 返回结果: 完成任务后返回结果给主 Claude Code

Agent vs 普通 Claude Code

特性普通 Claude CodeAgent
知识范围通用特定领域专业知识
工具权限根据需要配置针对任务优化的工具集
工作方式直接交互被调用后独立工作
上下文共享主对话上下文独立上下文
适用场景日常开发任务特定专业任务

1.2 Agent 与主对话的关系

08-01-agent-relationship.png

工作流程:

  1. 你向主 Claude Code 提出需求
  2. 主 Claude Code 判断是否需要调用 Agent
  3. 如需要,启动对应的 Agent
  4. Agent 独立工作,完成任务
  5. Agent 返回结果给主 Claude Code
  6. 主 Claude Code 整合结果,继续处理

1.3 Agent 的工作原理

核心组成

一个 Agent 由以下部分组成:

# agent.yaml 示例
name: code-reviewer
description: 专业的代码审查 Agent
version: 1.0.0

# Agent 的专业知识(System Prompt)
system_prompt: |
  你是一位经验丰富的代码审查专家,专注于:
  1. 代码质量和可维护性
  2. 潜在的 Bug 和安全问题
  3. 性能优化建议
  4. 最佳实践和设计模式

# Agent 可以使用的工具
tools:
  - Read          # 读取代码文件
  - Grep          # 搜索代码
  - Glob          # 查找文件
  # 不包含 Write/Edit (只读权限)

# Agent 的工作参数
parameters:
  max_iterations: 10
  focus_areas:
    - security
    - performance
    - maintainability

执行流程

1. 主 Claude Code 收到任务
   "请审查 LoginActivity.kt 的代码质量"

2. 决定调用 Agent
   判断这是代码审查任务 → 调用 code-reviewer Agent

3. Agent 启动
   - 加载 system_prompt (审查专家角色)
   - 配置工具权限 (只读)
   - 设置工作参数

4. Agent 独立工作
   - 读取 LoginActivity.kt
   - 分析代码结构
   - 检查常见问题
   - 生成审查报告

5. 返回结果
   Agent 将审查报告返回给主 Claude Code

6. 主 Claude Code 呈现
   将结果格式化并展示给用户

二、内置 Agent 详解

Claude Code 内置了多个专业 Agent,覆盖常见的开发场景。

2.1 Explore Agent - 代码库探索专家

专长: 系统地探索和理解陌生代码库

使用场景:

  • 接手一个新项目,需要快速了解代码结构
  • 查找特定功能的实现位置
  • 理解模块间的依赖关系

调用方式:

# 自动调用(Claude Code 自动判断)
User: 帮我分析这个 Android 项目的架构

# 手动调用(使用 Task 工具)
User: 使用 Explore Agent 分析 app/src 目录的结构

工作流程:

1. 扫描目录结构
   ├─ app/
   │   ├─ src/main/java/com/example/
   │   │   ├─ ui/
   │   │   ├─ data/
   │   │   └─ domain/
   │   └─ build.gradle.kts

2. 识别架构模式
   → 检测到 MVVM 架构
   → ui/ 包含 Activity 和 ViewModel
   → data/ 包含 Repository 和数据源
   → domain/ 包含业务逻辑

3. 分析关键文件
   → MainActivity.kt (入口)
   → AppDatabase.kt (数据库)
   → ApiService.kt (网络接口)

4. 生成探索报告
   ✅ 项目使用 MVVM 架构
   ✅ 采用 Kotlin + Jetpack Compose
   ✅ 网络层使用 Retrofit
   ✅ 数据库使用 Room

最佳实践:

# ✅ 好的使用方式
"探索 app/src 目录,重点关注用户认证相关的代码"

# ✅ 指定探索深度
"快速浏览整个项目结构,不需要深入每个文件"

# ❌ 避免
"分析所有代码" (范围太大,耗时长)

2.2 Plan Agent - 架构设计专家

专长: 方案设计、技术选型、任务分解

使用场景:

  • 实现复杂功能前,需要先设计方案
  • 重构现有模块,需要评估风险和制定计划
  • 技术选型决策,需要对比不同方案

调用方式:

# 进入 Plan 模式
User: /plan 实现用户多租户支持功能

# Plan Agent 自动启动,进入方案设计阶段

工作流程:

阶段 1: 需求理解
  → 什么是多租户?
  → 需要隔离哪些数据?
  → 性能要求如何?

阶段 2: 方案设计
  → 数据库隔离策略(Schema 隔离 vs 数据表隔离)
  → 租户识别机制(域名 vs Token)
  → 权限控制方案

阶段 3: 技术选型
  → 对比 Row-Level Security vs 应用层隔离
  → 评估性能影响
  → 选择最优方案

阶段 4: 任务分解
  1. 数据库 schema 设计
  2. 租户识别中间件
  3. 权限检查拦截器
  4. 现有 API 适配
  5. 测试用例编写

阶段 5: 风险评估
  ⚠️ 现有数据迁移风险
  ⚠️ 性能影响需要测试
  ⚠️ 跨租户数据泄漏风险

生成的 Plan 文档示例:

# 多租户支持实现方案

## 1. 方案概述

采用 Schema 隔离 + Row-Level Security 的混合方案:
- 核心数据使用 Schema 隔离(完全隔离)
- 共享数据使用 RLS (灵活控制)

## 2. 架构设计

\`\`\`
请求 → 租户识别中间件 → RLS Context 设置 → 业务逻辑
\`\`\`

## 3. 实施步骤

### 3.1 数据库设计 (2天)
- [ ] 创建 tenants 表
- [ ] 为每个租户创建独立 schema
- [ ] 配置 RLS 策略

### 3.2 中间件开发 (1天)
- [ ] 实现租户识别逻辑
- [ ] 集成到请求处理链

### 3.3 API 适配 (3天)
- [ ] 更新所有 API 添加租户过滤
- [ ] 测试跨租户隔离

## 4. 风险与应对

| 风险 | 影响 | 应对措施 |
|:---|:---|:---|
| 数据迁移 | 高 | 编写迁移脚本,分批迁移 |
| 性能下降 | 中 | 添加索引,压力测试 |

## 5. 验收标准

- ✅ 租户间数据完全隔离
- ✅ 性能下降 < 10%
- ✅ 通过安全审计
\`\`\`

2.3 Backend Architect Agent - 后端架构师

专长: 后端系统架构设计、API 设计、数据库设计

使用场景:

  • 设计 RESTful API
  • 设计数据库 schema
  • 评审系统架构

示例:

User: 设计一个订单系统的 API 和数据库

Backend Architect Agent 工作:
1. API 设计
   POST   /api/orders          # 创建订单
   GET    /api/orders/:id      # 查询订单
   PATCH  /api/orders/:id      # 更新订单
   DELETE /api/orders/:id      # 取消订单

2. 数据库设计
   orders 表:
   - id (UUID, PK)
   - user_id (FK → users)
   - status (enum: pending, confirmed, shipped, delivered, cancelled)
   - total_amount (decimal)
   - created_at, updated_at

   order_items 表:
   - id (UUID, PK)
   - order_id (FK → orders)
   - product_id (FK → products)
   - quantity (integer)
   - price (decimal)

3. 业务逻辑
   - 订单状态机
   - 库存检查和锁定
   - 支付集成

2.4 Tech Blog Writer Agent - 技术写作专家

专长: 技术博客写作、文档编写

使用场景:

  • 撰写技术博客
  • 编写 API 文档
  • 生成 README

示例:

User: 为这个开源项目写一篇介绍博客

Tech Blog Writer Agent:
1. 分析项目特点
2. 确定目标读者
3. 规划文章结构:
   - 引言(痛点引入)
   - 核心特性
   - 使用示例
   - 最佳实践
   - 总结
4. 撰写正文(专业 + 易读)
5. 添加代码示例和配图

2.5 其他内置 Agent

Agent 名称专长领域典型场景
Test Writer Agent测试用例编写生成单元测试、集成测试
Refactor Agent代码重构优化代码结构,消除坏味道
Debug Agent问题诊断分析 Bug,定位根因
Performance Agent性能优化分析瓶颈,提出优化方案
Security Agent安全审计检查安全漏洞,提供修复建议

三、Agent 的调用方式

3.1 自动调用(推荐)

Claude Code 会根据任务类型自动选择合适的 Agent:

# 示例 1: 自动调用 Explore Agent
User: 这个项目是什么架构?
→ Claude Code 自动调用 Explore Agent 分析代码库

# 示例 2: 自动调用 Plan Agent
User: 实现一个复杂的推荐系统
→ Claude Code 进入 Plan 模式,调用 Plan Agent

# 示例 3: 自动调用 Backend Architect Agent
User: 设计用户权限系统的数据库 schema
→ Claude Code 调用 Backend Architect Agent

优点:

  • ✅ 无需记忆命令
  • ✅ AI 自动选择最合适的 Agent
  • ✅ 用户体验更自然

3.2 手动调用(精确控制)

使用 Task 工具明确指定 Agent:

# 语法
使用 <Agent名称> 执行 <任务描述>

# 示例 1
User: 使用 Explore Agent 分析 src/main/java 目录,重点关注数据层

# 示例 2
User: 使用 Code Reviewer Agent 审查 PaymentService.kt

# 示例 3
User: 使用 Tech Blog Writer Agent 为这个功能写一篇介绍文章

优点:

  • ✅ 精确控制使用哪个 Agent
  • ✅ 适合特定场景

3.3 参数配置

调用 Agent 时可以传递参数:

# 配置 Explore Agent 的探索深度
User: 使用 Explore Agent 快速扫描项目结构(depth=2)

# 配置 Plan Agent 的输出格式
User: 使用 Plan Agent 设计方案,生成 Markdown 格式的文档

# 配置 Code Reviewer Agent 的审查重点
User: 使用 Code Reviewer Agent 审查代码,重点关注安全问题

四、创建自定义 Agent

4.1 为什么需要自定义 Agent?

内置 Agent 虽然强大,但可能无法满足你的特定需求:

  • 领域专业知识: 你的团队有特定的技术栈和最佳实践
  • 工作流定制: 你希望 Agent 按照团队的工作流程工作
  • 专有工具: 你需要集成公司内部的工具和服务

示例场景:

  • Android 内存泄漏分析 Agent
  • 代码提交规范检查 Agent
  • Jira 任务同步 Agent
  • 性能监控数据分析 Agent

4.2 Agent 的文件格式

Claude Code 的自定义 Agent 采用单文件格式,非常简洁:

~/.claude/agents/
├── android-memory-analyzer.md    # 一个 Agent 就是一个 .md 文件
├── code-reviewer.md
├── crash-analyzer.md
└── backend-architect.md

文件结构:

---
name: agent-name
description: Agent 的描述,用于触发匹配和显示
model: sonnet  # 可选: sonnet/opus/haiku
---

[System Prompt 内容 - Agent 的专业知识和角色定义]

核心组成:

部分说明必填
nameAgent 的唯一标识符
description描述信息,用于自动匹配和展示
model使用的模型 (sonnet/opus/haiku)
正文System Prompt,定义 Agent 的专业知识

4.3 创建 Agent 的两种方式

方式一: 使用 /agent 命令 AI 辅助创建(推荐)

Claude Code 提供了 /agent 命令,可以让 AI 帮你自动生成 Agent:

# 在 Claude Code 中输入
User: /agent 创建一个 Android 内存泄漏分析专家

# Claude Code 会自动:
# 1. 分析你的需求
# 2. 生成 Agent 文件内容
# 3. 保存到 ~/.claude/agents/ 目录
# 4. 你只需要审查和微调即可

优点:

  • ✅ 快速生成,省去手写
  • ✅ AI 会根据需求自动设计合适的 prompt
  • ✅ 格式规范,不易出错
  • ✅ 生成后可以手动修改优化

示例对话:

User: /agent 创建一个代码审查专家,专注于安全漏洞检测

Claude Code: 我来帮你创建一个专注于安全漏洞检测的代码审查 Agent...
[自动生成 security-reviewer.md 文件]

生成完成! Agent 已保存到 ~/.claude/agents/security-reviewer.md
你可以通过以下方式使用:
- 自然语言: "帮我审查这段代码的安全性"
- 直接调用: "使用 security-reviewer 审查 LoginService.kt"

方式二: 手动创建 .md 文件

如果你想完全自定义,可以手动创建 Agent 文件:

# 创建 Agent 文件
touch ~/.claude/agents/android-memory-analyzer.md

4.4 完整示例: Android 内存泄漏分析 Agent

---
name: android-memory-analyzer
description: 专门分析 Android 应用的内存泄漏问题,结合 LeakCanary 日志和 Profiler dump 进行诊断。当用户提到内存泄漏、LeakCanary、OOM、内存分析等关键词时自动触发。
model: sonnet
---

你是一位资深的 Android 性能优化专家,专注于内存泄漏问题的诊断和修复。

## 你的专业技能

### 1. LeakCanary 日志分析
- 快速定位泄漏的对象类型
- 分析引用链,找到 GC Root
- 识别常见的泄漏模式

### 2. 常见内存泄漏模式识别

#### 模式 1: Activity 持有静态引用
\`\`\`kotlin
// ❌ 泄漏代码
companion object {
    var context: Context? = null  // 静态变量持有 Activity
}

// ✅ 修复方案
companion object {
    var context: WeakReference<Context>? = null
}
\`\`\`

#### 模式 2: 非静态内部类持有外部引用
\`\`\`kotlin
// ❌ 泄漏代码
class MainActivity : AppCompatActivity() {
    inner class MyHandler : Handler() {
        // 隐式持有 MainActivity 引用
    }
}

// ✅ 修复方案
class MainActivity : AppCompatActivity() {
    class MyHandler(activity: WeakReference<MainActivity>) : Handler() {
        // 使用弱引用
    }
}
\`\`\`

#### 模式 3: 监听器未注销
\`\`\`kotlin
// ❌ 泄漏代码
override fun onCreate(savedInstanceState: Bundle?) {
    EventBus.getDefault().register(this)
    // 忘记在 onDestroy 中注销
}

// ✅ 修复方案
override fun onDestroy() {
    super.onDestroy()
    EventBus.getDefault().unregister(this)
}
\`\`\`

### 3. Heap Dump 分析
- 使用 Memory Profiler 的 dump 文件
- 分析对象引用关系
- 计算泄漏对象占用的内存大小

## 工作流程

1. **收集信息**
   - 读取 LeakCanary 日志
   - 查看 Profiler heap dump (如果有)
   - 搜索相关的代码文件

2. **定位问题**
   - 识别泄漏的对象类型(Activity、Fragment、Context 等)
   - 分析引用链,找到持有引用的地方
   - 确定泄漏原因(静态引用、监听器未注销、异步任务等)

3. **提供修复方案**
   - 给出具体的代码修改建议
   - 解释为什么这样修改可以解决泄漏
   - 提供预防同类问题的建议

4. **验证修复**
   - 建议如何验证修复是否有效
   - 推荐使用的工具和方法

## 输出格式

# 内存泄漏分析报告

## 问题概述
[简要描述泄漏情况]

## 泄漏对象
- 类型: [Activity/Fragment/...]
- 实例数量: [X 个]
- 占用内存: [XX MB]

## 引用链分析
[对象] → [持有者1] → [持有者2] → ... → GC Root

## 根本原因
[详细解释泄漏原因]

## 修复方案
[具体的修复代码]

## 预防措施
[如何避免类似问题]

## 注意事项

- 始终以用户友好的方式解释技术问题
- 提供可直接应用的代码示例
- 如果不确定,说明需要更多信息

4.5 更多实用 Agent 示例

示例 1: 后端架构师 Agent

---
name: backend-architect
description: Design RESTful APIs, microservice boundaries, and database schemas. Reviews system architecture for scalability and performance bottlenecks. Use PROACTIVELY when creating new backend services or APIs.
model: sonnet
---

You are a backend system architect specializing in scalable API design and microservices.

## Focus Areas
- RESTful API design with proper versioning and error handling
- Service boundary definition and inter-service communication
- Database schema design (normalization, indexes, sharding)
- Caching strategies and performance optimization
- Basic security patterns (auth, rate limiting)

## Approach
1. Start with clear service boundaries
2. Design APIs contract-first
3. Consider data consistency requirements
4. Plan for horizontal scaling from day one
5. Keep it simple - avoid premature optimization

## Output
- API endpoint definitions with example requests/responses
- Service architecture diagram (mermaid or ASCII)
- Database schema with key relationships
- List of technology recommendations with brief rationale
- Potential bottlenecks and scaling considerations

Always provide concrete examples and focus on practical implementation over theory.

示例 2: 代码审查 Agent

---
name: code-reviewer
description: 专业的代码审查专家,专注于代码质量、安全漏洞、性能问题和最佳实践。当用户需要代码审查、Review、检查代码质量时自动触发。
model: sonnet
---

你是一位经验丰富的代码审查专家,专注于以下方面:

## 审查维度

### 1. 代码质量
- 命名规范和可读性
- 函数/方法长度和复杂度
- 代码重复和抽象程度
- 注释的必要性和准确性

### 2. 安全问题
- SQL 注入
- XSS 攻击
- 敏感信息泄露
- 权限控制漏洞

### 3. 性能问题
- N+1 查询问题
- 内存泄漏风险
- 不必要的循环和计算
- 缓存使用

### 4. 最佳实践
- SOLID 原则
- 设计模式适用性
- 错误处理
- 单元测试覆盖

## 输出格式

使用以下格式输出审查结果:

## 审查摘要
- 总体评价: [优秀/良好/需改进/不合格]
- 发现问题: X 个 (严重: X, 一般: X, 建议: X)

## 问题列表

### 🔴 严重问题
[问题描述和修复建议]

### 🟡 一般问题
[问题描述和修复建议]

### 🟢 优化建议
[建议内容]

## 审查原则
- 客观公正,有理有据
- 给出具体的修复建议,而不是泛泛批评
- 肯定代码中的优点
- 区分"必须修复"和"建议优化"

4.6 使用自定义 Agent

Agent 文件保存到 ~/.claude/agents/ 目录后,Claude Code 会自动识别并加载。

使用方式:

# 方式 1: 自然语言触发(根据 description 自动匹配)
User: 帮我分析这个内存泄漏日志
→ Claude Code 根据关键词自动匹配 android-memory-analyzer Agent

# 方式 2: 明确指定 Agent
User: 使用 android-memory-analyzer 分析 leakcanary.log

# 方式 3: 在 description 中配置触发示例
# 在 description 中可以添加示例来帮助 Claude Code 更准确地匹配

description 编写技巧:

# 好的 description 示例
description: 专门分析 Android 应用的内存泄漏问题,结合 LeakCanary 日志和 Profiler dump 进行诊断。当用户提到内存泄漏、LeakCanary、OOM、内存分析等关键词时自动触发。示例:<example>用户:"帮我分析这个 LeakCanary 日志",助手:"我将使用内存泄漏分析 Agent 来帮你诊断问题"</example>

# 包含的要素:
# 1. 核心功能描述
# 2. 触发关键词
# 3. 使用示例(可选但推荐)

五、优秀的 Agent 框架:BMAD-Method

5.1 什么是 BMAD-Method?

BMAD (Business-Modeling-Architecture-Development) 是一个专业的 Agent 协作框架,模拟真实软件团队的工作模式。

核心理念:

  • 每个角色都是一个专业 Agent
  • Agent 之间协作完成复杂任务
  • 遵循规范的软件工程流程

5.2 BMAD Agent 角色体系

08-02-bmad-framework.png

角色说明:

角色Agent 名称职责
产品负责人bmad-po需求分析、PRD 编写、用户故事
项目经理bmad-pm项目规划、进度跟踪、风险管理
架构师bmad-architect架构设计、技术选型、方案评审
Scrum Masterbmad-sm敏捷流程、任务拆分、看板管理
开发工程师bmad-dev代码实现、单元测试、代码审查
QA 工程师bmad-qa测试用例、自动化测试、质量报告

5.3 BMAD 工作流示例

场景:开发一个用户反馈功能

1 阶段:需求分析
  ┌─────────────┐
  │ bmad-po     │ "用户反馈功能需求分析"
  └──────┬──────┘
         │
         ▼
  生成 PRD:
  - 用户可以提交反馈(文字+图片)
  - 管理员可以查看和回复
  - 反馈分类和优先级

第 2 阶段:项目规划
  ┌─────────────┐
  │ bmad-pm     │ "制定开发计划"
  └──────┬──────┘
         │
         ▼
  项目计划:
  - Sprint 1: 用户提交反馈 (3天)
  - Sprint 2: 管理后台 (5天)
  - Sprint 3: 通知和统计 (2天)

第 3 阶段:架构设计
  ┌─────────────┐
  │bmad-architect│ "设计系统架构"
  └──────┬──────┘
         │
         ▼
  技术方案:
  - API 设计:POST /api/feedback
  - 数据库设计:feedback 表
  - 文件存储:S3/OSS4 阶段:任务拆分
  ┌─────────────┐
  │ bmad-sm     │ "拆分用户故事"
  └──────┬──────┘
         │
         ▼
  用户故事:
  - 作为用户,我可以提交反馈
  - 作为管理员,我可以查看反馈列表
  - 作为管理员,我可以回复反馈

第 5 阶段:开发实现
  ┌─────────────┐
  │ bmad-dev    │ "实现代码"
  └──────┬──────┘
         │
         ▼
  代码实现:
  - FeedbackController.kt
  - FeedbackRepository.kt
  - FeedbackViewModel.kt

第 6 阶段:质量保障
  ┌─────────────┐
  │ bmad-qa     │ "编写测试并验证"
  └──────┬──────┘
         │
         ▼
  测试用例:
  - 单元测试:业务逻辑测试
  - 集成测试:API 测试
  - UI 测试:提交反馈流程

六、总结与展望

6.1 核心收益回顾

通过本文的学习,你掌握了:

  1. Agent 系统的理解

    • Agent 的概念和工作原理
    • Agent 与主 Claude Code 的关系
    • Agent 的执行流程
  2. 自定义 Agent 开发

    • Agent 的文件结构
    • 配置 agent.md
    • 工具权限配置
    • 完整示例:Android 内存泄漏分析 Agent

6.2 Agent 的价值

维度传统开发使用 Agent 后提升
专业深度通用 AI领域专家+300%
工作效率手动探索自动化分析+200%
知识积累分散沉淀为 Agent+∞
团队协作人工配合Agent 协作+150%

6.3 进阶阅读


相关资源

社区资源


🔗 相关文章:


如果这篇文章对你有帮助,欢迎点赞、收藏、分享!有任何问题或建议,欢迎在评论区留言讨论。让我们一起学习,一起成长!

也欢迎访问我的个人主页发现更多宝藏资源