Claude Code Agent模式与自动化实战全攻略：从 -p 无头模式到多 Agent 编排

# 确认版本
claude --version
# 预期输出: claude-code/2.1.xxx

graph TB
    subgraph L1["第1层：无头模式"]
        H1["claude -p"]
        H2["stdin 管道"]
        H3["--output-format"]
    end

    subgraph L2["第2层：事件钩子"]
        K1["PreToolUse"]
        K2["PostToolUse"]
        K3["Stop / Notification"]
    end

    subgraph L3["第3层：定时与循环"]
        S1["/loop 固定间隔"]
        S2["/loop 动态间隔"]
        S3["CronCreate API"]
    end

    subgraph L4["第4层：多Agent编排"]
        A1["Subagents 子代理"]
        A2["Agent Teams 团队"]
        A3["Dynamic Workflows 工作流"]
    end

    L1 --> L2 --> L3 --> L4

    style L1 fill:#e8f5e9
    style L2 fill:#e3f2fd
    style L3 fill:#fff3e0
    style L4 fill:#fce4ec

# 方式1：直接传入提示词
claude -p "为 src/auth.ts 中的 login 函数编写单元测试"

# 方式2：通过管道传入文件内容
cat src/auth.ts | claude -p "审查这段代码中的安全漏洞"

# 方式3：重定向文件输入
claude -p "总结这个模块的功能" < README.md

# 方式4：组合管道
echo "修复 main.py 中的类型错误" | claude -p

# JSON 格式输出，便于程序解析
claude -p "列出 package.json 中的所有依赖" \
  --output-format json

# 纯文本流式输出
claude -p "生成 CHANGELOG" \
  --output-format stream-json

# 仅输出文本内容（适合管道拼接）
claude -p "将以下错误日志分类" < error.log \
  --output-format text

# .github/workflows/claude-review.yml
name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

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

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # 获取变更文件列表
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)

          # 让 Claude 审查变更
          claude -p "审查以下变更文件中的代码质量问题、安全漏洞和性能问题：
          变更文件：${CHANGED_FILES}

          请用以下格式输出：
          1. 🔴 严重问题
          2. 🟡 建议改进
          3. 🟢 良好实践
          " --output-format text > review_output.md

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review_output.md', 'utf8');
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## 🤖 Claude Code Review\n\n${review}`
            });

#!/bin/bash
# batch-todo.sh — 批量处理 TODO 注释

PROJECT_DIR="${1:-.}"
OUTPUT_DIR="./claude-reports"
mkdir -p "$OUTPUT_DIR"

# 查找所有包含 TODO 的文件
TODO_FILES=$(grep -rl "TODO\|FIXME\|HACK" "$PROJECT_DIR" \
  --include="*.ts" --include="*.py" --include="*.js" | head -20)

for file in $TODO_FILES; do
  filename=$(basename "$file")
  echo "正在处理: $file"

  # 用 Claude 分析每个文件的 TODO
  claude -p "分析以下文件中的所有 TODO/FIXME/HACK 注释。
  对于每个注释：
  1. 估算优先级（P0-P3）
  2. 建议修复方案
  3. 预估工作量（分钟）

  输出 JSON 格式。" < "$file" \
    --output-format json \
    > "${OUTPUT_DIR}/${filename}.todo.json"
done

echo "处理完成，报告保存在 ${OUTPUT_DIR}/"

sequenceDiagram
    participant U as 用户
    participant C as Claude Agent
    participant H as Hook 系统
    participant T as 工具

    U->>C: 发送指令
    C->>H: PreToolUse 事件
    H->>H: 执行匹配器过滤
    alt Hook 返回 deny
        H-->>C: 阻止执行
        C-->>U: 操作被拦截
    else Hook 返回 allow
        H-->>C: 允许执行
        C->>T: 执行工具
        T-->>C: 返回结果
        C->>H: PostToolUse 事件
        H->>H: 记录/转换结果
    end

# 全局配置
~/.claude/settings.json

# 项目配置
.claude/settings.json

# 项目本地配置（不提交到 Git）
.claude/settings.local.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"\nimport sys, json\ninput_data = json.load(sys.stdin)\nfile_path = input_data.get('tool_input', {}).get('file_path', '')\nif '.env' in file_path or 'credentials' in file_path:\n    print(json.dumps({\n        'decision': 'deny',\n        'reason': '⛔ 安全策略：禁止修改敏感文件 ' + file_path\n    }))\n    sys.exit(0)\nprint(json.dumps({}))\n\""
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/protect-sensitive.sh
# PreToolUse hook: 保护敏感文件

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# 敏感文件模式
SENSITIVE_PATTERNS=(
  ".env"
  "credentials"
  "secrets"
  ".pem"
  ".key"
  "id_rsa"
)

