主 Claude Code (你)
   ├─ Explore Agent (代碼庫探索專家)
   ├─ Plan Agent (架構設計專家)
   ├─ Backend Architect Agent (后端架構師)
   ├─ Tech Blog Writer Agent (技術寫作專家)
   ├─ Code Reviewer Agent (代碼審查專家)
   └─ 你的自定義 Agent (...)

# agent.yaml 示例
name: code-reviewer
description: 專業(yè)的代碼審查 Agent
version: 1.0.0

# Agent 的專業(yè)知識(System Prompt)
system_prompt: |
  你是一位經驗豐富的代碼審查專家,專注于:
  1. 代碼質量和可維護性
  2. 潛在的 Bug 和安全問題
  3. 性能優(yōu)化建議
  4. 最佳實踐和設計模式

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

# Agent 的工作參數(shù)
parameters:
  max_iterations: 10
  focus_areas:
    - security
    - performance
    - maintainability

1. 主 Claude Code 收到任務
   "請審查 LoginActivity.kt 的代碼質量"

2. 決定調用 Agent
   判斷這是代碼審查任務 → 調用 code-reviewer Agent

3. Agent 啟動
   - 加載 system_prompt (審查專家角色)
   - 配置工具權限 (只讀)
   - 設置工作參數(shù)

4. Agent 獨立工作
   - 讀取 LoginActivity.kt
   - 分析代碼結構
   - 檢查常見問題
   - 生成審查報告

5. 返回結果
   Agent 將審查報告返回給主 Claude Code

6. 主 Claude Code 呈現(xiàn)
   將結果格式化并展示給用戶

# 自動調用(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 和數(shù)據源
   → domain/ 包含業(yè)務邏輯

3. 分析關鍵文件
   → MainActivity.kt (入口)
   → AppDatabase.kt (數(shù)據庫)
   → ApiService.kt (網絡接口)

4. 生成探索報告
   ? 項目使用 MVVM 架構
   ? 采用 Kotlin + Jetpack Compose
   ? 網絡層使用 Retrofit
   ? 數(shù)據庫使用 Room

# ? 好的使用方式
"探索 app/src 目錄,重點關注用戶認證相關的代碼"

# ? 指定探索深度
"快速瀏覽整個項目結構,不需要深入每個文件"

# ? 避免
"分析所有代碼" (范圍太大,耗時長)

# 進入 Plan 模式
User: /plan 實現(xiàn)用戶多租戶支持功能

# Plan Agent 自動啟動,進入方案設計階段

階段 1: 需求理解
  → 什么是多租戶?
  → 需要隔離哪些數(shù)據?
  → 性能要求如何?

階段 2: 方案設計
  → 數(shù)據庫隔離策略(Schema 隔離 vs 數(shù)據表隔離)
  → 租戶識別機制(域名 vs Token)
  → 權限控制方案

階段 3: 技術選型
  → 對比 Row-Level Security vs 應用層隔離
  → 評估性能影響
  → 選擇最優(yōu)方案

階段 4: 任務分解
  1. 數(shù)據庫 schema 設計
  2. 租戶識別中間件
  3. 權限檢查攔截器
  4. 現(xiàn)有 API 適配
  5. 測試用例編寫

階段 5: 風險評估
  ?? 現(xiàn)有數(shù)據遷移風險
  ?? 性能影響需要測試
  ?? 跨租戶數(shù)據泄漏風險

# 多租戶支持實現(xiàn)方案

## 1. 方案概述

采用 Schema 隔離 + Row-Level Security 的混合方案:
- 核心數(shù)據使用 Schema 隔離(完全隔離)
- 共享數(shù)據使用 RLS (靈活控制)

## 2. 架構設計

