Claude Code工程自动化实战：从代码审查到CI批处理的工作流搭建

这次我们来看一个在生产环境里跑出过实际效果的工作流：Shopify 团队公开站台的 Claude Code 工程自动化方案。它不只是“用 AI 帮忙写代码”，而是把 Claude Code 当成仓库里的正式工程角色——接收 PR 自动做代码审查、补测试、写发布说明、维护文档，并且整个过程都留下可审计的记录。

先给结论：这套工作流的价值不在某个单一技巧，而在它把 Claude Code 的五个能力拼在了一起——CLAUDE.md 的团队记忆、Slash Commands 的固定动作、Hooks 的事件触发、Subagents 的角色分工、headless 模式的 CI 批处理。这五块拼起来才是“工作流”，而不是“一次聊天”。

如果你已经装过 Claude Code，可以直接跳到第 5 节看工作流文件怎么写；如果还没装，这篇会从环境准备、安装部署、功能测试讲到你能在自己的仓库里复制一个最小可用版本。重点覆盖：headless 模式、CI 中的 PR 审查、批量任务和接口调用。全文不吹概念，直接给能跑的步骤和排查清单。

1. 核心能力速览

在开始复刻之前，先把这套工作流的技术底数摆出来。以下信息一部分来自 Shopify 团队的公开分享和 Claude Code 官方文档，一部分来自社区通用实践；凡是无法精确到数字的，我统一按“以本机、以当前版本实测为准”处理。

为什么说这套方案“强”？从公开信息看，Shopify 的关键动作不是写了一条很长的 prompt，而是把 Agent 和 Git 事件绑定在一起。分支规范、PR 模板、测试命令、发布清单全部变成了机器可理解的结构化信息。Agent 每次被触发时，都能拿到“当前改动是什么、仓库规范是什么、测试怎么跑、输出什么格式”，所以结果稳定，而不是一次灵光乍现。

2. 适用场景与使用边界

2.1 适合做什么

• 代码审查：自动拉取 diff，按仓库规范输出问题清单，带文件、行号和修复建议。
• 测试补全：新功能合入前，让 Agent 参考已有测试风格补单测，再由人确认。
• 发布说明：基于 commit 和 PR 标题生成 Release Notes，格式统一。
• 技术方案预审：把设计文档丢给 Agent，先过一遍边界条件、数据流和异常处理。
• Issue 到 PR 草稿：从 Issue 描述生成实现草稿，减轻重复工作。
• 文档同步：接口变更后，自动识别需要更新的文档位置。

2.2 不适合做什么

• 替代人工验收：高风险上线决策、合规签字、产品验收必须有人。
• 自动合并代码：即使审查结果全绿，也不建议让 Agent 直接 merge，保留人工 gate。
• 处理敏感数据：包含生产密钥、客户个人信息、未脱敏内部资料的仓库，不建议直接喂给第三方 API。
• 一步到位的重构：大规模重构需要人先划定边界，Agent 更适合做局部、可回滚的改动。

2.3 合规与安全边界

• Agent 默认拥有执行工具的能力，第一原则是权限最小化：默认只读，按需开放编辑和命令执行。
• 公司仓库如果涉及商业机密，接入外部 API 前需要确认数据出境和合规条款；不确定时优先走本地模型或私有化网关。
• 生成的代码、文档、文案仍然属于工具输出，商用前必须人工复核版权和开源许可证。
• 不要让 Agent 绕过安全校验，例如跳过 lint、关闭测试、注释掉鉴权逻辑。工作流用来提升效率，不是用来制造更快的返工。

3. 环境准备与前置条件

3.1 硬件与系统

Claude Code 本身是 Node 命令行工具，对显卡没有硬性要求。走 Anthropic API 时，本机只需要能跑 Node 和 Git；接本地模型时才开始关心显存。系统方面，macOS、Linux、Windows 都支持，但大量 CI 示例和团队实践基于 Linux/macOS，Windows 下如果遇到终端工具执行差异，建议优先用 WSL 保持一致。

3.2 软件依赖

3.3 模型访问方式

有两条路线，先想清楚再装：

• 官方路线：登录 Claude 账号，或配置 ANTHROPIC_API_KEY。个人开发者最省事，团队场景可以用账号管理能力做权限控制。
• 兼容路线：通过网关接入 DeepSeek、Qwen、GLM 等第三方接口，或者接本地模型（LM Studio、Ollama 提供 OpenAI 兼容端口）。这条路对国内同学友好，但稳定性和合规由服务提供方决定，公司项目先确认是否允许。

