graph TB
    subgraph Primary["主会话代理 (Primary Agent)"]
        P1[用户对话]
        P2[工具调用]
        P3[上下文管理]
    end

    subgraph TaskTool["Task 工具（编排中枢）"]
        T1[分析任务]
        T2[选择代理类型]
        T3[派发执行]
    end

    subgraph Subagents["子代理集群"]
        S1["🔍 Explore Agent<br/>快速搜索与探索"]
        S2["📋 Plan Agent<br/>架构设计与规划"]
        S3["⚙️ General-Purpose<br/>通用任务执行"]
        S4["🎯 Custom Agent<br/>自定义专业代理"]
    end

    subgraph Isolation["隔离机制"]
        W1["Worktree 隔离"]
        W2["独立上下文"]
        W3["工具白名单"]
    end

    P1 --> T1
    T1 --> T2 --> T3
    T3 --> S1
    T3 --> S2
    T3 --> S3
    T3 --> S4
    S1 & S2 & S3 & S4 --> W1 & W2 & W3
    S1 & S2 & S3 & S4 -->|结果返回| P2

# 在 Claude Code 会话中直接提问
> 帮我找出这个项目中所有的数据库迁移文件，并分析它们的执行顺序

# Claude 会自动派发 Explore 子代理
# Explore 只读搜索 → 返回结构化结果

# 不好的提问（全库扫描）
> 找到所有错误处理相关的代码

# 好的提问（精准定位）
> 在 src/api/ 和 src/middleware/ 目录下，找到所有 try-catch 块和错误处理中间件

flowchart LR
    subgraph Explore["Explore Agent"]
        E1[搜索] --> E2[定位] --> E3[报告发现]
    end

    subgraph Plan["Plan Agent"]
        P1[分析代码] --> P2[理解架构] --> P3[设计变更方案]
        P3 --> P4[识别关键文件]
        P4 --> P5[评估权衡]
        P5 --> P6[输出实施步骤]
    end

> 分析当前项目架构，设计一个添加 WebSocket 实时通知功能的方案

# Plan Agent 将返回：
# 1. 架构分析：现有 Express 路由结构
# 2. 关键文件：server.js、routes/、middleware/
# 3. 变更方案：安装 ws 包、创建 WebSocket 管理器、修改 server.js
# 4. 风险点：与现有 HTTP server 的端口冲突
# 5. 步骤清单：5 个有序实施步骤

┌─────────────────────────────────────────────────┐
│         General-Purpose Agent 执行流程           │
├─────────────────────────────────────────────────┤
│  1. 接收任务描述和上下文                          │
│  2. 自主规划执行步骤                              │
│  3. 调用所需工具（Read/Edit/Write/Bash）          │
│  4. 验证每步结果                                  │
│  5. 返回最终结果摘要                              │
│                                                  │
│  ⚡ 特点：完全自主，无需人工干预                    │
│  🔒 限制：上下文窗口独立，不共享主会话历史          │
└─────────────────────────────────────────────────┘

.claude/
├── agents/
│   ├── security-auditor.md      # 安全审计代理
│   ├── test-writer.md           # 测试编写代理
│   ├── doc-generator.md         # 文档生成代理
│   └── perf-analyzer.md         # 性能分析代理
├── settings.json
└── CLAUDE.md

---
name: security-auditor
description: |
  Scans code for OWASP Top 10 vulnerabilities, hardcoded secrets,
  and insecure patterns. Use when reviewing code for security issues
  or before committing sensitive changes.
model: sonnet
tools:
  - Glob
  - Grep
  - Read
  - Bash
allowed_commands:
  - "npx eslint"
  - "grep"
  - "git diff"
---

# Security Auditor Agent

You are a security-focused code reviewer. Your job is to find vulnerabilities,
not to fix them.

## Review Checklist

1. **Injection attacks** — SQL injection, command injection, XSS
2. **Authentication flaws** — hardcoded credentials, weak tokens
3. **Sensitive data exposure** — API keys in source, unencrypted PII
4. **Security misconfiguration** — CORS *, debug mode enabled
5. **Dependency vulnerabilities** — known CVEs in package.json

## Output Format

Return findings as a structured list:
- Severity: CRITICAL / HIGH / MEDIUM / LOW
- File: path:line_number
- Issue: description
- Recommendation: how to fix

