Headless模式与CI/CD集成1

• 引入Claude作为PR的“初审员”，自动执行安全检查、代码质量分析及测试覆盖率评估，并生成结构化的审查报告。人工审查员则基于该报告进行最终决策，将精力集中于业务逻辑与架构设计等核心领域。

1 从人机交互到无人值守：一次关键的架构演进

点击查看代码

# 最基本的Headless模式调用
claude -p "分析src/目录的安全漏洞"
# 等价的完整形式
claude --print "分析src/目录的安全漏洞"

2 核心参数体系：4个维度的控制

2.1 输出格式控制

• output-format参数是连接Claude Code与下游自动化流水线的“协议转换器”。
• 该参数包含3种核心格式——text格式、json格式和stream-json格式。

1. text格式

点击查看代码

claude -p "列出主要问题" --output-format text 

2. json格式

点击查看代码

claude -p "审查 PR" --output-format json

{
  "type": "result",
  "subtype": "success",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_error": false,
  "duration_ms": 12345,
  "duration_api_ms": 10000,
  "num_turns": 5,
  "total_cost_usd": 0.0342,
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 1500,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 3000
  },
  "result": "发现2个 Critical问题：\n1. SQL注入风险...",
  "structured_output": null
}

3. stream-json格式

• 逐行输出JSON事件（即NDJSON格式），专为长任务的实时监控而设计。

点击查看代码

claude-p "分析代码" --output-format stream-json

{"type":"system","subtype":"init","session_id":"...","model":"claude-sonnet-4-6","tools":["Read","Grep","Glob"]}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"正在分析..."}]}}
{"type":"user","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"...","content":"..."}]}}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"分析完成。"}]}}
{"type":"result","subtype":"success","total_cost_usd":0.03,"result":"最终结果"}

• 需要人工阅读就采用纯文本格式，需要机器解析就采用JSON格式，需要实时监控就采用stream-json格式。

2.2 成本护栏

点击查看代码

# 限制执行轮数（防止过度分析）
claude -p "审查代码" --max-turns 5
# 设置硬性成本上限（美元）
claude -p "分析日志" --max-budget-usd 0.50
# 双重保险：同时限制轮数与成本
claude -p "分析整个代码库" --max-turns 10 --max-budget-usd 2.00

2.3 安全边界：工具权限

点击查看代码

# 白名单模式：仅允许只读工具（最安全的审查配置）
claude -p "审查代码变更" --allowedTools "Read,Grep,Glob"

# 黑名单模式：禁止特定工具
claude -p "生成文档" --disallowedTools "Bash"

# 细粒度模式：允许特定的命令模式
claude -p "检查 Git 历史" --allowedTools "Read,Grep,Glob,Bash(git log *),Bash(git diff *)"

• 白名单基于“封闭世界假设”：仅允许使用明确列出的工具，其余工具一律拒绝。
• 黑名单基于“开放世界假设”：除明确禁止的工具以外，其余所有工具均可使用。

此外，还有一个更为激进的参数——--dangerously-skip-permissions，用于跳过所有权限检查。

2.4 执行控制：模型、Prompt、结构化输出

1.模型选择

点击查看代码

# 简单格式检查（快速且低成本）
claude -p "检查代码格式" --model claude-haiku-4-5

# 深度安全审查（使用最强模型）
claude -p "安全漏洞分析" --model claude-sonnet-4-6

# 指定备选模型（主模型过载时自动降级）
claude -p "代码审查" --model claude-sonnet-4-6 --fallback-model claude-haiku-4-5

2. System Prompt定制

• 通过定制System Prompt来定义Claude的角色与行为边界。

点击查看代码

# 完全替换System Prompt（这将使Claude忘记其默认的代码助手身份，仅遵循新指令）
claude -p "分析代码" --system-prompt "你是一名专注于OWASP Top 10的应用安全专家。"
# 追加System Prompt（推荐，在保留Claude基础能力的同时，增加特定约束）
claude -p "审查 PR" --append-system-prompt "务必检查敏感信息硬编码。"
# 从文件加载追加Prompt（适用于包含复杂审查规范的大型项目）
claude -p "审查代码" --append-system-prompt-file ./review-guidelines.txt

3.结构化输出

• 强制Claude输出符合特定JSON Schema的数据，从而实现程序化的无缝集成。

点击查看代码

claude -p "提取代码中所有安全问题" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "issues": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "severity": {"type": "string", "enum": ["critical", "high", "medium", "low"]},
            "file": {"type": "string"},
            "line": {"type": "number"},
            "description": {"type": "string"}
          },
          "required": ["severity", "file", "description"]
        }
      }
    },
    "required": ["issues"]
  }'

