首页 › tutorials › Claude Code自动化三大武器实战全解

Claude Code自动化三大武器实战全解

概述

本教程面向已掌握Claude Code基础操作的开发者,深入讲解三大自动化武器:Headless模式(-p)、Hooks系统、批量任务编排。学完后你将能构建完整的自动化工作流——从CI/CD代码审查到批量重构、从安全防护到通知推送,让Claude Code从"对话助手"进化为"自动化引擎"。

适用人群:有Claude Code使用经验的开发者、DevOps工程师、需要大规模代码改造的技术负责人。

学习目标: - 掌握 -p 模式的所有参数与输出格式 - 独立配置Hooks的6种事件类型和Matcher模式 - 构建多步骤、可编排的批量自动化流水线

前置条件

条件 说明
Claude Code CLI 已安装并完成认证(claude 命令可用)
终端基础 熟悉 Bash/Zsh 管道、重定向、退出码
API Key ANTHROPIC_API_KEY 环境变量已配置
项目目录 一个有实际代码的 Git 仓库用于练习

第一部分:Headless模式——让Claude Code变成命令行工具

1.1 核心概念

Headless模式是Claude Code的非交互执行模式。当你使用 -p(或 --print)标志时,Claude Code不再启动交互式REPL,而是接受一条Prompt,执行后直接输出结果到stdout。

flowchart LR
    A["用户输入<br/>claude -p 'prompt'"] --> B["Headless模式<br/>非交互执行"]
    B --> C{"输出格式"}
    C -->|"--output-format text"| D["纯文本到stdout"]
    C -->|"--output-format json"| E["JSON结构体"]
    C -->|"--output-format stream-json"| F["NDJSON事件流"]
    D --> G["管道到其他命令"]
    E --> H["程序化解析"]
    F --> I["实时流式处理"]

1.2 基础用法

最简形式——一行命令获得回答:

claude -p "解释这个函数的作用:$(cat src/utils/parse.ts)"

管道输入——把文件内容"喂"给Claude:

cat error.log | claude -p "分析这些错误日志,找出根本原因"

输出重定向——结果写入文件:

claude -p "为 src/api/ 下所有接口生成TypeScript类型定义" > types.generated.ts

1.3 关键参数全览

参数 作用 示例
-p / --print 启用非交互模式 claude -p "prompt"
--output-format 输出格式:text/json/stream-json --output-format json
--max-turns 限制Agent最大执行轮数 --max-turns 5
--allowedTools 限制可用工具列表 --allowedTools "Read,Glob,Grep"
--model 指定使用的模型 --model claude-sonnet-4-6
--system-prompt 自定义系统提示 --system-prompt "你是一个代码审查专家"
--input-format 输入格式:text/stream-json --input-format stream-json
--resume 恢复之前的会话 --resume <session-id>
--append-system-prompt 追加系统提示(不覆盖默认) --append-system-prompt "项目使用React 19"

1.4 三种输出格式详解

格式一:text(默认)

纯文本输出,适合人类阅读和简单管道:

claude -p "列出package.json中过时的依赖" --output-format text
# 输出:直接的文字回答

格式二:json

返回结构化JSON,包含完整会话信息:

claude -p "这段代码有什么问题?" --output-format json

输出结构(简化):

{
  "result": "代码中存在以下问题...",
  "session_id": "abc-123-def",
  "cost_usd": 0.034,
  "duration_ms": 4500,
  "num_turns": 3,
  "is_error": false
}

格式三:stream-json

实时NDJSON(Newline Delimited JSON)事件流——这是自动化的核心:

claude -p "重构auth模块" --output-format stream-json --verbose

每行是一个JSON事件,关键事件类型包括:

{"type":"system","subtype":"init","session_id":"...","tools":[...]}
{"type":"assistant","subtype":"text","content":"我来分析auth模块..."}
{"type":"tool_use","name":"Read","input":{"file_path":"src/auth/index.ts"}}
{"type":"tool_result","name":"Read","output":"文件内容..."}
{"type":"result","result":"重构完成...","cost_usd":0.12,"duration_ms":12000}

1.5 多轮对话:stdin流式输入

通过 --input-format stream-json 可以实现多轮对话式自动化:

cat <<'EOF' | claude -p --input-format stream-json --output-format stream-json
{"type":"user","content":"分析src/api目录下的代码结构"}
{"type":"user","content":"为每个接口生成对应的单元测试"}
{"type":"user","content":"运行测试并报告结果"}
EOF

每条JSON消息代表一个用户轮次,Claude会按顺序处理所有轮次。

1.6 安全限制——工具白名单

在自动化场景中,限制Claude的工具权限是关键安全措施:

# 只读审查——不允许修改任何文件
claude -p "审查这个PR的安全问题" \
  --allowedTools "Read,Glob,Grep,Bash" \
  --max-turns 10

# 纯分析模式——只能读取和搜索
claude -p "生成项目架构文档" \
  --allowedTools "Read,Glob,Grep"

可用工具名列表:Read、Write、Edit、Bash、Glob、Grep、Task、WebSearch、TodoWrite、NotebookEdit 等。


第二部分:Hooks系统——为Agent行为装上"触发器"

2.1 Hooks架构总览

Hooks是Claude Code的事件驱动机制,允许你在特定时机注入自定义逻辑——无论是安全防护、自动格式化、还是通知推送。

flowchart TB
    subgraph "Hook事件生命周期"
        A["SessionStart"] --> B["UserPromptSubmit"]
        B --> C["PreToolUse"]
        C --> D["工具执行"]
        D --> E["PostToolUse"]
        E --> F["继续Agent循环"]
        F --> C
        F --> G["Stop"]
        G --> H["Notification"]
    end

    subgraph "Hook处理器类型"
        I["command<br/>Shell命令"]
        J["http<br/>HTTP请求"]
        K["prompt<br/>LLM判断"]
    end

    C -.-> I
    C -.-> J
    C -.-> K
    E -.-> I
    E -.-> J

2.2 六大Hook事件类型

事件 触发时机 典型用途
PreToolUse 工具执行之前 拦截危险操作、输入校验、权限控制
PostToolUse 工具执行之后 自动格式化、日志审计、触发通知
Notification Agent发出通知时 发送到Slack/Discord、桌面通知
Stop Agent会话结束时 执行清理、生成报告、记录指标
SubagentStop 子Agent结束时 聚合子Agent结果、资源清理
SessionStart 会话启动时 注入上下文、环境检测、加载配置

2.3 配置位置与优先级

Hooks可以在三个层级配置,优先级从低到高:

~/.claude/settings.json          # 全局配置(所有项目)
├── .claude/settings.json        # 项目级配置(团队共享)
└── .claude/settings.local.json  # 本地配置(个人偏好,不提交到Git)

2.4 配置Schema详解

完整的Hooks配置结构:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "your-script.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "send-slack-notification.sh"
          }
        ]
      }
    ]
  }
}

关键字段说明:

2.5 Hook输入输出协议

输入——Hook通过stdin接收JSON数据:

{
  "session_id": "sess_abc123",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "删除node_modules"
  }
}

输出——通过stdout返回JSON,退出码决定行为:

退出码 含义 效果
0 通过 继续执行(可返回额外信息)
2 阻止 阻止工具执行,向Agent显示原因

阻止执行的示例脚本:

#!/bin/bash
# block-dangerous-commands.sh
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -qE 'rm\s+-rf\s+/|drop\s+table|DROP\s+TABLE'; then
  echo '{"decision":"block","reason":"禁止执行危险操作:'$COMMAND'"}'
  exit 2
fi

exit 0

2.6 六大实战Hook配置

配置一:自动代码格式化(PostToolUse)