---
name: test-writer
description: |
  Generates comprehensive test suites for any code module. Creates unit tests,
  integration tests, and edge case coverage. Triggered when user asks to add
  tests, improve coverage, or TDD a new feature.
model: sonnet
tools:
  - Glob
  - Grep
  - Read
  - Edit
  - Write
  - Bash
---

# Test Writer Agent

You are a test engineering specialist. You write thorough, well-structured tests.

## Workflow

1. **Analyze target** — Read the source file, identify all exported functions
2. **Detect framework** — Check package.json for jest/vitest/mocha/pytest
3. **Generate tests** — Cover happy path, edge cases, error conditions
4. **Run tests** — Execute and verify all tests pass
5. **Report coverage** — If coverage tool available, report results

## Test Structure Pattern

```javascript
describe('moduleName', () => {
  describe('functionName', () => {
    it('should handle normal input', () => { /* ... */ })
    it('should handle edge case: empty input', () => { /* ... */ })
    it('should handle edge case: null input', () => { /* ... */ })
    it('should throw on invalid input', () => { /* ... */ })
  })
})

### 3.3 代理选择策略

Claude 如何决定使用哪个子代理？这取决于 `description` 字段与用户请求的语义匹配。

```mermaid
flowchart TD
    A[用户请求到达] --> B{需要修改代码？}
    B -->|否| C{需要设计方案？}
    B -->|是| D{有匹配的自定义代理？}
    C -->|是| E[Plan Agent]
    C -->|否| F[Explore Agent]
    D -->|是| G[Custom Agent]
    D -->|否| H{需要执行多步骤？}
    H -->|是| I[General-Purpose Agent]
    H -->|否| J[主代理直接处理]

    style G fill:#e1f5fe
    style E fill:#fff3e0
    style F fill:#e8f5e9
    style I fill:#fce4ec

# ✅ 好的 description —— 明确触发条件
description: |
  Scans code for OWASP Top 10 vulnerabilities.
  Use when reviewing code for security issues or before
  committing sensitive changes.

# ❌ 差的 description —— 模糊不清
description: |
  Helps with code quality and stuff.

Agent A: 编辑 src/auth.js 第 15 行
Agent B: 同时编辑 src/auth.js 第 12 行
→ 文件冲突，Agent B 的修改覆盖 Agent A

主仓库:     /project/
Agent A:    /project/.claude/worktrees/feature-auth/
Agent B:    /project/.claude/worktrees/feature-test/
→ 各自独立工作，完成后通过 Git 合并

> 在一个独立的 worktree 中工作，实现用户注册功能

> 使用两个并行代理：一个在 worktree 中修复 Bug #42，另一个在另一个 worktree 中添加日志功能

# 启动 Claude Code 并自动进入 worktree
claude --worktree feature-auth

# 在后台运行并行任务
claude -p "修复登录 Bug" --worktree fix-login &
claude -p "添加注册功能" --worktree add-register &
wait

sequenceDiagram
    participant User as 开发者
    participant Primary as 主代理
    participant BugFix as Bug修复代理
    participant Test as 测试代理
    participant Doc as 文档代理

    User->>Primary: 并行处理三项任务

    par 并行派发
        Primary->>BugFix: Task(isolation: worktree)<br/>修复 Issue #42
        Primary->>Test: Task(isolation: worktree)<br/>补充测试覆盖
        Primary->>Doc: Task(model: haiku)<br/>更新 API 文档
    end

    Note over BugFix,Doc: 三个代理同时执行<br/>各自在独立 worktree 中工作

    BugFix-->>Primary: 修复完成，返回变更摘要
    Test-->>Primary: 测试编写完成，覆盖率 85%→95%
    Doc-->>Primary: 文档已更新

    Primary->>Primary: 合并三个 worktree 的变更
    Primary->>Primary: 运行完整测试套件验证
    Primary-->>User: 三项任务全部完成

> 我需要同时完成三件事，请并行派发：
> 1. 在独立 worktree 中修复 src/api/auth.js 的 token 过期 Bug
> 2. 在独立 worktree 中为 src/utils/ 下所有工具函数补充单元测试
> 3. 更新 docs/api.md 中认证部分的文档
> 
> 修复和测试用 sonnet 模型，文档用 haiku 模型节省 token