如果只做本地技术验证，先用 Anthropic API 跑通最省时间，后面再切换网关。

4. 安装部署与启动方式

4.1 安装 Claude Code

推荐用 npm 全局安装，各平台通用：

bash复制npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

macOS / Linux 也可以用官方原生安装脚本，具体地址以官方文档为准：

bash复制# 常见安装方式之一，脚本地址如变化以官方文档为准
curl -fsSL https://claude.ai/install.sh | bash

安装完成后，在仓库目录里直接输入 claude 就会进入交互式终端。第一次启动时会要求登录或配置 API Key。

4.2 登录与认证

交互式登录最简单：

bash复制claude
# 在会话里执行 /login 完成账号授权
# 执行 /status 查看当前模型、账号和模式

API Key 方式适合 CI 和服务器：

bash复制export ANTHROPIC_API_KEY="sk-ant-xxxxxxxx"
claude -p "请简要输出当前仓库结构"

注意：API Key 属于敏感信息，不要写进仓库、评论或分享截图。CI 里统一放到 Secrets 中。

4.3 三种启动方式

第一，交互式终端。适合日常开发和调试 prompt，能看到 Claude Code 的思考、工具调用和最终输出。

第二，headless 模式。一条命令执行完直接退出，输出文本或 JSON，适合脚本和 CI：

bash复制claude -p "请审查当前分支的改动，指出潜在 bug 和样式问题，用列表输出" \
  --output-format json > review.json

第三，VS Code 插件与桌面版。在 VS Code 扩展市场安装 Claude Code 扩展后，可以直接在侧边栏对话；桌面版从官方下载入口获取。两种方式本质还是调同一个 Claude Code 内核，适合不想切终端的场景。

4.4 让 Agent 执行终端命令

Claude Code 交互模式下，Agent 可以请求执行终端命令，默认需要你确认。headless 模式下用权限参数控制：

bash复制claude -p "运行 npm test，并根据失败信息修复代码" \
  --allowedTools "Read,Edit,Bash" \
  --disallowedTools "WebFetch"

这里的工具名要和 claude --help 里的权限写法保持一致。先用小范围测试，确认 Agent 不会乱删文件、不会改不该改的目录，再放大权限。

5. 搭建 Shopify 风格工作流

下面这套结构是官方文档和社区里的标准玩法，也是把“一次对话”升级成“团队资产”的关键。核心思想：把工作流写进仓库，全组共用。

5.1 目录规划与 CLAUDE.md

在仓库根目录维护一个 CLAUDE.md，Claude Code 每次会话开始时自动读取，相当于团队记忆。内容不要写长篇大论，只写 Agent 必须知道的事：

markdown复制# 项目说明
本仓库是一个订单管理服务，使用 Node 20 + TypeScript + PostgreSQL。

## 开发环境
- 安装依赖：pnpm install
- 运行测试：pnpm test
- 代码检查：pnpm lint

## 工程规范
- 提交信息使用 Conventional Commits
- PR 必须通过自动化检查才能合并
- 新功能必须补单元测试

## 代码审查要点
- 先看数据流，再看异常处理
- 重点检查：未处理错误、SQL N+1、内存泄漏、敏感信息泄露
- 输出格式：按严重程度排序，每项包含文件、行号、原因、建议

有了这个文件，Agent 在写代码、审查、补测试时都能对齐仓库约定。项目变大后，还可以在子目录放 CLAUDE.md 拆分成模块级规则。

5.2 用 Slash Commands 固化审查动作

自定义命令放在 .claude/commands/ 目录，一个 Markdown 文件就是一个斜杠命令。比如建立 .claude/commands/review.md：

markdown复制---
description: 对当前分支做一轮代码审查
argument-hint: 可选：关注模块名
allowed-tools: Read,Grep,Glob,Bash(git diff:*)
---

请对当前分支相对主分支的改动做代码审查：
1. 运行 git diff main...HEAD 获取改动。
2. 按 CLAUDE.md 里的“代码审查要点”逐条检查。
3. 输出：按严重程度排序的问题列表，每项给出文件、行号、原因和建议修复。

使用时在会话里输入 /review 或者 /review 支付模块。整个团队共用同一个命令，审查标准就统一了。还可以继续加 /test、/release-notes 等命令。

5.3 用 Subagents 做角色分工

Subagents 相当于给 Agent 拆出专职角色，各有独立的 system prompt 和工具权限。放在 .claude/agents/ 目录。

例如 .claude/agents/test-writer.md：

markdown复制---
name: test-writer
description: 根据代码实现编写单元测试
tools: Read,Edit,Write,Bash(pnpm test:*)
---