每次文件写入后自动格式化:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(cat | jq -r .tool_input.file_path); ext=${FILE##*.}; case $ext in ts|tsx|js|jsx) npx prettier --write \"$FILE\" ;; py) black \"$FILE\" ;; go) gofmt -w \"$FILE\" ;; esac'"
          }
        ]
      }
    ]
  }
}

配置二:保护敏感文件(PreToolUse)

阻止修改.env等敏感文件:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); if echo \"$FILE\" | grep -qE \"\\.env|credentials|secret|\\.pem\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"禁止修改敏感文件: $FILE\\\"}\"; exit 2; fi; exit 0'"
          }
        ]
      }
    ]
  }
}

配置三:Slack通知(Notification)

Agent任务完成时发送通知:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'MSG=$(cat | jq -r .message); curl -s -X POST \"$SLACK_WEBHOOK_URL\" -H \"Content-Type: application/json\" -d \"{\\\"text\\\":\\\"🤖 Claude Code: $MSG\\\"}\"'"
          }
        ]
      }
    ]
  }
}

配置四:Bash命令安全审计(PreToolUse)

记录并审查所有Shell命令执行:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo $INPUT | jq -r .tool_input.command); echo \"[$(date -Iseconds)] CMD: $CMD\" >> ~/.claude/bash-audit.log; if echo \"$CMD\" | grep -qE \"curl.*\\|.*sh|wget.*\\|.*bash\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"禁止管道到Shell执行\\\"}\"; exit 2; fi; exit 0'"
          }
        ]
      }
    ]
  }
}

配置五:测试自动运行(PostToolUse)

源码修改后自动运行相关测试:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(cat | jq -r .tool_input.file_path); if [[ \"$FILE\" == src/**/*.ts ]] && [[ \"$FILE\" != *.test.ts ]]; then TEST_FILE=\"${FILE%.ts}.test.ts\"; if [ -f \"$TEST_FILE\" ]; then npx vitest run \"$TEST_FILE\" 2>&1 | tail -5; fi; fi; exit 0'"
          }
        ]
      }
    ]
  }
}

配置六:会话启动环境检测(SessionStart)

每次会话开始时注入项目上下文:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"项目: $(basename $(pwd)) | 分支: $(git branch --show-current 2>/dev/null || echo N/A) | 最后提交: $(git log -1 --oneline 2>/dev/null || echo N/A)\"'"
          }
        ]
      }
    ]
  }
}

2.7 Matcher模式匹配技巧

matcher 字段使用正则表达式匹配工具名:

Bash             # 精确匹配Bash工具
Write|Edit       # 匹配Write或Edit
.*               # 匹配所有工具
Read|Glob|Grep   # 匹配所有只读工具

常见工具名列表:

工具名 类别
Read 文件读取
Write 文件创建
Edit 文件编辑
Bash Shell命令
Glob 文件搜索
Grep 内容搜索
Task 子Agent
TodoWrite 任务管理
WebSearch 网络搜索

2.8 Hooks调试技巧

验证Hook是否加载:

在Claude Code交互模式中使用 /hooks 命令查看当前已加载的所有Hooks。

调试Hook脚本:

# 手动测试Hook脚本
echo '{"session_id":"test","tool_name":"Bash","tool_input":{"command":"ls -la"}}' | bash your-hook-script.sh
echo "Exit code: $?"

查看Hook执行日志:

Hooks的标准错误输出会显示在Claude Code的调试信息中。启动时加上 --verbose 可以看到完整的Hook执行过程。


第三部分:批量任务编排——大规模自动化实战

3.1 三种批量执行模式对比

flowchart TB
    subgraph "模式一:Shell循环"
        A1["for file in *.ts"] --> A2["claude -p 处理单个文件"]
        A2 --> A3["下一个文件"]
    end

    subgraph "模式二:并行进程"
        B1["文件列表"] --> B2["xargs -P 并行"]
        B2 --> B3["多个claude -p同时执行"]
    end

    subgraph "模式三:/batch命令"
        C1["交互式输入"] --> C2["/batch"]
        C2 --> C3["自动并行spawn"]
    end