stateDiagram-v2
    [*] --> Created: 创建 worktree
    Created --> Working: 子代理开始执行
    Working --> Completed: 任务完成
    Working --> Failed: 任务失败
    Completed --> Merged: Git merge/cherry-pick
    Failed --> Retried: 重试
    Failed --> Abandoned: 放弃
    Merged --> Cleaned: 自动清理
    Abandoned --> Cleaned: 手动清理
    Retried --> Working
    Cleaned --> [*]

# 查看所有 worktree
git worktree list

# 清理已合并的 worktree
git worktree prune

# 删除特定 worktree
git worktree remove .claude/worktrees/feature-auth

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[$(date)] Subagent started: $CLAUDE_SUBAGENT_NAME' >> .claude/agent-log.txt"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[$(date)] Subagent completed: $CLAUDE_SUBAGENT_NAME, duration: $CLAUDE_DURATION seconds' >> .claude/agent-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "general-purpose",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$CLAUDE_SUBAGENT_TOOLS' | grep -q 'Bash'; then echo 'approve'; else echo 'deny'; fi"
          }
        ]
      }
    ]
  }
}

---
name: perf-analyzer
description: |
  Analyzes code for performance bottlenecks including N+1 queries,
  memory leaks, unnecessary re-renders, and algorithmic complexity issues.
  Use when reviewing code for performance or optimizing existing modules.
model: sonnet
tools:
  - Glob
  - Grep
  - Read
  - Bash
allowed_commands:
  - "npx eslint"
  - "node"
  - "wc"
---

# Performance Analyzer Agent

You are a performance engineering specialist.

## Analysis Targets

1. **Database queries** — N+1 patterns, missing indexes, full table scans
2. **Memory patterns** — closures holding references, growing arrays, event listener leaks
3. **Algorithmic complexity** — O(n²) loops that should be O(n), nested iterations
4. **Network calls** — sequential requests that could be parallel, missing caching
5. **Bundle size** — large imports, unused dependencies

## Output Format

For each finding:
- Category: DB / Memory / Algorithm / Network / Bundle
- Severity: HIGH / MEDIUM / LOW
- Location: file:line
- Impact: estimated performance degradation
- Fix: recommended optimization with code example

#!/bin/bash
set -euo pipefail

# 获取当前分支相对于 main 的变更文件
CHANGED_FILES=$(git diff --name-only main...HEAD 2>/dev/null || git diff --name-only HEAD~1)

if [ -z "$CHANGED_FILES" ]; then
    echo "No changes detected."
    exit 0
fi

echo "=== Multi-Agent Code Review ==="
echo "Changed files:"
echo "$CHANGED_FILES"
echo ""

# 将变更文件列表写入临时文件供各代理读取
DIFF_FILE=$(mktemp)
git diff main...HEAD > "$DIFF_FILE" 2>/dev/null || git diff HEAD~1 > "$DIFF_FILE"

# 1. 安全审计（sonnet 模型，较深层分析）
echo "🔍 [1/3] Running security audit..."
claude -p \
    --model sonnet \
    "你是一个安全审计专家。审查以下代码变更，重点检查：
    - 硬编码密钥或凭证
    - SQL 注入 / XSS 风险
    - 不安全的依赖
    - CORS / CSRF 配置错误

    变更内容：
    $(cat "$DIFF_FILE")

    输出格式：每条发现包含严重程度(CRITICAL/HIGH/MEDIUM/LOW)、文件路径、问题描述。" \
    > /tmp/security-report.md 2>&1 &
SEC_PID=$!

# 2. 性能分析（sonnet 模型）
echo "⚡ [2/3] Running performance analysis..."
claude -p \
    --model sonnet \
    "你是一个性能分析专家。审查以下代码变更，重点检查：
    - N+1 数据库查询模式
    - 内存泄漏风险（未清理的事件监听器、闭包引用）
    - O(n²) 或更高复杂度的算法
    - 可并行化但被串行执行的网络请求

    变更内容：
    $(cat "$DIFF_FILE")

    输出格式：每条发现包含类别、严重程度、位置、影响评估、优化建议。" \
    > /tmp/perf-report.md 2>&1 &
PERF_PID=$!

# 3. 测试覆盖分析（haiku 模型，快速检查）
echo "🧪 [3/3] Analyzing test coverage..."
claude -p \
    --model haiku \
    "分析以下变更文件的测试覆盖情况：

    变更文件列表：
    $CHANGED_FILES

    对于每个变更文件，检查是否存在对应的测试文件。
    报告缺少测试的文件，以及已有测试但可能需要更新的文件。
    输出简洁的覆盖情况摘要。" \
    > /tmp/coverage-report.md 2>&1 &
