<!-- title: Claude Code子Agent体系与动态编排全实战 -->

# Claude Code子Agent体系与动态编排全实战

> **学习目标**：掌握Claude Code四大并行模式（子Agent、Agent View、Agent Teams、动态Workflow），理解Hooks生命周期拦截机制，学会用Agent SDK编写生产级编排脚本，最终构建一个完整的多Agent代码审计系统。
>
> **适用人群**：已具备Claude Code基础操作能力的开发者、DevOps工程师、技术团队负责人。

## 一、前置条件

| 项目 | 要求 |
|------|------|
| Claude Code | ≥ 1.0.50（2026年6月版本） |
| 订阅计划 | Pro / Max / Team / Enterprise（Workflow功能需要Pro及以上） |
| Node.js | ≥ 18（运行Agent SDK TypeScript） |
| Python | ≥ 3.10（运行Agent SDK Python） |
| Git | ≥ 2.30（Agent Teams依赖worktree） |

安装Agent SDK：

```bash
# TypeScript
npm install @anthropic-ai/claude-code

# Python
pip install claude-code-sdk
```

## 二、Claude Code四大并行模式全景

Claude Code在2026年已形成完整的并行执行体系，四种模式各有定位：

```mermaid
graph TB
    subgraph "Claude Code 并行执行体系"
        A["单一会话<br/>Interactive Mode"] --> B["子Agent Subagent<br/>会话内并行"]
        A --> C["Agent View<br/>多会话管理"]
        A --> D["Agent Teams<br/>团队协作"]
        A --> E["动态 Workflow<br/>脚本编排"]

        B --> B1["Agent Tool调用<br/>自动派遣"]
        B --> B2["轻量级、零配置"]
        B --> B3["默认最多16并行"]

        C --> C1["claude agents 命令<br/>统一仪表盘"]
        C --> C2["查看/管理所有会话"]
        C --> C3["需要时介入审批"]

        D --> D1["多实例协作<br/>共享任务列表"]
        D --> D2["跨Agent消息传递"]
        D --> D3["实验性功能"]

        E --> E1["JavaScript脚本<br/>确定性编排"]
        E --> E2["pipeline/parallel"]
        E --> E3["支持1000个Agent"]
    end
```

### 2.1 模式选择决策树

```mermaid
flowchart TD
    Start[需要并行处理] --> Q1{任务类型?}
    Q1 -->|"对话中派生子任务"| Sub["子Agent Subagent"]
    Q1 -->|"管理多个独立项目"| View["Agent View"]
    Q1 -->|"多Agent团队协作"| Team["Agent Teams"]
    Q1 -->|"大规模确定性编排"| WF["动态 Workflow"]

    Sub --> Q2{需要确定性控制?}
    Q2 -->|是| WF
    Q2 -->|否| Sub

    View --> Q3{需要跨Agent通信?}
    Q3 -->|是| Team
    Q3 -->|否| View
```

## 三、子Agent（Subagent）深度实战

### 3.1 核心概念

子Agent是Claude Code会话内部的轻量级并行机制。当主会话遇到可以拆分的任务时，Claude会自动通过Agent Tool派生子Agent。每个子Agent拥有独立的上下文窗口，完成后将结果返回主会话。

**关键特性：**
- 零配置：Claude自动判断何时派遣子Agent
- 并行上限：默认最多16个同时运行（取决于CPU核心数）
- 上下文隔离：子Agent不会污染主会话上下文
- 自动合并：结果自动汇总到主对话

### 3.2 自定义子Agent定义

在项目的`.claude/agents/`目录下创建自定义Agent定义文件：

```bash
mkdir -p .claude/agents
```

创建`.claude/agents/code-reviewer.md`：

```markdown
---
name: code-reviewer
description: |
  专门用于代码审查的子Agent。审查代码质量、安全漏洞和性能问题。
  当需要审查PR、检查代码质量、进行安全审计时使用。
tools:
  - Read
  - Grep
  - Glob
  - Bash
model: sonnet
---

你是资深代码审查专家。你的职责是：

1. **安全审查**：检测SQL注入、XSS、CSRF等常见安全漏洞
2. **性能审查**：识别N+1查询、内存泄漏、不必要的同步操作
3. **代码质量**：检查命名规范、函数复杂度、重复代码
4. **架构合规**：验证是否遵循项目既定架构模式

输出格式：
- 按严重程度分级：🔴 严重 / 🟡 警告 / 🔵 建议
- 每个问题附上文件路径和行号
- 给出具体的修复建议
```