for pattern in "${SENSITIVE_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    jq -n --arg reason "⛔ 安全策略：禁止修改包含 '$pattern' 的文件" \
      '{decision: "deny", reason: $reason}'
    exit 0
  fi
done

# 允许操作
echo '{}'

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/protect-sensitive.sh"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/auto-format.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/auto-format.sh
# PostToolUse hook: 自动格式化

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then
  echo '{}'
  exit 0
fi

EXT="${FILE_PATH##*.}"

case "$EXT" in
  ts|tsx|js|jsx|json|css|md)
    npx prettier --write "$FILE_PATH" 2>/dev/null
    ;;
  py)
    python3 -m black "$FILE_PATH" 2>/dev/null
    ;;
  go)
    gofmt -w "$FILE_PATH" 2>/dev/null
    ;;
esac

echo '{}'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/notify-slack.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/notify-slack.sh
# Notification hook: 转发到 Slack

INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message // empty')

if [ -z "$MESSAGE" ]; then
  echo '{}'
  exit 0
fi

# 发送到 Slack Webhook
curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d "{\"text\": \"🤖 Claude Code: $MESSAGE\"}" > /dev/null 2>&1

echo '{}'

// 精确匹配单个工具
"matcher": "Bash"

// 匹配多个工具（管道符表示 OR）
"matcher": "Write|Edit"

// 匹配所有文件操作
"matcher": "Write|Edit|NotebookEdit"

// 匹配所有工具（空字符串或省略）
"matcher": ""

// 使用正则表达式
"matcher": "Bash|Write|Edit"

# 每5分钟检查部署状态
/loop 5m check if the deployment finished and tell me what happened

# 每30分钟检查 PR 审查评论
/loop 30m check for new review comments on PR #42 and address them

# 每2小时运行代码审查
/loop 2h /review

# Claude 自行决定检查频率
/loop check whether CI passed and address any review comments

# 裸 /loop 运行内置维护提示
/loop

<!-- .claude/loop.md — 项目级循环维护指令 -->

检查 `release/next` 分支的 PR 状态：
1. 如果 CI 红灯，拉取失败日志，诊断并推送最小修复
2. 如果有新审查评论，逐一处理
3. 如果出现合并冲突，解决并更新
4. 如果一切正常，报告当前状态即可

请帮我设置以下定时任务：
1. 每天早上9点（避开整点）检查未处理的 PR
2. 每小时检查一次测试流水线状态
3. 30分钟后提醒我做代码评审

CronCreate({
  cron: "57 8 * * 1-5",          // 工作日 8:57
  prompt: "检查未处理的 PR 并汇报",
  recurring: true,
  durable: false                   // 会话级
})

CronCreate({
  cron: "7 * * * *",             // 每小时第7分钟
  prompt: "检查 CI 流水线状态",
  recurring: true
})

CronCreate({
  cron: "30 14 10 6 *",          // 6月10日 14:30（一次性）
  prompt: "提醒：该做代码评审了",
  recurring: false
})

graph TD
    START["需要并行工作"] --> Q1{"谁协调任务？"}
    Q1 -->|"我自己逐步委派"| SUB["Subagents<br/>子代理"]
    Q1 -->|"我想甩手不管"| AV["Agent View<br/>后台调度"]
    Q1 -->|"让 Claude 自动分工"| TEAM["Agent Teams<br/>团队协作"]
    Q1 -->|"写成脚本可复现"| WF["Dynamic Workflows<br/>动态工作流"]

    SUB --> S1["场景：搜索结果汇总<br/>代码审查副任务"]
    AV --> S2["场景：多个独立研究<br/>并行开发功能"]
    TEAM --> S3["场景：项目拆分开发<br/>需要同步进度"]
    WF --> S4["场景：500+文件迁移<br/>代码库全量审计"]

    style SUB fill:#e8f5e9
    style AV fill:#e3f2fd
    style TEAM fill:#fff3e0
    style WF fill:#fce4ec

请帮我做以下事情：
1. 搜索整个代码库中使用 deprecated API 的地方
2. 检查所有测试文件的覆盖率
3. 审查最近5个 PR 的代码质量

# 打开 Agent View
claude agents

# 在 Agent View 中可以：
# → 查看所有后台会话的状态
# → 切入某个需要输入的会话
# → 一目了然地监控进度

# 深度研究工作流——多源检索 + 交叉验证 + 合成报告
/deep-research Node.js v20 到 v22 的权限模型发生了什么变化？

// 安全审计工作流
export const meta = {
  name: 'security-audit',
  description: '代码库安全审计：多维度扫描 + 对抗验证',
  phases: [
    { title: '扫描', detail: '并行多维度安全扫描' },
    { title: '验证', detail: '对抗验证每个发现' },
    { title: '合成', detail: '汇总确认的安全问题' }
  ]
}