COV_PID=$!

# 等待所有代理完成
wait $SEC_PID $PERF_PID $COV_PID

# 合并报告
echo ""
echo "============================================"
echo "       Multi-Agent Review Report"
echo "============================================"
echo ""
echo "## 🔒 Security Audit"
cat /tmp/security-report.md
echo ""
echo "## ⚡ Performance Analysis"
cat /tmp/perf-report.md
echo ""
echo "## 🧪 Test Coverage"
cat /tmp/coverage-report.md
echo ""
echo "============================================"

# 清理
rm -f "$DIFF_FILE" /tmp/security-report.md /tmp/perf-report.md /tmp/coverage-report.md

# 赋予执行权限
chmod +x scripts/multi-review.sh

# 创建 pre-push hook
cat > .git/hooks/pre-push << 'EOF'
#!/bin/bash
echo "Running multi-agent code review..."
bash scripts/multi-review.sh

# 如果任何代理报告 CRITICAL 级别问题，阻止 push
if grep -q "CRITICAL" /tmp/security-report.md 2>/dev/null; then
    echo "❌ Critical security issues found. Push blocked."
    exit 1
fi

echo "✅ Review passed."
exit 0
EOF

chmod +x .git/hooks/pre-push

# 手动触发审查
./scripts/multi-review.sh

# 预期输出示例：
# === Multi-Agent Code Review ===
# Changed files:
# src/api/auth.js
# src/utils/token.js
# src/middleware/cors.js
#
# 🔍 [1/3] Running security audit...
# ⚡ [2/3] Running performance analysis...
# 🧪 [3/3] Analyzing test coverage...
#
# ============================================
#        Multi-Agent Review Report
# ============================================
#
# ## 🔒 Security Audit
# MEDIUM: src/api/auth.js:42 — Token not validated on refresh
# LOW: src/middleware/cors.js:8 — Wildcard CORS origin in development
#
# ## ⚡ Performance Analysis
# HIGH: src/api/auth.js:56 — Sequential DB queries can be parallelized
# MEDIUM: src/utils/token.js:23 — Token decode called twice per request
#
# ## 🧪 Test Coverage
# src/api/auth.js → Missing test file
# src/utils/token.js → Test exists, may need update
# src/middleware/cors.js → Test exists, coverage adequate

flowchart TB
    subgraph Trigger["触发源"]
        T1["git push"]
        T2["手动执行脚本"]
        T3["CI/CD Pipeline"]
    end

    subgraph Orchestrator["编排层"]
        O1["multi-review.sh"]
        O2["读取 git diff"]
        O3["写入临时文件"]
    end

    subgraph Agents["并行代理集群"]
        A1["🔒 Security Agent<br/>model: sonnet"]
        A2["⚡ Perf Agent<br/>model: sonnet"]
        A3["🧪 Coverage Agent<br/>model: haiku"]
    end

    subgraph Aggregate["聚合层"]
        G1["合并三份报告"]
        G2{"有 CRITICAL？"}
        G3["✅ 通过"]
        G4["❌ 阻止推送"]
    end

    T1 & T2 & T3 --> O1
    O1 --> O2 --> O3
    O3 --> A1 & A2 & A3
    A1 & A2 & A3 -->|并行执行| G1
    G1 --> G2
    G2 -->|否| G3
    G2 -->|是| G4

# 策略一：--continue 继续上一次会话
claude --continue
# 自动加载最近一次会话的完整上下文

# 策略二：--resume 恢复指定会话
claude --resume
# 交互式选择历史会话

# 策略三：--name 命名会话（推荐用于多代理编排）
claude --name "security-review-sprint-42"
# 后续可通过名称精确恢复

flowchart LR
    subgraph Session1["会话 1：探索"]
        S1["Explore Agent<br/>扫描代码库"]
        S1 --> S2["输出：架构分析报告"]
    end

    subgraph Session2["会话 2：规划"]
        S3["读取架构分析"]
        S3 --> S4["Plan Agent<br/>设计重构方案"]
        S4 --> S5["输出：实施计划"]
    end

    subgraph Session3["会话 3：执行"]
        S6["读取实施计划"]
        S6 --> S7["并行 General-Purpose Agents"]
        S7 --> S8["输出：代码变更"]
    end

    subgraph Session4["会话 4：验证"]
        S9["读取变更"]
        S9 --> S10["运行测试"]
        S10 --> S11["输出：验证报告"]
    end

    S2 -->|传递| S3
    S5 -->|传递| S6
    S8 -->|传递| S9