创建`.claude/agents/test-writer.md`：

```markdown
---
name: test-writer
description: |
  专门编写测试用例的子Agent。根据代码自动生成单元测试和集成测试。
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

你是测试工程专家。根据提供的代码：

1. 分析函数签名和边界条件
2. 生成覆盖正常路径、边界值、异常路径的测试用例
3. 使用项目已有的测试框架（Jest/Vitest/pytest等）
4. 确保测试可独立运行、不依赖外部状态
5. 测试命名遵循项目约定

输出要求：
- 每个测试函数只验证一个行为
- 使用AAA模式（Arrange-Act-Assert）
- Mock外部依赖
```

### 3.3 使用自定义子Agent

在对话中，Claude会根据任务类型自动选择合适的子Agent。也可以手动指定：

```bash
# Claude会根据agent定义的description自动匹配
claude "审查 src/auth/ 目录下的所有文件，找出安全漏洞"

# 也可以在CLAUDE.md中配置默认行为
echo '当需要代码审查时，使用 code-reviewer 子Agent' >> .claude/CLAUDE.md
```

## 四、Agent View：多会话管理仪表盘

### 4.1 核心功能

Agent View是一个统一界面，让你同时管理多个Claude Code后台会话：

```bash
# 打开Agent View仪表盘
claude agents

# 在后台启动一个新任务
claude agents spawn "重构 src/api/ 目录，将REST API迁移到GraphQL"

# 查看特定Agent的状态
claude agents status <agent-id>

# 向等待输入的Agent发送消息
claude agents message <agent-id> "继续，使用Apollo Server"
```

### 4.2 Agent View界面操作

Agent View提供以下操作：

| 快捷键 | 功能 |
|--------|------|
| `j/k` | 上下选择Agent |
| `Enter` | 进入Agent会话 |
| `a` | 审批等待中的Agent |
| `r` | 拒绝并停止Agent |
| `n` | 启动新Agent |
| `?` | 显示帮助 |

### 4.3 实战：批量文件重构

```bash
# 同时启动多个后台Agent处理不同模块
claude agents spawn "重构 src/users/ 模块，将class组件转为函数组件" &
claude agents spawn "重构 src/products/ 模块，将class组件转为函数组件" &
claude agents spawn "重构 src/orders/ 模块，将class组件转为函数组件" &

# 打开仪表盘查看进度
claude agents
```

## 五、Agent Teams：多实例团队协作

### 5.1 启用Agent Teams

Agent Teams目前是实验性功能，需要在设置中启用：

```json
// .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "true"
  }
}
```

### 5.2 团队架构

```mermaid
graph TB
    TM["Team Manager<br/>协调者"] --> A1["Agent 1: 前端开发"]
    TM --> A2["Agent 2: 后端开发"]
    TM --> A3["Agent 3: 测试工程"]
    TM --> A4["Agent 4: 文档撰写"]

    A1 --> |"API接口定义"| A2
    A2 --> |"接口变更通知"| A3
    A3 --> |"测试报告"| TM

    subgraph "共享机制"
        ST["共享任务列表"]
        MSG["跨Agent消息"]
        WT["独立Worktree"]
    end

    TM --- ST
    A1 --- MSG
    A2 --- MSG
```

**核心机制：**

1. **共享任务列表**：所有Agent共享一个任务看板，可以认领和更新任务
2. **跨Agent消息**：Agent之间可以发送消息协调工作
3. **独立Worktree**：每个Agent在独立的Git worktree中工作，避免文件冲突
4. **协调者模式**：一个Team Manager负责分配和协调

### 5.3 创建团队任务

```bash
# 在对话中创建团队
claude "创建一个开发团队，包含3个Agent：
1. 前端Agent：使用React重写登录页面
2. 后端Agent：实现OAuth2.0认证API
3. 测试Agent：编写集成测试
使用Agent Teams协调工作"
```

## 六、动态Workflow：脚本化确定性编排

### 6.1 Workflow核心概念