你是一名资深测试工程师。编写测试时：
1. 先读被测代码，理解输入输出。
2. 参考仓库现有测试风格。
3. 补齐边界条件和异常路径。
4. 写完运行 pnpm test 验证，失败则修复到通过。

主会话里提到 @test-writer 即可调用。角色隔离的好处是：审查 Agent 不会顺手改代码，测试 Agent 不会跑去重构业务逻辑。

5.4 用 Hooks 实现事件触发

Hooks 让工作流从“人想起来再跑”变成“事件到了自动跑”。配置在 settings.json，可以是用户级 ~/.claude/settings.json，也可以是项目级 .claude/settings.json。

下面示例是拦截 Bash 工具调用前执行一次检查：

json复制{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/check_bash.py"
          }
        ]
      }
    ]
  }
}

常用事件还包括 PostToolUse、Stop、SessionStart、SessionEnd。实际项目中，Stop 事件适合做“会话结束后的自动整理”，比如自动生成变更摘要；SessionStart 适合加载团队约定。注意 hooks 脚本要短、要幂等，失败不能把主任务卡死。

5.5 接入 GitHub Actions 实现自动审查

工作流最终要落在 CI 里才有规模效应。下面是一份 GitHub Actions 模板，在 PR 事件上调用 headless 模式生成审查意见并回帖。注意这只是模板，流程、权限、密钥管理都要按自己团队的安全规范调整。

yaml复制name: claude-code-review

on:
  pull_request:
    types: [opened, synchronize]

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: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "请审查本次 PR 的改动，输出问题清单" \
            --output-format text > review.txt

      - name: Post review comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          REVIEW_FILE=$(ls review.txt)
          gh pr comment "${{ github.event.pull_request.number }}" --body-file "$REVIEW_FILE"

这份配置的要点：API Key 只放在 GitHub Secrets；权限只给了 reads 和 pull-requests write；审查结果由人看，不自动 merge。换成 GitLab CI 也是同样的思路，把事件改成 merge request，命令不改。

6. 接口 API 与批量任务

6.1 Headless 模式当作接口用

claude -p 配合 --output-format json 可以拿到结构化输出，适合做内部服务、定时任务和批量审查：

bash复制claude -p "请审查 src/payment 目录的改动，输出 JSON 格式问题列表" \
  --output-format json > payment-review.json

JSON 输出里会包含会话 ID、结果类型、耗时等信息。日志落在 ~/.claude/logs，可以按会话 ID 回溯一次调用做了什么。

6.2 Claude Agent SDK 编程调用

如果业务系统需要把审查能力嵌入自有平台，用官方 SDK 更稳。安装：

bash复制npm install @anthropic-ai/claude-agent-sdk

一个最小调用示例：

javascript复制const { query } = require('@anthropic-ai/claude-agent-sdk');

async function runReview() {
  const result = await query({
    prompt: '请审查 src/ 下的改动，输出问题清单，按严重程度排序',
    options: {
      cwd: process.cwd(),
      model: 'sonnet',
      permissionMode: 'acceptEdits',
      allowedTools: ['Read', 'Grep', 'Bash']
    }
  });

  for await (const message of result) {
    if (message.type === 'result') {
      console.log(message.result);
    }
  }
}

runReview();

SDK 适合做任务队列：把待审查的 PR 列表塞进队列，逐个调用，结果写入数据库，再交给后续的人工确认环节。具体 API 字段以当前 SDK 版本文档为准，但整体模式是这样。

6.3 批量任务与失败重试

批量审查多个 PR 时，直接用 shell 循环最容易理解：

bash复制for pr in 101 102 103; do
  claude -p "请审查 PR #$pr 的改动，输出 JSON 结果" \
    --output-format json > "review-$pr.json" && echo "PR $pr done"
  # 控制节奏，避免触发限流
  sleep 10
done

批量任务三个原则：

• 每个任务独立输出文件，不能覆盖。
• 加失败重试和退避，429 / 超时不属于致命错误。
• 记录开始时间和耗时，方便算成本和定位慢任务。

6.4 本地模型接入与供应商切换

不想走官方 API 时，社区常用做法是用兼容网关。本地场景中，LM Studio 和 Ollama 会把模型暴露成 OpenAI 兼容的本地端口，然后在启动命令前设置基础地址：

bash复制export ANTHROPIC_BASE_URL="http://localhost:1234/v1"
export ANTHROPIC_AUTH_TOKEN="local-key-placeholder"
claude -p "1 + 1 等于多少？"

