Claude Code多Agent编排实战：从Subagent原理到生产级模式

Task({
  subagent_type:    "Explore" | "Plan" | "Bash" | "general-purpose" | "自定义名",
  description:      "3-5词的任务描述",
  prompt:           "详细指令文本",
  model:            "sonnet" | "opus" | "haiku",        // 可选，默认继承主Agent
  run_in_background: true | false,                       // 可选，默认false
  isolation:        "worktree" | undefined,              // 可选，隔离模式
  max_turns:        10,                                   // 可选，限制API调用轮次
  resume:           "agent-id-string"                     // 可选，恢复之前的Agent
})

haiku  → 简单搜索、命令执行、格式化任务  （成本最低，速度最快）
sonnet → 代码分析、方案设计、常规开发任务（均衡之选）
opus   → 架构决策、复杂重构、安全审计    （最强推理，成本最高）

// 三个Explore Agent同时启动
Task({ subagent_type: "Explore", prompt: "搜索所有API路由定义" })
Task({ subagent_type: "Explore", prompt: "搜索所有数据库模型文件" })
Task({ subagent_type: "Bash", prompt: "运行当前测试套件并报告失败项" })

your-project/
└── .claude/
    └── agents/
        ├── code-reviewer.md      # 代码审查Agent
        ├── security-auditor.md   # 安全审计Agent
        └── test-runner.md        # 测试执行Agent

---
name: security-auditor
description: |
  Run a comprehensive security audit. Trigger on "security audit",
  "check for vulnerabilities", "OWASP scan", or "security review".
tools:
  - Read
  - Glob
  - Grep
  - Bash
---

You are a security audit specialist. Scan the codebase for OWASP Top 10 vulnerabilities:

1. **SQL injection** — Look for raw SQL queries, unsanitized inputs in database calls
2. **XSS** — Look for unescaped user content in templates and responses
3. **Authentication issues** — Hardcoded secrets, weak hashing, missing CSRF tokens
4. **SSRF** — User-controlled URLs in server-side requests
5. **Dependency vulnerabilities** — Run `npm audit` / `pip audit` and report results

Report each finding with:
- Severity: Critical / High / Medium / Low
- File path and line number
- Vulnerable code snippet
- Recommended fix

Constraints:
- Do NOT modify any files — only report findings
- Limit output to 1500 words maximum
- If a source is inaccessible, note it rather than failing

## research-agent
Researches a specific technical topic and returns a structured report.

### When to use
- User asks to research a topic
- Need to gather information from web or documentation

### Input
- `topic`: the subject to research (string)
- `depth`: "overview" | "deep-dive"
- `sources`: array of URLs to prioritize, or empty for open research

### Output format
Return a markdown report with exactly these sections:
1. Summary (3-5 sentences)
2. Key findings (bullet list, max 10 items)
3. Gaps / unknowns (what you could not verify)
4. Sources used (URL list)

### Constraints
- Do not return more than 1,500 words total
- If `depth` is "overview", spend no more than 5 tool calls
- If a source is inaccessible, note it in Gaps rather than failing

~/.claude/agents/                 # 全局Agent——所有项目可用
your-project/.claude/agents/      # 项目级Agent——团队共享（提交到Git）
your-project/packages/api/.claude/agents/  # 模块级Agent——特定包专用

主Agent
  ├── 并行启动 → Agent A: 搜索 src/api/ 的安全问题
  ├── 并行启动 → Agent B: 搜索 src/auth/ 的安全问题
  ├── 并行启动 → Agent C: 搜索 src/database/ 的安全问题
  └── 启动聚合 → Aggregator Agent: 汇总A/B/C结果，去重分级，生成最终报告

Task({
  subagent_type: "general-purpose",
  prompt: "尝试将Prisma ORM替换为Drizzle ORM。运行测试验证。如果失败则回退。",
  isolation: "worktree"
})

Task({
  subagent_type: "Bash",
  prompt: "运行完整的集成测试套件，报告所有失败",
  run_in_background: true
})
// 主Agent继续处理其他任务...
// 测试完成后自动收到通知

步骤1: Explore Agent → "分析当前数据库Schema"
  ↓ 输出: Schema结构报告
步骤2: Plan Agent → "基于Schema设计迁移方案" + 上一步的输出
  ↓ 输出: 迁移SQL + 代码修改计划
步骤3: general-purpose Agent → "执行迁移方案" + 上一步的输出
  ↓ 输出: 修改后的文件列表
步骤4: Bash Agent → "运行迁移并验证数据库完整性"
  ↓ 输出: 验证结果

// 错误：把整个代码库塞给Subagent
Task({
  prompt: "这里是整个src/目录的内容：[50000字代码]...请分析安全问题"
})

// 正确：传递结构化摘要
Task({
  prompt: `## 代码库上下文
- 语言: TypeScript, Node.js 20
- 架构: Express REST API, PostgreSQL via Prisma
- 相关文件:
  - src/api/users.ts (用户CRUD端点)
  - src/lib/db.ts (数据库查询辅助)
  - prisma/schema.prisma (数据模型)
- 约定: 命名导出, snake_case数据库列, camelCase代码
- 测试命令: npm test

请审计这些文件中的SQL注入风险。`
})