动态Workflow是Claude Code最强大的编排机制——用JavaScript脚本定义确定性的多Agent工作流，支持循环、条件分支、并行/串行执行。

```mermaid
sequenceDiagram
    participant U as 用户
    participant W as Workflow引擎
    participant A1 as Agent 1
    participant A2 as Agent 2
    participant A3 as Agent 3
    
    U->>W: 启动Workflow
    W->>A1: phase("发现") - 扫描代码
    A1-->>W: 返回问题列表
    
    W->>W: parallel 屏障: 等待所有
    
    par 并行验证
        W->>A2: 验证问题1
        W->>A3: 验证问题2
    end
    
    A2-->>W: 确认/反驳
    A3-->>W: 确认/反驳
    W-->>U: 最终报告
```

### 6.2 Workflow脚本结构

每个Workflow脚本必须包含`meta`声明和脚本主体：

```javascript
// 必须的meta声明（纯字面量，不能包含变量或表达式）
export const meta = {
  name: 'code-audit-workflow',
  description: '全量代码审计：扫描、验证、生成报告',
  phases: [
    { title: '扫描', detail: '并行扫描不同维度' },
    { title: '验证', detail: '对抗式验证每个发现' },
    { title: '报告', detail: '合成最终审计报告' }
  ]
}

// 脚本主体
phase('扫描')

// pipeline：每个item独立流过所有stage，无屏障
const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, { label: `scan:${d.key}`, phase: '扫描', schema: FINDINGS_SCHEMA }),
  finding => agent(`验证此发现: ${finding.title}`, { label: `verify`, phase: '验证', schema: VERDICT_SCHEMA })
)

// parallel：屏障，等待所有完成
const all = await parallel([
  () => agent('扫描安全漏洞', { schema: SECURITY_SCHEMA }),
  () => agent('扫描性能问题', { schema: PERF_SCHEMA }),
  () => agent('扫描代码异味', { schema: SMELL_SCHEMA })
])
```

### 6.3 四大编排原语

| 原语 | 用途 | 特点 |
|------|------|------|
| `agent(prompt, opts)` | 派生单个子Agent | 返回字符串或结构化输出 |
| `pipeline(items, ...stages)` | 流水线处理 | 每个item独立流过所有stage，无屏障 |
| `parallel(thunks)` | 并行屏障 | 等待所有完成，适合需要全部结果才能继续的场景 |
| `phase(title)` | 阶段标记 | UI分组显示进度 |

**关键API参数：**

```javascript
agent(prompt, {
  label: '显示名称',           // UI标签
  phase: '阶段名',             // 归属阶段
  schema: {...},              // JSON Schema，强制结构化输出
  model: 'sonnet',            // 模型覆盖
  isolation: 'worktree',      // 在独立worktree中运行
  agentType: 'Explore'        // 使用特定子Agent类型
})
```

## 七、Hooks：生命周期拦截与自动化门禁

### 7.1 Hooks事件体系

Hooks是Claude Code的拦截器机制，在特定生命周期事件触发时自动执行用户定义的Shell命令。

```mermaid
flowchart LR
    subgraph "Claude Code 生命周期"
        A["PreToolUse<br/>工具执行前"] --> B["工具执行"]
        B --> C["PostToolUse<br/>工具执行后"]
        C --> D["用户交互"]
        D --> A
        E["Notification<br/>通知事件"]
        F["Stop<br/>会话结束"]
    end

    subgraph "Hook 处理"
        H1["Shell命令"]
        H2["HTTP端点"]
        H3["LLM提示"]
        H4["MCP工具"]
    end

    A -.-> H1
    C -.-> H2
    E -.-> H3
    F -.-> H4
```

### 7.2 Hooks配置格式