模式 优点 缺点 适用场景
Shell循环 简单、可控、顺序执行 速度慢 有依赖关系的任务
并行进程 快速、可控制并发数 需处理资源竞争 独立的大批量任务
/batch命令 智能调度、内置并行 仅交互模式可用 代码库大规模改造

3.2 模式一:Shell循环顺序执行

适合有依赖关系的多步任务:

#!/bin/bash
# migrate-api-endpoints.sh — 顺序迁移API端点

APIS=("users" "products" "orders" "payments" "notifications")

for api in "${APIS[@]}"; do
  echo "=== 迁移 $api API ==="
  claude -p "将 src/api/$api.ts 从Express风格迁移到Fastify风格。保持所有接口签名不变,只修改框架相关代码。" \
    --output-format text \
    --max-turns 15 \
    --allowedTools "Read,Write,Edit,Bash,Glob,Grep"

  echo "=== 运行 $api 测试 ==="
  npx vitest run "src/api/$api.test.ts"

  if [ $? -ne 0 ]; then
    echo "❌ $api 测试失败,停止迁移"
    exit 1
  fi
  echo "✅ $api 迁移完成"
done

echo "🎉 所有API迁移完成"

3.3 模式二:并行进程批量执行

适合独立的、无依赖关系的任务:

#!/bin/bash
# batch-add-tests.sh — 并行为所有模块生成测试

MAX_PARALLEL=4  # 控制并发数

generate_test() {
  local file=$1
  local test_file="${file%.ts}.test.ts"

  if [ -f "$test_file" ]; then
    echo "跳过 $file(测试已存在)"
    return
  fi

  echo "为 $file 生成测试..."
  claude -p "为以下文件生成完整的单元测试:$file。使用vitest框架,覆盖所有导出函数,包含正常路径和边界情况。" \
    --output-format text \
    --max-turns 10 \
    --allowedTools "Read,Write,Glob,Grep" \
    > "$test_file"

  echo "✅ $test_file 已生成"
}

export -f generate_test

# 查找所有源文件并并行处理
find src -name "*.ts" ! -name "*.test.ts" ! -name "*.d.ts" | \
  xargs -P $MAX_PARALLEL -I {} bash -c 'generate_test "$@"' _ {}

echo "🎉 批量测试生成完成"

3.4 模式三:/batch命令

/batch 是Claude Code v2.1.63引入的内置命令,在交互模式下使用,能自动并行spawn子Agent处理多个文件:

使用方式:

> /batch 将所有 src/components/ 下的组件从 Class 组件迁移为函数组件

/batch的工作机制:

  1. Claude分析任务,确定需要修改的文件列表
  2. 为每个文件(或文件组)spawn独立的子Agent
  3. 子Agent并行执行,各自处理分配的文件
  4. 所有子Agent完成后,主Agent汇总结果

/batch适用场景: - 大规模重命名/迁移(如替换API、更新import路径) - 批量添加JSDoc注释 - 批量修改代码风格(如从Options API改Composition API) - 批量添加错误处理

3.5 多步骤Pipeline:组合三大武器

将Headless模式、Hooks和批量执行组合成完整的自动化Pipeline:

flowchart TB
    A["Git Push触发"] --> B["PreToolUse Hook<br/>环境检查"]
    B --> C["Step 1: claude -p<br/>代码审查"]
    C --> D["PostToolUse Hook<br/>记录审查结果"]
    D --> E["Step 2: claude -p<br/>自动修复"]
    E --> F["PostToolUse Hook<br/>自动格式化+测试"]
    F --> G["Step 3: claude -p<br/>生成变更摘要"]
    G --> H["Notification Hook<br/>发送Slack通知"]
    H --> I["Stop Hook<br/>生成最终报告"]

