ClaudeCode中的Agent系统工作原理、如何使用和自定义开发

主 claude code (你)
   ├─ explore agent (代码库探索专家)
   ├─ plan agent (架构设计专家)
   ├─ backend architect agent (后端架构师)
   ├─ tech blog writer agent (技术写作专家)
   ├─ code reviewer 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 呈现
   将结果格式化并展示给用户

# 自动调用(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 目录,重点关注用户认证相关的代码"

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

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

# 进入 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: 风险评估
  ⚠️ 现有数据迁移风险
  ⚠️ 性能影响需要测试
  ⚠️ 跨租户数据泄漏风险

# 多租户支持实现方案

## 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%
- ✅ 通过安全审计
\`\`\`

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. 业务逻辑
   - 订单状态机
   - 库存检查和锁定
   - 支付集成

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

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

# 示例 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

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

# 示例 1
user: 使用 explore agent 分析 src/main/java 目录,重点关注数据层

# 示例 2
user: 使用 code reviewer agent 审查 paymentservice.kt

# 示例 3
user: 使用 tech blog writer agent 为这个功能写一篇介绍文章

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

# 配置 plan agent 的输出格式
user: 使用 plan agent 设计方案,生成 markdown 格式的文档

# 配置 code reviewer agent 的审查重点
user: 使用 code reviewer 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 的专业知识和角色定义]

# 在 claude code 中输入
user: /agent 创建一个 android 内存泄漏分析专家

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

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

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

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

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

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

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

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

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

## 注意事项

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

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

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

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

## 审查维度

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

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

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

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

## 输出格式

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

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

## 问题列表

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

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

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

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

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

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

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

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

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

第 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/oss

第 4 阶段:任务拆分
  ┌─────────────┐
  │ bmad-sm     │ "拆分用户故事"
  └──────┬──────┘
         │
         ▼
  用户故事:
  - 作为用户,我可以提交反馈
  - 作为管理员,我可以查看反馈列表
  - 作为管理员,我可以回复反馈

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

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