3 Unix管道：将Claude融入命令行工作流

点击查看代码

# 分析日志文件
cat server.log | claude -p "找出所有500错误并总结根本原因"
# 分析git变更
git diff HEAD~1 | claude -p "总结这次提交的变更，并按Conventional Commits规范格式化"
# 解析API响应
curl -s https://api.example.com/health | claude -p "判断服务是否健康"

点击查看代码

# Claude分析→ jq提取→发送通知
claude -p "检查是否存在安全漏洞" --output-format json | \ jq -r '.result' | \ mail -s "安全
扫描报告" security@company.com
# Grep预过滤→Claude深度分析
grep -r "TODO" src/ | claude -p "将这些待办事项按优先级分类"
# Claude 生成代码 → 直接写入文件
claude -p "生成一个Express健康检查路由" --output-format text > routes/health.js 

4 实战一：GitHub Actions自动代码审查

• Anthropic提供了两种GitHub Actions集成方案：
  一是采用官方Action（anthropics/claude-code-action@v1），其封装程度高、配置简便；
  二是直接调用CLI，其灵活性更强、控制更为精细。

4.1 采用官方Action

• Claude Code内置了便捷的安装命令：在交互模式下执行/install-github-app，即可引导用户完成GitHub App安装、Secret配置及Workflow文件创建的全流程。
• 若选择手动配置，步骤亦不烦琐。首先，进入GitHub仓库，然后单击Settings→Secrets→Actions命令，添加ANTHROPIC_API_KEY，随后创建如下Workflow文件。

点击查看代码

name: Claude PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]
  issue_comment:
    types: [created]

# 针对同一PR的新提交自动取消正在运行的旧任务，以节省资源
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    # 仅在触发PR相关事件或评论中包含"@claude"时运行
    if: |
      github.event_name == 'pull_request' ||
      contains(github.event.comment.body, '@claude')
    permissions:
      contents: read
      pull-requests: write
      issues: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 拉取完整历史，以便进行差异分析

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            请审查此PR的代码变更，重点检查以下内容：
            1. 安全漏洞（如SQL注入、XSS攻击、敏感信息硬编码等）。
            2. 未处理的异常情况及边界条件。
            3. 性能隐患（如N+1查询、内存泄漏风险）。

            请按以下格式输出报告：
            ## 审查报告
            ### Critical（必须修复）
            ### Warning（建议修复）
            ### Suggestion（可选优化）
          claude_args: >-
            --allowedTools "Read,Grep,Glob"
            --max-turns 10
            --model claude-sonnet-4-6

1.两重触发模式

• Agent Mode（代理模式）
• Tag Mode （标签模式）
  这两种模式可在同一个Workflow文件中共存，互不冲突。

2.参数透传机制

• 官方Action v1版本大幅简化了配置结构。所有Claude Code CLI的参数现统一通过claude_args字段传递。

3.并发控制策略

• 通过设置cancel-in-progress:true，可实现高效的并发控制。

4.2 直接调用CLI

点击查看代码

name: Advanced AI Review