完整的Pipeline脚本:

#!/bin/bash
# auto-code-review-pipeline.sh — 全自动代码审查Pipeline

set -euo pipefail

BRANCH=$(git branch --show-current)
DIFF=$(git diff main...HEAD --stat)
SESSION_ID=""

echo "🚀 启动代码审查Pipeline — 分支: $BRANCH"
echo "📊 变更文件统计:"
echo "$DIFF"

# Step 1: 安全审查
echo ""
echo "=== Step 1/3: 安全审查 ==="
SECURITY_REPORT=$(claude -p "审查以下Git diff中的安全隐患(SQL注入、XSS、硬编码密钥、不安全的依赖)。只报告确定的漏洞,不要误报。输出JSON格式:{\"issues\": [{\"file\": \"...\", \"line\": N, \"severity\": \"high|medium|low\", \"description\": \"...\"}]}

Diff:
$(git diff main...HEAD)" \
  --output-format json \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 8)

echo "$SECURITY_REPORT" | jq '.result' 2>/dev/null || echo "$SECURITY_REPORT"

# Step 2: 代码质量改进建议
echo ""
echo "=== Step 2/3: 质量审查 ==="
QUALITY_REPORT=$(claude -p "审查以下Git diff的代码质量。关注:1)性能问题 2)可维护性 3)测试覆盖率 4)错误处理。输出简洁的改进建议列表。

Diff:
$(git diff main...HEAD)" \
  --output-format text \
  --allowedTools "Read,Glob,Grep,Bash" \
  --max-turns 10)

echo "$QUALITY_REPORT"

# Step 3: 生成PR摘要
echo ""
echo "=== Step 3/3: 生成变更摘要 ==="
SUMMARY=$(claude -p "为以下代码变更生成一个简洁的PR描述,包括:1)主要变更内容(3-5个要点)2)影响范围 3)建议的测试重点

Diff stat:
$(git diff main...HEAD --stat)

最近的Commits:
$(git log main..HEAD --oneline)" \
  --output-format text \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 5)

echo "$SUMMARY"

# 输出最终报告
echo ""
echo "========================================="
echo "📋 审查报告已生成"
echo "========================================="

3.6 CI/CD集成实战

GitHub Actions集成示例:

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: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run AI Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "你是高级代码审查员。审查这个PR的变更,重点关注:
          1. 安全漏洞(OWASP Top 10)
          2. 性能退化
          3. 逻辑错误
          4. 测试覆盖是否充分

          只报告确定的、可操作的问题。不要报告风格偏好。

          变更内容:
          $(git diff origin/main...HEAD)" \
            --output-format text \
            --allowedTools "Read,Glob,Grep,Bash" \
            --max-turns 15 \
            > review_output.md

      - name: Post Review Comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file review_output.md

Git Pre-commit Hook集成:

#!/bin/bash
# .git/hooks/pre-commit — 提交前自动审查

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx|py)$')

if [ -z "$STAGED_FILES" ]; then
  exit 0
fi

echo "🔍 AI审查暂存文件..."

REVIEW=$(claude -p "快速审查以下文件的代码质量,只报告严重问题。如果代码质量可接受,输出PASS。

文件列表:
$STAGED_FILES

具体内容:
$(git diff --cached)" \
  --output-format text \
  --max-turns 5 \
  --allowedTools "Read,Glob,Grep")

echo "$REVIEW"

if echo "$REVIEW" | grep -q "BLOCK"; then
  echo "❌ 代码审查未通过,请修复上述问题后重新提交"
  exit 1
fi

echo "✅ 代码审查通过"
exit 0

3.7 高级模式:RALF循环

对于特别大的任务(如全项目迁移),可以采用RALF(Read-Analyze-Loop-Fix)循环模式,将多个Claude Code会话串联起来:

#!/bin/bash
# ralf-loop-migration.sh — RALF循环模式

TARGET_FILES=($(find src -name "*.vue" -type f))
MAX_ITERATIONS=5
PASS=0

while [ $PASS -lt $MAX_ITERATIONS ]; do
  PASS=$((PASS + 1))
  echo "=== 第 $PASS 轮 ==="

  # Read & Analyze
  ISSUES=$(claude -p "检查以下Vue组件是否已完全迁移到Vue 3 Composition API。列出仍使用Options API的组件。

文件列表:
$(printf '%s\n' "${TARGET_FILES[@]}")" \
    --output-format text \
    --allowedTools "Read,Glob,Grep" \
    --max-turns 8)

  if echo "$ISSUES" | grep -q "全部迁移完成\|没有遗留问题\|all migrated"; then
    echo "🎉 迁移完成!共 $PASS 轮"
    break
  fi

  echo "发现问题:"
  echo "$ISSUES"

  # Loop & Fix
  claude -p "根据以下问题列表,修复所有未完成迁移的Vue组件。

问题:
$ISSUES" \
    --output-format text \
    --max-turns 20 \
    --allowedTools "Read,Write,Edit,Glob,Grep,Bash"

  # 运行测试验证
  npx vitest run 2>&1 | tail -10
done

第四部分:综合实战案例——全自动代码质量守护

4.1 场景描述

构建一个完整的自动化系统,当代码变更时自动:审查安全→运行测试→修复问题→更新文档→发送通知。

4.2 完整项目结构

project/
├── .claude/
│   ├── settings.json          # Hooks配置
│   └── settings.local.json    # 本地配置
├── scripts/
│   └── auto-quality-guard.sh  # 主Pipeline脚本
├── CLAUDE.md                  # Claude行为指引
└── .github/
    └── workflows/
        └── quality-guard.yml  # CI/CD配置

4.3 配置文件

.claude/settings.json——项目级Hooks:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); if echo \"$FILE\" | grep -qE \"\\.env|credentials|\\.pem|secret\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"安全策略:禁止修改敏感文件 $FILE\\\"}\"; exit 2; fi; exit 0'"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo $INPUT | jq -r .tool_input.command); echo \"[$(date -Iseconds)] BASH: $CMD\" >> .claude/command-log.txt; if echo \"$CMD\" | grep -qE \"rm\\s+-rf\\s+/|DROP\\s+TABLE|truncate\"; then echo \"{\\\"decision\\\":\\\"block\\\",\\\"reason\\\":\\\"危险命令被拦截: $CMD\\\"}\"; exit 2; fi; exit 0'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); ext=${FILE##*.}; case $ext in ts|tsx|js|jsx) npx prettier --write \"$FILE\" 2>/dev/null; npx eslint --fix \"$FILE\" 2>/dev/null ;; py) black \"$FILE\" 2>/dev/null ;; esac; exit 0'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'MSG=$(cat | jq -r .message // .text // empty); if [ -n \"$MSG\" ] && [ -n \"$SLACK_WEBHOOK\" ]; then curl -s -X POST \"$SLACK_WEBHOOK\" -H \"Content-Type: application/json\" -d \"{\\\"text\\\":\\\"[Claude Code] $MSG\\\"}\" > /dev/null; fi; exit 0'"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo \"项目: $(basename $(pwd)) | 分支: $(git branch --show-current 2>/dev/null || echo detached) | 最后提交: $(git log -1 --oneline 2>/dev/null || echo none) | Node: $(node -v 2>/dev/null || echo N/A)\"'"
          }
        ]
      }
    ]
  }
}