在`.claude/settings.json`或`.claude/settings.local.json`中配置：

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "cat | jq -r '.tool_input.command' | grep -qE '(rm -rf|drop table|format)' && echo 'BLOCK: 危险命令已拦截' && exit 2 || exit 0"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $(cat | jq -r '.tool_input.file_path') 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '[$(date)] Claude Code 任务完成' >> ~/.claude/activity.log"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code 需要你的输入\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}
```

### 7.3 Hook输入输出协议

每个Hook通过stdin接收JSON输入：

```json
// PreToolUse 输入
{
  "session_id": "abc123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

// PreToolUse 输出（退出码控制行为）
// 退出码 0: 允许继续
// 退出码 2: 阻止操作，stdout作为错误消息
// 其他退出码: 非预期错误，允许继续
```

PostToolUse额外接收执行结果：

```json
{
  "session_id": "abc123",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/src/app.ts",
    "content": "..."
  },
  "tool_result": "File written successfully"
}
```

### 7.4 实用Hook脚本集

**安全门禁脚本** `~/.claude/hooks/security-gate.sh`：

```bash
#!/bin/bash
# 读取stdin中的JSON
INPUT=$(cat)

# 提取工具名和命令
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 规则1: 禁止删除关键目录
if echo "$CMD" | grep -qE 'rm\s+(-rf?|--recursive)\s+/(etc|var|usr|home|root)'; then
  echo "🚫 安全拦截: 禁止删除系统关键目录"
  exit 2
fi

# 规则2: 禁止写入.env文件
if echo "$FILE" | grep -qE '\.env($|\.)'; then
  echo "🚫 安全拦截: 禁止修改环境变量文件"
  exit 2
fi

# 规则3: 禁止执行curl/wget到未知域名
if echo "$CMD" | grep -qE '(curl|wget).*--post'; then
  echo "⚠️  警告: 检测到POST请求，请确认目标地址安全"
fi

exit 0
```

**代码风格自动格式化** `~/.claude/hooks/auto-format.sh`：

```bash
#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

[ -z "$FILE" ] || [ ! -f "$FILE" ] && exit 0

# 根据文件扩展名选择格式化工具
case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx) npx prettier --write "$FILE" 2>/dev/null ;;
  *.py) python -m black "$FILE" 2>/dev/null ;;
  *.go) gofmt -w "$FILE" 2>/dev/null ;;
  *.rs) rustfmt "$FILE" 2>/dev/null ;;
esac

exit 0
```

## 八、Agent SDK：编程式Agent控制

### 8.1 TypeScript SDK基础

```typescript
// agent-runner.ts
import { query } from '@anthropic-ai/claude-code';

async function main() {
  // 基础查询
  const result = await query({
    prompt: '分析这个项目的依赖关系，找出安全风险',
    options: {
      maxTurns: 10,
      allowedTools: ['Read', 'Grep', 'Glob'],
      cwd: process.cwd()
    }
  });

  console.log(result);
}

main();
```

### 8.2 Python SDK基础

```python
# agent_runner.py
import asyncio
from claude_code_sdk import query

async def main():
    result = await query(
        prompt="分析这个项目的依赖关系，找出安全风险",
        options={
            "max_turns": 10,
            "allowed_tools": ["Read", "Grep", "Glob"],
        }
    )
    print(result)

asyncio.run(main())
```

### 8.3 编程式子Agent编排

```typescript
// multi-audit.ts
import { query } from '@anthropic-ai/claude-code';

interface AuditResult {
  findings: Array<{
    severity: 'critical' | 'high' | 'medium' | 'low';
    title: string;
    file: string;
    line: number;
    description: string;
  }>;
}

async function runParallelAudits(projectPath: string) {
  // 定义审计维度
  const dimensions = [
    {
      name: 'security',
      prompt: `审查 ${projectPath} 中的安全漏洞：SQL注入、XSS、认证绕过、敏感数据泄露`
    },
    {
      name: 'performance',
      prompt: `审查 ${projectPath} 中的性能问题：N+1查询、内存泄漏、不必要的同步、大数据集处理`
    },
    {
      name: 'architecture',
      prompt: `审查 ${projectPath} 中的架构问题：循环依赖、职责不清、耦合度过高`
    }
  ];

  // 并行执行所有审计
  const results = await Promise.all(
    dimensions.map(dim =>
      query<AuditResult>({
        prompt: dim.prompt,
        options: {
          maxTurns: 15,
          allowedTools: ['Read', 'Grep', 'Glob', 'Bash'],
          outputFormat: 'json',
          cwd: projectPath
        }
      })
    )
  );

  // 合并结果
  const allFindings = results
    .flatMap((r, i) => ({
      ...r,
      dimension: dimensions[i].name
    }))
    .sort((a, b) => {
      const order = { critical: 0, high: 1, medium: 2, low: 3 };
      return order[a.findings[0]?.severity] - order[b.findings[0]?.severity];
    });

  return allFindings;
}