\`\`\`
請求 → 租戶識別中間件 → RLS Context 設置 → 業(yè)務邏輯
\`\`\`

## 3. 實施步驟

### 3.1 數(shù)據庫設計 (2天)
- [ ] 創(chuàng)建 tenants 表
- [ ] 為每個租戶創(chuàng)建獨立 schema
- [ ] 配置 RLS 策略

### 3.2 中間件開發(fā) (1天)
- [ ] 實現(xiàn)租戶識別邏輯
- [ ] 集成到請求處理鏈

### 3.3 API 適配 (3天)
- [ ] 更新所有 API 添加租戶過濾
- [ ] 測試跨租戶隔離

## 4. 風險與應對

| 風險 | 影響 | 應對措施 |
|:---|:---|:---|
| 數(shù)據遷移 | 高 | 編寫遷移腳本,分批遷移 |
| 性能下降 | 中 | 添加索引,壓力測試 |

## 5. 驗收標準

- ? 租戶間數(shù)據完全隔離
- ? 性能下降 < 10%
- ? 通過安全審計
\`\`\`

User: 設計一個訂單系統(tǒng)的 API 和數(shù)據庫

Backend Architect Agent 工作:
1. API 設計
   POST   /api/orders          # 創(chuàng)建訂單
   GET    /api/orders/:id      # 查詢訂單
   PATCH  /api/orders/:id      # 更新訂單
   DELETE /api/orders/:id      # 取消訂單

2. 數(shù)據庫設計
   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. 業(yè)務邏輯
   - 訂單狀態(tài)機
   - 庫存檢查和鎖定
   - 支付集成

User: 為這個開源項目寫一篇介紹博客

Tech Blog Writer Agent:
1. 分析項目特點
2. 確定目標讀者
3. 規(guī)劃文章結構:
   - 引言(痛點引入)
   - 核心特性
   - 使用示例
   - 最佳實踐
   - 總結
4. 撰寫正文(專業(yè) + 易讀)
5. 添加代碼示例和配圖

# 示例 1: 自動調用 Explore Agent
User: 這個項目是什么架構?
→ Claude Code 自動調用 Explore Agent 分析代碼庫

# 示例 2: 自動調用 Plan Agent
User: 實現(xiàn)一個復雜的推薦系統(tǒng)
→ Claude Code 進入 Plan 模式,調用 Plan Agent

# 示例 3: 自動調用 Backend Architect Agent
User: 設計用戶權限系統(tǒng)的數(shù)據庫 schema
→ Claude Code 調用 Backend Architect Agent

# 語法
使用 <Agent名稱> 執(zhí)行 <任務描述>

# 示例 1
User: 使用 Explore Agent 分析 src/main/java 目錄,重點關注數(shù)據層

# 示例 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 的描述,用于觸發(fā)匹配和顯示
model: sonnet  # 可選: sonnet/opus/haiku
---

[System Prompt 內容 - Agent 的專業(yè)知識和角色定義]

# 在 Claude Code 中輸入
User: /agent 創(chuàng)建一個 Android 內存泄漏分析專家

# Claude Code 會自動:
# 1. 分析你的需求
# 2. 生成 Agent 文件內容
# 3. 保存到 ~/.claude/agents/ 目錄
# 4. 你只需要審查和微調即可

User: /agent 創(chuàng)建一個代碼審查專家,專注于安全漏洞檢測

Claude Code: 我來幫你創(chuàng)建一個專注于安全漏洞檢測的代碼審查 Agent...
[自動生成 security-reviewer.md 文件]

生成完成! Agent 已保存到 ~/.claude/agents/security-reviewer.md
你可以通過以下方式使用:
- 自然語言: "幫我審查這段代碼的安全性"
- 直接調用: "使用 security-reviewer 審查 LoginService.kt"

# 創(chuàng)建 Agent 文件
touch ~/.claude/agents/android-memory-analyzer.md

---
name: android-memory-analyzer
description: 專門分析 Android 應用的內存泄漏問題,結合 LeakCanary 日志和 Profiler dump 進行診斷。當用戶提到內存泄漏、LeakCanary、OOM、內存分析等關鍵詞時自動觸發(fā)。
model: sonnet
---

你是一位資深的 Android 性能優(yōu)化專家,專注于內存泄漏問題的診斷和修復。

## 你的專業(yè)技能

### 1. LeakCanary 日志分析
- 快速定位泄漏的對象類型
- 分析引用鏈,找到 GC Root
- 識別常見的泄漏模式

### 2. 常見內存泄漏模式識別

#### 模式 1: Activity 持有靜態(tài)引用
\`\`\`kotlin
// ? 泄漏代碼
companion object {
    var context: Context? = null  // 靜態(tài)變量持有 Activity
}

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

#### 模式 2: 非靜態(tài)內部類持有外部引用
\`\`\`kotlin
// ? 泄漏代碼
class MainActivity : AppCompatActivity() {
    inner class MyHandler : Handler() {
        // 隱式持有 MainActivity 引用
    }
}

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

#### 模式 3: 監(jiān)聽器未注銷
\`\`\`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 等)
   - 分析引用鏈,找到持有引用的地方
   - 確定泄漏原因(靜態(tài)引用、監(jiān)聽器未注銷、異步任務等)

3. **提供修復方案**
   - 給出具體的代碼修改建議
   - 解釋為什么這樣修改可以解決泄漏
   - 提供預防同類問題的建議

4. **驗證修復**
   - 建議如何驗證修復是否有效
   - 推薦使用的工具和方法

## 輸出格式

# 內存泄漏分析報告

## 問題概述
[簡要描述泄漏情況]

## 泄漏對象
- 類型: [Activity/Fragment/...]
- 實例數(shù)量: [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: 專業(yè)的代碼審查專家,專注于代碼質量、安全漏洞、性能問題和最佳實踐。當用戶需要代碼審查、Review、檢查代碼質量時自動觸發(fā)。
model: sonnet
---

你是一位經驗豐富的代碼審查專家,專注于以下方面:

## 審查維度

### 1. 代碼質量
- 命名規(guī)范和可讀性
- 函數(shù)/方法長度和復雜度
- 代碼重復和抽象程度
- 注釋的必要性和準確性

### 2. 安全問題
- SQL 注入
- XSS 攻擊
- 敏感信息泄露
- 權限控制漏洞

### 3. 性能問題
- N+1 查詢問題
- 內存泄漏風險
- 不必要的循環(huán)和計算
- 緩存使用

### 4. 最佳實踐
- SOLID 原則
- 設計模式適用性
- 錯誤處理
- 單元測試覆蓋

## 輸出格式

使用以下格式輸出審查結果:

## 審查摘要
- 總體評價: [優(yōu)秀/良好/需改進/不合格]
- 發(fā)現(xiàn)問題: X 個 (嚴重: X, 一般: X, 建議: X)

## 問題列表

### ?? 嚴重問題
[問題描述和修復建議]

### ?? 一般問題
[問題描述和修復建議]

### ?? 優(yōu)化建議
[建議內容]

## 審查原則
- 客觀公正,有理有據
- 給出具體的修復建議,而不是泛泛批評
- 肯定代碼中的優(yōu)點
- 區(qū)分"必須修復"和"建議優(yōu)化"

# 方式 1: 自然語言觸發(fā)(根據 description 自動匹配)
User: 幫我分析這個內存泄漏日志
→ Claude Code 根據關鍵詞自動匹配 android-memory-analyzer Agent

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

# 方式 3: 在 description 中配置觸發(fā)示例
# 在 description 中可以添加示例來幫助 Claude Code 更準確地匹配

# 好的 description 示例
description: 專門分析 Android 應用的內存泄漏問題,結合 LeakCanary 日志和 Profiler dump 進行診斷。當用戶提到內存泄漏、LeakCanary、OOM、內存分析等關鍵詞時自動觸發(fā)。示例：<example>用戶："幫我分析這個 LeakCanary 日志"，助手："我將使用內存泄漏分析 Agent 來幫你診斷問題"</example>

# 包含的要素:
# 1. 核心功能描述
# 2. 觸發(fā)關鍵詞
# 3. 使用示例(可選但推薦)

第 1 階段:需求分析
  ┌─────────────┐
  │ bmad-po     │ "用戶反饋功能需求分析"
  └──────┬──────┘
         │
         ▼
  生成 PRD:
  - 用戶可以提交反饋(文字+圖片)
  - 管理員可以查看和回復
  - 反饋分類和優(yōu)先級

第 2 階段:項目規(guī)劃
  ┌─────────────┐
  │ bmad-pm     │ "制定開發(fā)計劃"
  └──────┬──────┘
         │
         ▼
  項目計劃:
  - Sprint 1: 用戶提交反饋 (3天)
  - Sprint 2: 管理后臺 (5天)
  - Sprint 3: 通知和統(tǒng)計 (2天)

第 3 階段:架構設計
  ┌─────────────┐
  │bmad-architect│ "設計系統(tǒng)架構"
  └──────┬──────┘
         │
         ▼
  技術方案:
  - API 設計:POST /api/feedback
  - 數(shù)據庫設計:feedback 表
  - 文件存儲:S3/OSS

第 4 階段:任務拆分
  ┌─────────────┐
  │ bmad-sm     │ "拆分用戶故事"
  └──────┬──────┘
         │
         ▼
  用戶故事:
  - 作為用戶,我可以提交反饋
  - 作為管理員,我可以查看反饋列表
  - 作為管理員,我可以回復反饋

第 5 階段:開發(fā)實現(xiàn)
  ┌─────────────┐
  │ bmad-dev    │ "實現(xiàn)代碼"
  └──────┬──────┘
         │
         ▼
  代碼實現(xiàn):
  - FeedbackController.kt
  - FeedbackRepository.kt
  - FeedbackViewModel.kt

第 6 階段:質量保障
  ┌─────────────┐
  │ bmad-qa     │ "編寫測試并驗證"
  └──────┬──────┘
         │
         ▼
  測試用例:
  - 單元測試:業(yè)務邏輯測試
  - 集成測試:API 測試
  - UI 測試:提交反饋流程