scripts/auto-quality-guard.sh:

#!/bin/bash
set -euo pipefail

PROJECT_DIR=$(pwd)
REPORT_DIR="$PROJECT_DIR/.claude/reports"
mkdir -p "$REPORT_DIR"

TIMESTAMP=$(date +%Y%m%d_%H%M%S)
REPORT_FILE="$REPORT_DIR/quality-$TIMESTAMP.md"

echo "# 代码质量报告 - $(date +%Y-%m-%d\ %H:%M)" > "$REPORT_FILE"
echo "" >> "$REPORT_FILE"

# Step 1: 安全扫描
echo "## 1. 安全扫描" >> "$REPORT_FILE"
SEC_RESULT=$(claude -p "扫描项目中所有源文件的安全问题。重点检查:
- 硬编码的密钥或Token
- SQL注入风险
- XSS风险
- 不安全的依赖引用
- 敏感信息泄露

输出格式:按严重程度排序,每条包含文件路径、行号、问题描述。" \
  --output-format text \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 12)

echo "$SEC_RESULT" >> "$REPORT_FILE"
echo "" >> "$REPORT_FILE"

# Step 2: 代码质量分析
echo "## 2. 代码质量分析" >> "$REPORT_FILE"
QUALITY_RESULT=$(claude -p "分析项目代码质量,输出以下指标:
1. 重复代码比例较高的区域
2. 圈复杂度超过10的函数
3. 过长的函数(超过50行)
4. 缺少错误处理的异步函数
5. 潜在的性能瓶颈

给出具体的文件路径和行号。" \
  --output-format text \
  --allowedTools "Read,Glob,Grep,Bash" \
  --max-turns 15)

echo "$QUALITY_RESULT" >> "$REPORT_FILE"
echo "" >> "$REPORT_FILE"

# Step 3: 测试覆盖率分析
echo "## 3. 测试覆盖分析" >> "$REPORT_FILE"
COV_RESULT=$(claude -p "分析项目的测试覆盖率。列出:
1. 没有对应测试的源文件
2. 测试中缺少的边界情况
3. 建议优先添加测试的模块(按风险排序)" \
  --output-format text \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 10)

echo "$COV_RESULT" >> "$REPORT_FILE"

# 输出报告位置
echo ""
echo "📊 质量报告已生成: $REPORT_FILE"
cat "$REPORT_FILE"

.github/workflows/quality-guard.yml:

name: AI Quality Guard

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * 1'  # 每周一凌晨2点

jobs:
  quality-scan:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: |
          npm ci
          npm install -g @anthropic-ai/claude-code

      - name: Security Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "审查这个仓库的安全状况。检查所有源代码文件中是否存在:硬编码密钥、SQL注入、XSS、不安全的反序列化、路径遍历。输出JSON格式报告。" \
            --output-format json \
            --allowedTools "Read,Glob,Grep" \
            --max-turns 15 > security-report.json

      - name: Quality Analysis
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "分析代码库的整体质量。重点关注:代码复杂度、重复代码、错误处理、API设计。输出改进建议列表,按优先级排序。" \
            --output-format text \
            --allowedTools "Read,Glob,Grep,Bash" \
            --max-turns 12 > quality-report.md

      - name: Upload Reports
        uses: actions/upload-artifact@v4
        with:
          name: quality-reports
          path: |
            security-report.json
            quality-report.md

      - name: Comment on PR
        if: github.event_name == 'pull_request'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file quality-report.md

第五部分:进阶技巧与最佳实践

5.1 成本控制策略

自动化场景容易产生大量API调用,需要严格控制:

# 限制最大轮数,防止Agent"跑飞"
claude -p "任务" --max-turns 5

# 使用更经济的模型处理简单任务
claude -p "格式化这个文件" --model claude-haiku-4-5

# 只读任务限制工具,减少不必要调用
claude -p "分析代码" --allowedTools "Read,Glob,Grep"

5.2 错误处理与重试

#!/bin/bash
# 带重试的Claude Code调用

call_claude_with_retry() {
  local prompt="$1"
  local max_retries=3
  local attempt=1

  while [ $attempt -le $max_retries ]; do
    RESULT=$(claude -p "$prompt" --output-format json 2>&1)
    EXIT_CODE=$?

    if [ $EXIT_CODE -eq 0 ]; then
      echo "$RESULT"
      return 0
    fi

    echo "尝试 $attempt/$max_retries 失败,退出码: $EXIT_CODE" >&2
    attempt=$((attempt + 1))
    sleep 5
  done

  echo "所有重试失败" >&2
  return 1
}

5.3 会话复用——--resume

对于复杂任务,可以保存会话ID并在后续继续:

# 第一次调用,获取session_id
RESULT=$(claude -p "分析项目架构" --output-format json)
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')
echo "Session ID: $SESSION_ID" > .claude/last-session

# 后续调用,继续同一会话
claude -p "基于刚才的分析,生成架构改进方案" \
  --resume "$SESSION_ID" \
  --output-format text

5.4 Stream-JSON实时处理

使用 jq 实时过滤stream-json输出:

claude -p "重构整个auth模块" \
  --output-format stream-json \
  --max-turns 20 \
  | while read -r line; do
    TYPE=$(echo "$line" | jq -r '.type // empty')
    case "$TYPE" in
      tool_use)
        TOOL=$(echo "$line" | jq -r '.name')
        echo "🔧 使用工具: $TOOL"
        ;;
      tool_result)
        echo "✅ 工具执行完成"
        ;;
      result)
        COST=$(echo "$line" | jq -r '.cost_usd')
        DURATION=$(echo "$line" | jq -r '.duration_ms')
        echo "💰 费用: \$$COST | ⏱ 耗时: ${DURATION}ms"
        ;;
    esac
  done