runParallelAudits('/path/to/project').then(console.log);
```

## 九、实战案例：多Agent代码审计系统

### 9.1 项目结构

```
multi-agent-audit/
├── .claude/
│   ├── settings.json          # Hooks配置
│   ├── agents/
│   │   ├── security-scanner.md
│   │   ├── perf-analyzer.md
│   │   └── test-coverage.md
│   └── workflows/
│       └── full-audit.js      # 动态Workflow脚本
├── audit-runner.ts             # SDK编排入口
└── reports/                    # 输出目录
```

### 9.2 完整Workflow脚本

```javascript
// .claude/workflows/full-audit.js
export const meta = {
  name: 'full-code-audit',
  description: '全量代码审计：安全扫描 → 性能分析 → 测试覆盖 → 对抗验证 → 生成报告',
  phases: [
    { title: '扫描', detail: '并行扫描三个维度' },
    { title: '验证', detail: '对抗式交叉验证' },
    { title: '报告', detail: '合成结构化报告' }
  ]
}

const FINDINGS_SCHEMA = {
  type: 'object',
  properties: {
    findings: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
          title: { type: 'string' },
          file: { type: 'string' },
          line: { type: 'number' },
          description: { type: 'string' },
          fix: { type: 'string' }
        },
        required: ['severity', 'title', 'file', 'description']
      }
    }
  }
}

const VERDICT_SCHEMA = {
  type: 'object',
  properties: {
    confirmed: { type: 'boolean' },
    confidence: { type: 'number', minimum: 0, maximum: 1 },
    reasoning: { type: 'string' },
    additionalContext: { type: 'string' }
  },
  required: ['confirmed', 'confidence', 'reasoning']
}

const DIMENSIONS = [
  { key: 'security', prompt: '扫描所有源代码文件，找出安全漏洞：注入攻击、认证问题、敏感数据暴露、不安全的依赖。按严重程度分级。' },
  { key: 'performance', prompt: '扫描所有源代码文件，找出性能问题：N+1查询、内存泄漏、不必要的同步操作、大数据集处理不当。按影响程度分级。' },
  { key: 'quality', prompt: '扫描所有源代码文件，找出代码质量问题：高复杂度函数、重复代码、不一致的错误处理、缺失的类型定义。按严重程度分级。' }
]

// 阶段1: 并行扫描三个维度
phase('扫描')
const scanResults = await parallel(
  DIMENSIONS.map(d => () =>
    agent(d.prompt, {
      label: `scan:${d.key}`,
      phase: '扫描',
      schema: FINDINGS_SCHEMA
    })
  )
)

// 合并所有发现
const allFindings = scanResults
  .filter(Boolean)
  .flatMap(r => r.findings)
  .sort((a, b) => {
    const order = { critical: 0, high: 1, medium: 2, low: 3 }
    return (order[a.severity] ?? 3) - (order[b.severity] ?? 3)
  })

log(`发现 ${allFindings.length} 个问题，开始验证...`)

// 阶段2: 对抗式验证每个发现
phase('验证')
const verified = await pipeline(
  allFindings,
  finding => agent(
    `你是代码审查质疑者。以下发现是否真实可信？

    问题: ${finding.title}
    文件: ${finding.file}${finding.line ? ':' + finding.line : ''}
    描述: ${finding.description}

    请严格审视：这是否是误报？是否遗漏了关键上下文？严重程度是否准确？
    如果是误报或严重程度有误，请说明理由。`,
    {
      label: `verify:${finding.file}`,
      phase: '验证',
      schema: VERDICT_SCHEMA
    }
  )
)

// 过滤确认的问题
const confirmed = verified
  .filter(Boolean)
  .filter((v, i) => v.confirmed && v.confidence >= 0.6)
  .map((v, i) => ({ ...allFindings[i], verdict: v }))

log(`验证通过 ${confirmed.length}/${allFindings.length} 个问题`)

// 阶段3: 生成报告
phase('报告')
const report = await agent(
  `基于以下验证通过的审计发现，生成结构化报告：

${JSON.stringify(confirmed, null, 2)}

报告需包含：
1. 执行摘要（总问题数、按严重程度统计）
2. 每个问题的详细描述和修复建议
3. 优先级排序的行动计划`,
  { label: 'report', phase: '报告' }
)