// 阶段1：多维度扫描
phase('扫描')

const DIMENSIONS = [
  { key: 'injection', prompt: '搜索所有 SQL 注入、命令注入和 XSS 漏洞' },
  { key: 'auth', prompt: '审查认证和授权逻辑中的安全缺陷' },
  { key: 'secrets', prompt: '查找硬编码的密钥、token 和凭证' },
  { key: 'deps', prompt: '检查依赖中的已知漏洞和过时包' }
]

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

// 并行扫描：每个维度一个 Agent
const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, {
    label: `scan:${d.key}`,
    phase: '扫描',
    schema: FINDING_SCHEMA
  }),
  // 阶段2：每个发现进行对抗验证
  scanResult => {
    if (!scanResult || !scanResult.findings) return null
    return parallel(
      scanResult.findings.map(f => () =>
        agent(
          `尝试反驳以下安全发现，验证其是否为真实漏洞：\n
          文件：${f.file}:${f.line}\n
          描述：${f.description}\n
          如果无法反驳，标记为 confirmed=true`,
          { label: `verify:${f.file}`, phase: '验证', schema: VERDICT_SCHEMA }
        )
        .then(v => ({ ...f, verdict: v }))
      )
    )
  }
)

// 合成最终报告
const confirmed = results
  .flat()
  .filter(Boolean)
  .filter(r => r.verdict?.confirmed)

return { confirmed, total: confirmed.length }

# 查看所有工作流
/workflows

# 监控特定运行的进度
# ↑/↓ 选择运行 → Enter 展开详情
# 可以看到每个阶段的 Agent 数量、token 用量和耗时

# 恢复暂停的运行（修改脚本后）
# Workflow 会自动使用缓存的已完成 Agent 结果

graph LR
    subgraph "CI Pipeline"
        A[git push] --> B["claude -p<br/>代码审查"]
        B --> C{审查通过？}
        C -->|是| D[合并 PR]
        C -->|否| E[发送评论]
    end

    subgraph "Hooks 防护"
        F["PreToolUse<br/>阻止危险操作"] --> G["PostToolUse<br/>自动格式化"]
        G --> H["Notification<br/>Slack 告警"]
    end

    subgraph "定时监控"
        I["/loop 10m<br/>部署状态检查"] --> J["/loop 动态<br/>PR 看护"]
    end

    subgraph "批量任务"
        K["Workflow<br/>全量安全审计"]
    end

    D --> I
    F -.-> B
    K -.-> A

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/guard-commands.sh"
        }]
      },
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/protect-sensitive.sh"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/auto-format.sh"
        }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": "bash .claude/hooks/notify-slack.sh"
        }]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(npm test*)",
      "Bash(npx prettier*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(curl*| bash)"
    ]
  }
}

#!/bin/bash
# .claude/hooks/guard-commands.sh
# PreToolUse hook: 拦截危险的 Bash 命令

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 危险命令模式
DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "DROP TABLE"
  "truncate"
  ":(){ :|:& };:"
  "dd if="
  "mkfs"
  "> /dev/sda"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if [[ "$COMMAND" == *"$pattern"* ]]; then
    jq -n --arg cmd "$COMMAND" --arg pat "$pattern" \
      '{decision: "deny", reason: "⛔ 拦截危险命令: 匹配模式 [\($pat)]"}'
    exit 0
  fi
done

echo '{}'

// 在工作流脚本中使用预算控制
const budget = { total: 500000 } // 50万 token 上限

while (budget.total && budget.remaining() > 50000) {
  const result = await agent("Find bugs in this codebase", {
    schema: BUGS_SCHEMA
  })
  bugs.push(...result.bugs)
  log(`${bugs.length} found, ${Math.round(budget.remaining()/1000)}k remaining`)
}

┌──────────────────────────────────────────────────┐
│  < 5 分钟（60s-270s）                              │
│  → 缓存命中，低延迟                                │
│  → 适合：活跃监控 CI 构建                          │
├──────────────────────────────────────────────────┤
│  5 分钟 - 1 小时（300s-3600s）                     │
│  → 缓存失效，每次全量加载                          │
│  → 适合：非紧急的定期检查                          │
├──────────────────────────────────────────────────┤
│  > 1 小时                                         │
│  → 低频，总体 Token 消耗最低                      │
│  → 适合：日报、周报生成                            │
└──────────────────────────────────────────────────┘

第1级：权限白名单（permissions.allow）
  ↓ 未匹配
第2级：PreToolUse Hooks（条件性拦截）
  ↓ 通过
第3级：Claude 自主判断（AI 安全评估）
  ↓ 通过
第4级：执行操作