5.5 完整工作流Mermaid图

flowchart TB
    subgraph "触发层"
        T1["Git Push"]
        T2["定时任务"]
        T3["手动触发"]
        T4["PR创建"]
    end

    subgraph "Hook拦截层"
        H1["SessionStart<br/>环境检测"]
        H2["PreToolUse<br/>安全防护"]
        H3["PostToolUse<br/>自动格式化"]
        H4["Notification<br/>消息推送"]
    end

    subgraph "执行层"
        E1["claude -p<br/>代码审查"]
        E2["claude -p<br/>自动修复"]
        E3["claude -p<br/>测试生成"]
        E4["claude -p<br/>文档更新"]
    end

    subgraph "输出层"
        O1["JSON报告"]
        O2["Git Commit"]
        O3["PR评论"]
        O4["Slack通知"]
    end

    T1 --> H1 --> E1
    T4 --> E1
    T2 --> E1
    T3 --> E1
    E1 --> E2 --> E3 --> E4
    E1 --> H2
    E2 --> H2
    E2 --> H3
    E4 --> H4
    E1 --> O1
    E2 --> O2
    E1 --> O3
    H4 --> O4

延伸阅读

资源 说明
Claude Code Headless模式官方文档 编程式使用Claude Code的权威参考
Claude Code Hooks官方文档 Hooks的完整Schema和事件参考
Claude Code CLI Reference 所有CLI标志和命令的完整列表
Stream-JSON Protocol Reference stream-json协议的详细事件类型文档
Claude Code Hooks完整指南 20+个即用型Hooks配置示例

参考来源

  1. Run Claude Code programmatically - Claude Code Docs — Headless模式官方文档,涵盖-p标志、输出格式、stdin管道
  2. Hooks reference - Claude Code Docs — Hooks官方参考,包含所有事件类型、JSON Schema、退出码说明
  3. Claude Code Batch Processing Complete Guide — /batch命令和批量处理模式的系统指南
  4. Claude Code Hooks Schemas Reference (GitHub Gist) — Hooks输入输出JSON Schema的精确实现参考
  5. Stream-JSON Protocol Reference (GitHub) — stream-json输出格式的完整事件类型文档

[!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学通信知识星球海报-扫码加入