return { report, totalFindings: allFindings.length, confirmedCount: confirmed.length }
```

### 9.3 Hooks安全门禁配置

```json
// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command // empty'); if echo \"$CMD\" | grep -qiE '(rm\\s+-rf|drop\\s+table|truncate|format\\s+[a-z]:)'; then echo 'BLOCKED: 危险操作已拦截'; exit 2; fi; exit 0"
          }
        ]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // empty'); if echo \"$FILE\" | grep -qE '(\\.env|credentials|secret|\\.pem|\\.key)'; then echo 'BLOCKED: 禁止修改敏感文件'; exit 2; fi; exit 0"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "INPUT=$(cat); FILE=$(echo \"$INPUT\" | jq -r '.tool_input.file_path // empty'); [ -n \"$FILE\" ] && [ -f \"$FILE\" ] && case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null ;; *.py) python3 -m black \"$FILE\" 2>/dev/null ;; esac; exit 0"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date '+%Y-%m-%d %H:%M:%S')] Claude Code通知\" >> ~/.claude/audit-notifications.log"
          }
        ]
      }
    ]
  }
}
```

### 9.4 运行完整审计

```bash
# 方式1: 通过Workflow命令运行
claude /workflows full-audit

# 方式2: 通过-p模式运行
claude -p "运行full-code-audit workflow，审计当前项目"

# 方式3: 通过Agent SDK编程式运行
npx tsx audit-runner.ts
```

## 十、-p模式（Print Mode）：无头自动化

### 10.1 基础用法

`-p`模式（又称Print Mode或Headless Mode）是Claude Code的非交互式运行方式，适合CI/CD、脚本和自动化场景。

```bash
# 基础用法：单次提问，输出到stdout
claude -p "解释这个函数的作用: $(cat src/utils.ts)"

# 管道输入
echo "分析这段代码" | claude -p

# 从文件读取prompt
claude -p < prompt.txt

# 指定输出格式
claude -p "列出所有TODO注释" --output-format json

# 流式JSON输出（适合实时处理）
claude -p "重构这个模块" --output-format stream-json

# 限制最大交互轮次
claude -p "修复所有lint错误" --max-turns 5

# 限制可用工具
claude -p "只读分析项目结构" --allowedTools "Read,Grep,Glob"

# 裸模式（跳过hooks/MCP发现，加速启动）
claude -p --bare "快速回答: Node.js最新LTS版本是多少"
```

### 10.2 输出格式详解

| 格式 | 用途 | 示例 |
|------|------|------|
| `text`（默认） | 纯文本 | 直接输出到stdout |
| `json` | 结构化JSON | 包含消息、成本、会话ID |
| `stream-json` | 流式JSON | 每行一个JSON对象，实时处理 |

```bash
# JSON格式获取结构化结果
result=$(claude -p "计算这个项目的代码行数" --output-format json)
echo "$result" | jq '.result'
echo "$result" | jq '.cost_usd'
```

### 10.3 CI/CD集成模板

**GitHub Actions示例：**

```yaml
# .github/workflows/ai-code-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed
        run: |
          FILES=$(git diff --name-only origin/main...HEAD | head -20)
          echo "files=$FILES" >> $GITHUB_OUTPUT

      - name: Run AI Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "
            审查以下PR变更，关注安全漏洞、性能问题和代码质量：
            
            变更文件：
            ${{ steps.changed.outputs.files }}
            
            请给出：
            1. 总体评价（1-5分）
            2. 关键问题列表
            3. 改进建议
          " --output-format json > review-result.json

      - name: Post Review Comment
        if: always()
        run: |
          REVIEW=$(cat review-result.json | jq -r '.result')
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "## 🤖 AI Code Review
            
          $REVIEW"
```

### 10.4 批量任务脚本

```bash
#!/bin/bash
# batch-refactor.sh - 批量重构脚本

PROJECTS=("api-gateway" "user-service" "order-service" "notification-service")
TASK="将所有console.log替换为winston logger，添加适当的日志级别"