#!/bin/bash
set -euo pipefail

PROJECT_DIR=$(pwd)
WORK_DIR="/tmp/claude-orchestration"
mkdir -p "$WORK_DIR"

# 阶段一：探索
echo "Phase 1: Exploring codebase..."
claude -p --model sonnet \
    "分析这个项目的架构，输出一份结构化的分析报告，包含：
    - 目录结构和模块划分
    - 核心依赖关系
    - 代码规模统计
    - 潜在的重构点
    保存报告到 $WORK_DIR/architecture.md" \
    --output-format text

# 阶段二：规划
echo "Phase 2: Planning refactoring..."
claude -p --model opus \
    "读取 $WORK_DIR/architecture.md，基于其中的分析，
    设计一个分步骤的重构方案。优先处理高耦合、低内聚的模块。
    输出每个步骤的具体文件变更清单。
    保存方案到 $WORK_DIR/plan.md" \
    --output-format text

# 阶段三：执行（并行）
echo "Phase 3: Executing refactoring in parallel..."
# 读取计划中的步骤数
STEPS=$(grep -c "^## Step" "$WORK_DIR/plan.md" 2>/dev/null || echo 1)

for i in $(seq 1 "$STEPS"); do
    echo "  Starting step $i..."
    claude -p --model sonnet \
        "读取 $WORK_DIR/plan.md，执行第 $i 步骤中的所有变更。
        完成后运行相关测试验证。" \
        --worktree "refactor-step-$i" \
        > "$WORK_DIR/step-$i-result.md" 2>&1 &
done

echo "  Waiting for all steps to complete..."
wait

# 阶段四：验证
echo "Phase 4: Validating all changes..."
claude -p --model sonnet \
    "检查所有 worktree 中的变更：
    1. 运行完整测试套件
    2. 检查是否有合并冲突
    3. 验证代码风格一致性
    输出最终验证报告到 $WORK_DIR/validation.md" \
    --output-format text

echo "All phases complete. Results in $WORK_DIR/"

graph TD
    A[任务到达] --> B{任务复杂度评估}
    B -->|简单搜索/格式化| C["Haiku<br/>$0.25/M tokens"]
    B -->|中等开发/重构| D["Sonnet<br/>$3/M tokens"]
    B -->|架构设计/安全审计| E["Opus<br/>$15/M tokens"]

    C --> F["Explore 快速搜索<br/>文档更新<br/>简单格式化"]
    D --> G["Bug 修复<br/>功能实现<br/>测试编写"]
    E --> H["架构评审<br/>安全审计<br/>复杂重构规划"]

# 在任务描述中明确指定输出格式和长度限制
> 分析 src/ 目录的代码结构，只输出目录级别的问题摘要，
> 不要输出每个文件的逐行分析

# 最小权限原则——只授权必要的工具
tools:
  - Read      # 只读文件
  - Grep      # 搜索内容
  # 不给 Edit/Write/Bash 权限

# 在对话中指定
> 使用 maxTurns=10 的 Explore 代理搜索所有 TODO 注释

# 或在 -p 模式中使用
claude -p "搜索所有 TODO" --max-turns 10

# 先让主代理输出上下文到文件
claude -p "分析项目架构，输出摘要到 context.md"

# 子代理读取上下文文件
claude -p "读取 context.md，基于其中的信息执行重构"

graph TB
    subgraph L1["第一层：单代理自动化<br/>（入门级）"]
        L1A["-p 模式<br/>单次执行"]
        L1B["--continue<br/>会话延续"]
        L1C["/loop<br/>定时循环"]
    end

    subgraph L2["第二层：多代理编排<br/>（进阶级）"]
        L2A["Task 工具<br/>子代理派发"]
        L2B["Worktree<br/>并行隔离"]
        L2C["Custom Agents<br/>专业代理"]
    end

    subgraph L3["第三层：流水线自动化<br/>（生产级）"]
        L3A["Shell 脚本<br/>多阶段编排"]
        L3B["CI/CD 集成<br/>GitHub Actions"]
        L3C["Routines<br/>云端定时任务"]
    end

    L1 --> L2 --> L3

    style L1 fill:#e8f5e9
    style L2 fill:#fff3e0
    style L3 fill:#e1f5fe