注意：这是通用接入思路，具体变量名和兼容程度以网关文档为准。不同网关对 Anthropic Messages API 的兼容度不一样，本地小模型的输出质量和稳定性也明显弱于大模型，适合做敏感数据本地化处理，不适合直接当生产审查主力。

切换多供应商时，社区常用开源工具 CC Switch 这类配置工具，把 Anthropic、Bedrock、Vertex、DeepSeek、Qwen、GLM 等供应商切换封装成图形界面，本质是改写 Claude Code 的配置文件。好处是省去手工改 JSON，坏处是第三方接口的数据合规、可用性需要自己评估。公司项目接入前先确认安全边界。

7. 资源占用与性能观察

7.1 云端 API 与本机负载

走 Anthropic API 时，Claude Code 在本机主要消耗 CPU、内存和网络 IO，显存基本不用管。观察本机负载用：

bash复制top
# 或
htop

如果某个会话运行很久，可能不是模型慢，而是 Agent 反复读文件、跑测试、执行了大量工具调用。这类情况用 --debug 查看调用过程，能明显看出瓶颈。

7.2 本地模型的显存观察

接 LM Studio / Ollama 这类本地模型时，显存取决于模型大小、上下文长度和量化方式。同一个模型，Q4 量化和 FP16 的显存差一倍以上；上下文越长，KV Cache 占用越高。具体够不够用，用 GPU 监控工具看：

bash复制nvidia-smi -l 2

判断标准不是“能不能加载”，而是“推理时会不会 OOM”。起步阶段先选小模型、短上下文，跑通流程后再放大。不要只看加载成功，要看连续多次调用后显存是否稳定。

7.3 Context 与速度/成本

Claude Code 每次读取文件、命令输出都会累积到上下文里。上下文越长，响应越慢、费用越高，还容易出现输出截断或质量下降。控制手段：

• 让 Agent 先用 Grep / Glob 定位，再精准 Read，避免全文件扫描。
• 会话过长时用 /compact 压缩上下文，或直接 /clear 重开。
• Headless 批量任务尽量一次只处理一个小任务，别把所有文件塞给一个 prompt。

8. 常见问题与排查方法

其中最容易踩的是权限问题。很多人一上来就给 Agent --allowedTools "*"，结果它高高兴兴地帮你重构了不想动的模块。正确顺序是：先用只读模式跑审查，确认输出了解工具的边界，再逐步放开编辑权限。

9. 最佳实践与使用建议

• 把 .claude/ 目录和 CLAUDE.md 纳入 Git，全组共享同一套工作流；但 settings.json 里的本地密钥绝对不要提交。
• 第一次验证从一个小仓库或一个小 PR 开始，不要直接全量接入生产仓库。
• 所有 Agent 操作保留日志。claude --debug 或 ~/.claude/logs 里的会话记录，是出问题后还原现场的唯一线索。
• 权限最小化是硬原则。默认只读，逐个开放需要的工具；对生产配置、密钥、客户数据目录直接禁用编辑。
• 敏感数据处理走本地模型或私有化网关。客户数据和个人信息不应该以明文形式流到第三方服务。
• 一切生成内容必须人工复核。Agent 写代码，人负责把关；商用和发布前检查版权、许可证和合规。
• 批量任务加日志和失败重试。成本方向也要关注，统计每次任务的 token 消耗。
• 工作流尽量事件驱动。能用 Hooks 和 CI 触发的，就不要靠人记得去跑。

这套模式做到后面，团队最明显的收益不是“代码写得快”，而是“审查标准终于统一了”、每个 PR 都有人（或 Agent）看过、每次发布都有结构化的说明。至于质量问题，二维评价总比没有评价强，关键始终是人做最终决策。

10. 总结与下一步

最值得试的功能是 /review 自定义命令：在工作流里加上它，等于给每个 PR 配了一个自动审查员。最先验证的场景应该是 headless 模式，确认 claude -p --output-format json 能在你的仓库里输出可靠结果，再考虑接到 CI。

最容易踩的坑有三个：权限开太大导致 Agent 乱改代码、上下文太长导致输出漂移、CI 里把 Agent 当成普通命令行脚本却忽视了密钥和路径问题。

后续可以继续扩展的方向：接入 MCP Server 让 Agent 直接读 Issue、查知识库、关 PR；接入 Claude Agent SDK 做成内部审查服务；把模型供应商切换到本地大模型实现数据不出内网。建议先用个人仓库跑三天，把审查命令的命中率调到满意，再放进团队流程。工作流不是越复杂越好，能稳定触发、能审计、能救回现场，才是第一位。