for project in "${PROJECTS[@]}"; do
  echo "🔄 处理 $project ..."
  
  result=$(claude -p "$TASK" \
    --cwd "./services/$project" \
    --max-turns 10 \
    --allowedTools "Read,Write,Edit,Grep,Glob" \
    --output-format json 2>&1)
  
  if [ $? -eq 0 ]; then
    cost=$(echo "$result" | jq -r '.cost_usd // "unknown"')
    echo "✅ $project 完成 (成本: \$$cost)"
  else
    echo "❌ $project 失败: $result"
  fi
done

echo "🎉 批量重构完成"
```

## 十一、进阶模式与最佳实践

### 11.1 Workflow中的预算控制

```javascript
export const meta = {
  name: 'budget-aware-audit',
  description: '带预算控制的代码审计',
  phases: [{ title: '扫描' }, { title: '验证' }]
}

// 利用budget API控制token消耗
const bugs = []
while (budget.total && budget.remaining() > 50000) {
  const result = await agent('发现更多代码问题', {
    schema: FINDINGS_SCHEMA,
    phase: '扫描'
  })
  bugs.push(...result.findings)
  log(`已发现 ${bugs.length} 个问题，剩余预算: ${Math.round(budget.remaining() / 1000)}k tokens`)
}
```

### 11.2 Loop-Until-Dry模式

```javascript
// 持续发现直到连续N轮没有新发现
const seen = new Set()
const confirmed = []
let dry = 0

while (dry < 2) {
  const found = await parallel(
    FINDERS.map(f => () =>
      agent(f.prompt, { phase: '发现', schema: BUGS_SCHEMA })
    )
  ).then(r => r.filter(Boolean).flatMap(r => r.bugs))

  const fresh = found.filter(b => !seen.has(`${b.file}:${b.line}`))
  
  if (!fresh.length) { dry++; continue }
  dry = 0
  fresh.forEach(b => seen.add(`${b.file}:${b.line}`))

  // 对每个新发现进行3方对抗验证
  const judged = await parallel(fresh.map(b => () =>
    parallel([1, 2, 3].map(() => () =>
      agent(`反驳或确认: ${b.description}`, { phase: '验证', schema: VERDICT_SCHEMA })
    ))
  )))

  confirmed.push(...judged.filter(v => 
    v.filter(x => x?.confirmed).length >= 2
  ))
}
```

### 11.3 Workflow恢复与缓存

```bash
# Workflow支持恢复——已完成的Agent调用会自动缓存
# 首次运行
claude /workflows full-audit
# 返回 runId: wf_abc123

# 如果中断，可以恢复
# 修改脚本后重新运行，未变更的Agent调用直接使用缓存
claude /workflows full-audit --resume wf_abc123
```

### 11.4 子Agent模型选择策略

```javascript
// 根据任务复杂度选择不同模型
const agents = [
  // 简单任务用Haiku（快速、便宜）
  { task: '格式化JSON文件', model: 'haiku' },
  
  // 常规任务用Sonnet（平衡）
  { task: '代码审查', model: 'sonnet' },
  
  // 复杂推理用Opus（最强）
  { task: '架构设计评审', model: 'opus' }
]

const results = await parallel(
  agents.map(a => () =>
    agent(a.task, { model: a.model })
  )
)
```

## 十二、性能优化与成本控制

### 12.1 并行度调优

| 场景 | 推荐并行度 | 说明 |
|------|-----------|------|
| 代码审计 | 8-16 | 按目录或维度拆分 |
| 大规模迁移 | 4-8 | 避免worktree竞争 |
| 文档生成 | 16+ | IO密集，无冲突 |
| 测试生成 | 8-12 | 按模块拆分 |

### 12.2 上下文管理

```javascript
// 使用isolation避免上下文污染
const results = await parallel(
  files.map(f => () =>
    agent(`重构 ${f}`, {
      isolation: 'worktree',  // 每个Agent在独立worktree中
      schema: RESULT_SCHEMA
    })
  )
)

// 使用structured output减少token消耗
const result = await agent('分析代码', {
  schema: {
    type: 'object',
    properties: {
      issues: { type: 'array', items: { type: 'string' }, maxItems: 5 },
      score: { type: 'number' }
    }
  }
})
```

### 12.3 缓存提示缓存命中率

```bash
# 使用--bare跳过不必要的发现
claude -p --bare "快速回答"  # 跳过hooks/MCP发现