on:
  pull_request:
    types: [opened, synchronize]
    paths:
      - 'src/**' # 仅在src目录发生变更时触发

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

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

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

      - name: Get changed files
        id: changed
        run: |
          FILES=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
          echo "files=$(echo "$FILES" | tr '\n' ' ')" >> "$GITHUB_OUTPUT"
          echo "count=$(echo "$FILES" | wc -l)" >> "$GITHUB_OUTPUT"

      - name: Run Claude Review
        id: review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
        run: |
          claude -p "请审查以下PR变更文件：
          ${{ steps.changed.outputs.files }}
          重点检查安全漏洞、逻辑错误及性能问题。
          针对每个问题，请明确指出文件名和行号。" \
            --output-format json \
            --max-turns 10 \
            --max-budget-usd 0.50 \
            --model claude-sonnet-4-6 \
            --allowedTools "Read,Grep,Glob" > review.json

          # 提取审查结果与成本信息
          RESULT=$(jq -r '.result' review.json)
          COST=$(jq -r '.total_cost_usd' review.json)
          IS_ERROR=$(jq -r '.is_error' review.json)

          echo "cost=$COST" >> "$GITHUB_OUTPUT"
          echo "is_error=$IS_ERROR" >> "$GITHUB_OUTPUT"
          {
            echo "result<<EOF"
            echo "$RESULT"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const cost = '${{ steps.review.outputs.cost }}';
            const result = `${{ steps.review.outputs.result }}`;
            await github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Claude Code Review\n\n${result}\n\n---\n*Cost: $${cost} | Automated by Claude Code*`
            });

      - name: Gate on critical issues
        run: |
          RESULT="${{ steps.review.outputs.result }}"
          if echo "$RESULT" | grep -qi "critical"; then
            echo "::error::Critical issues found"
            exit 1
          fi

• 成本透明化（每次审查的具体费用将直接显示在评论中）
• 质量门禁（当检测到Critical级别的严重问题时，Workflow会自动失败并阻塞PR合并）
• 路径过滤（通过paths限定，仅在src/目录发生变更时触发审查）

此外，需要注意CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC环境变量。这是CI/CD流水线中的标准最佳实践，用于一次性禁用自动更新检查、错误上报及遥测数据发送等在自动化场景中非必要的功能。

5 实战二：多阶段CI管道

以下是一个多阶段AI流水线的配置示例。

点击查看代码

name: Multi-Stage AI Pipeline

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  # 阶段1：快速格式检查（使用低成本模型）
  lint-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Format Check
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
        run: |
          npx @anthropic-ai/claude-code -p "检查src/下的代码是否符合项目编码规范" \
            --model claude-haiku-4-5 \
            --max-turns 3 \
            --max-budget-usd 0.05 \
            --allowedTools "Read,Grep,Glob" \
            --output-format text

  # 阶段2：深度安全审查（使用高性能模型）
  security-scan:
    runs-on: ubuntu-latest
    needs: lint-check # 仅在格式检查通过后执行
    steps:
      - uses: actions/checkout@v4

      - name: Security Scan
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
        run: |
          npx @anthropic-ai/claude-code -p "深度安全扫描，重点检查OWASP Top 10" \
            --model claude-sonnet-4-6 \
            --append-system-prompt "你是一名应用安全专家，请仅关注安全漏洞问题。" \
            --max-turns 10 \
            --max-budget-usd 1.00 \
            --allowedTools "Read,Grep,Glob" \
            --output-format json \
            --json-schema '{
              "type": "object",
              "properties": {
                "vulnerabilities": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "severity": {"type": "string"},
                      "description": {"type": "string"},
                      "file": {"type": "string"}
                    },
                    "required": ["severity", "description"]
                  }
                }
              },
              "required": ["vulnerabilities"]
            }' > security-report.json

  # 阶段3：测试覆盖分析
  coverage-check:
    runs-on: ubuntu-latest
    needs: lint-check # 依赖于格式检查，但与安全检查并行
    steps:
      - uses: actions/checkout@v4

      - name: Coverage Analysis
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
        run: |
          npx @anthropic-ai/claude-code -p "分析哪些代码路径缺少测试覆盖" \
            --model claude-sonnet-4-6 \
            --max-turns 8 \
            --max-budget-usd 0.50 \
            --allowedTools "Read,Grep,Glob" \
            --output-format text

• 模型分级
• 预算分级
• 并行执行