## 来自 [前一Agent] 的交接
状态: 已完成
输出:
  - 在 src/api/payments.ts 创建了3个新API端点
  - 在 src/schemas/payment.ts 添加了Zod校验
  - 测试在 src/api/__tests__/payments.test.ts
遇到的问题:
  - Stripe webhook端点需要尚未实现的认证中间件
你的任务:
  - 实现缺失的认证中间件（参考 src/middleware/ 现有模式）
  - 接入webhook端点
  - 验证所有支付测试通过

---
name: code-reviewer
description: Reviews pull request diffs and returns structured feedback.
tools:
  - Read      # 可以读取文件
  - Glob      # 可以搜索文件
  - Grep      # 可以搜索内容
# 注意：没有 Edit、Write、Bash → Agent无法修改任何东西
---

### 失败行为
如果无法完成任务，返回：
{
  "status": "failed",
  "reason": "简要说明",
  "completed_portion": "失败前完成了什么",
  "retry_possible": true/false
}
不要猜测或在没有标记的情况下输出部分结果。

---
name: owasp-scanner
description: |
  Scan code for OWASP Top 10 vulnerabilities. Trigger on "security scan",
  "vulnerability check", or "OWASP audit".
tools:
  - Read
  - Glob
  - Grep
  - Bash
model: sonnet
---

You are an OWASP security scanner. Execute these checks:

1. **Injection (A01)** — Search for raw SQL, unsanitized inputs, exec/spawn with user data
2. **Broken Auth (A07)** — Find hardcoded credentials, weak session config, missing MFA
3. **XSS (A03)** — Find innerHTML, dangerouslySetInnerHTML, unescaped template output
4. **SSRF (A10)** — Find user-controlled URLs in fetch/axios/http requests
5. **Dependency vulns** — Run npm audit / pip audit / go vuln check

For each finding report:
- **Severity**: Critical | High | Medium | Low
- **Category**: OWASP category number
- **File:Line**: Exact location
- **Code**: Vulnerable snippet (max 3 lines)
- **Fix**: One-line remediation

Max output: 1000 words. Group by severity (Critical first).

---
name: performance-analyzer
description: |
  Analyze code for performance issues. Trigger on "performance review",
  "slow code", "optimize", or "N+1 query".
tools:
  - Read
  - Glob
  - Grep
model: sonnet
---

Scan for performance anti-patterns:

1. **N+1 queries** — Database calls inside loops
2. **Missing indexes** — Common query patterns without DB index support
3. **Synchronous I/O** — Blocking file/HTTP operations in async code
4. **Memory leaks** — Event listeners not cleaned up, growing caches
5. **Unnecessary re-renders** — React components re-rendering without prop changes

Report format:
- **Impact**: High | Medium | Low
- **File:Line**: Location
- **Pattern**: Anti-pattern name
- **Fix**: Recommended optimization

---
name: audit-aggregator
description: |
  Aggregate results from security and performance audits into a unified report.
  Trigger after owasp-scanner or performance-analyzer completes.
tools:
  - Read
  - Write
---

You are an audit report aggregator. You will receive findings from multiple
specialized scanners. Your job:

1. Deduplicate overlapping findings
2. Sort by severity (Critical → Low)
3. Group by module/directory
4. Add a summary scorecard:

| Category | Critical | High | Medium | Low |
|----------|----------|------|--------|-----|
| Security | X        | X    | X      | X   |
| Perf     | X        | X    | X      | X   |
| Total    | X        | X    | X      | X   |

5. List top 5 priority fixes
6. Write the full report to `audit-report.md`

你: 对这个项目做一次全面代码审计

Claude Code 自动编排:
  ┌─ 步骤1（并行）:
  │   ├── owasp-scanner: 扫描安全漏洞
  │   └── performance-analyzer: 扫描性能问题
  │
  ├─ 步骤2（依赖步骤1完成）:
  │   └── audit-aggregator: 汇总两份报告
  │
  └─ 步骤3: 主Agent展示审计摘要和优先修复建议

第1周: 部署Agent → 收集度量数据
第2周: 分析首次成功率低的Agent → 改进prompt和约束
第3周: 分析上下文消耗高的Agent → 优化输出格式
第4周: 验证改进效果 → 确认效率提升

// 致命错误——太模糊
## my-agent
处理任务并返回结果。

// 正确做法——精确到输入输出
## my-agent
### When to use
用户要求生成API文档时触发
### Input
接收 API路由文件路径列表
### Output
返回Markdown格式的API文档，每个端点包含：
- HTTP方法和路径
- 请求参数表格
- 响应格式示例
- 认证要求
### Constraints
- 输出不超过2000字
- 不要修改任何代码文件
- 如果无法确定参数类型，标注"unknown"

主Agent → Subagent → Sub-Subagent  ✓（2层，合理）
主Agent → Subagent → Sub-Subagent → Sub-Sub-Subagent  ✗（3层+，消耗爆炸）

## complex-migration-agent
处理数据库Schema迁移。完整规格见 `docs/agents/migration-agent.md`。