# 在-p模式中复用系统提示
# 保持prompt结构一致可提高缓存命中率
```

## 十三、常见问题与排障

### Q1: 子Agent超时怎么办？

```json
// 在settings.json中调整超时
{
  "agentTimeout": 300000  // 5分钟
}
```

### Q2: Workflow中Agent报错如何处理？

```javascript
// parallel中单个Agent报错不会影响其他
const results = await parallel([
  () => agent('任务A'),
  () => agent('任务B'),  // 即使B报错，A仍会完成
  () => agent('任务C')
])
// 报错的Agent返回null
const valid = results.filter(Boolean)
```

### Q3: Hooks脚本调试？

```bash
# 手动测试Hook脚本
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | \
  bash ~/.claude/hooks/security-gate.sh
echo $?  # 应该输出2（被拦截）

# 查看Hook执行日志
cat ~/.claude/activity.log
```

### Q4: Agent Teams的worktree冲突？

```bash
# 查看所有worktree
git worktree list

# 清理已完成的worktree
git worktree prune

# 如果Agent异常退出，手动清理
git worktree remove .claude/worktrees/<agent-name>
```

## 十四、整体架构总结

```mermaid
graph TB
    subgraph "用户层"
        CLI["Claude Code CLI"]
        SDK["Agent SDK<br/>(TS/Python)"]
        API["外部API调用"]
    end

    subgraph "编排层"
        WF["动态Workflow<br/>(JS脚本)"]
        AV["Agent View<br/>(仪表盘)"]
        AT["Agent Teams<br/>(团队协作)"]
    end

    subgraph "执行层"
        SA["子Agent<br/>(并行执行)"]
    end

    subgraph "拦截层"
        H1["PreToolUse Hook"]
        H2["PostToolUse Hook"]
        H3["Notification Hook"]
        H4["Stop Hook"]
    end

    subgraph "工具层"
        T1["文件操作<br/>Read/Write/Edit"]
        T2["搜索工具<br/>Grep/Glob"]
        T3["Shell执行<br/>Bash"]
        T4["MCP服务器<br/>外部集成"]
    end

    CLI --> WF
    CLI --> AV
    CLI --> AT
    SDK --> WF

    WF --> SA
    AV --> SA
    AT --> SA

    SA --> H1
    H1 --> T1
    H1 --> T2
    H1 --> T3
    H1 --> T4
    T1 --> H2
    T2 --> H2
    T3 --> H2
    T4 --> H2

    H3 -.-> CLI
    H4 -.-> CLI
```

## 十五、训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适用训练营** | AI工程高级训练营、企业级AI应用开发、DevOps智能化转型 |
| **教学时长** | 6-8小时（含实操） |
| **难度等级** | ⭐⭐⭐⭐（中高级） |
| **前置要求** | Claude Code基础操作、JavaScript/Python基础、Git高级操作 |
| **实操占比** | 70%（大量hands-on练习） |
| **推荐分组** | 2-3人一组，每组负责一个审计维度，最后合并结果 |
| **考核方式** | 完成一个真实项目的多Agent代码审计，生成结构化报告 |

## 参考来源

1. [Run Claude Code programmatically - Claude Code Docs](https://code.claude.com/docs/en/headless) — 官方无头模式/Agent SDK编程式运行文档
2. [Run agents in parallel - Claude Code Docs](https://code.claude.com/docs/en/agents) — 四大并行模式对比总览
3. [Hooks reference - Claude Code Docs](https://code.claude.com/docs/en/hooks) — Hooks生命周期事件完整参考
4. [Automate actions with hooks - Claude Code Docs](https://code.claude.com/docs/en/hooks-guide) — Hooks配置实战指南
5. [Subagents in the SDK - Claude Code Docs](https://code.claude.com/docs/en/agent-sdk/subagents) — Agent SDK子Agent编程接口
6. [Orchestrate subagents at scale with dynamic workflows - Claude Code Docs](https://code.claude.com/docs/en/workflows) — 动态Workflow编排机制
7. [Orchestrate teams of Claude Code sessions - Claude Code Docs](https://code.claude.com/docs/en/agent-teams) — Agent Teams团队协作模式

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)