用 Claude Code 自动化开发工作流的实战指南

Claude Code 的工作流自动化，不是让代理在无人看管时直接合并代码。更可靠的做法是把重复、可验证的部分交给它：整理 Issue、准备小范围修改、审查 PR、生成维护报告，并在需要产品判断、发布判断或数据变更时停下来等人确认。

本文给出可以复制运行的例子，使用 gh、git、node、npm 和 claude 命令。这里的核心是先搭好“代理脚手架”：输入是什么、允许做什么、日志放哪里、失败如何重试、怎样回滚、哪些地方必须人工批准。

先划清自动化边界

阶段	交给 Claude Code	人工保留
分诊	总结 Issue、差异和失败日志	优先级和产品判断
修改	小修复、测试、文档更新	范围变更和发布判断
审查	找出 bug、安全风险和缺失测试	选择采纳哪些建议
运维	定期检查、过期 TODO、依赖提醒	合并、删除、发布、计费影响

flowchart LR
  A["Issue / PR"] --> B["小提示词"]
  B --> C["Claude Code"]
  C --> D["差异和日志"]
  D --> E["测试"]
  E --> F["人工审批"]
  F --> G["PR / 发布"]

如果要把它放进完整流水线，可以继续阅读 Claude Code CI/CD 构建指南 和 Claude Code Hooks 指南。

用例1：从 Issue 创建安全的工作分支

这个脚本会读取 GitHub Issue，创建或复用固定分支，让 Claude Code 做最小修改，运行测试，然后把提交动作留给你。

保存为 scripts/claude-issue-work.sh。

#!/usr/bin/env bash
set -euo pipefail

ISSUE_NUMBER="${1:-}"
if [ -z "$ISSUE_NUMBER" ]; then
  echo "Usage: ./scripts/claude-issue-work.sh <issue-number>"
  exit 1
fi

for command_name in git gh claude npm; do
  if ! command -v "$command_name" >/dev/null 2>&1; then
    echo "Missing command: $command_name"
    exit 1
  fi
done

: "${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY before running this script}"

mkdir -p .claude-logs
ISSUE_FILE=".claude-logs/issue-${ISSUE_NUMBER}.md"
LOG_FILE=".claude-logs/issue-${ISSUE_NUMBER}-$(date +%Y%m%d-%H%M%S).log"
BRANCH="claude/issue-${ISSUE_NUMBER}"

gh issue view "$ISSUE_NUMBER" --json title,body,labels --jq '
  "# " + .title + "\n\n" + (.body // "") + "\n\nLabels: " + ([.labels[].name] | join(", "))
' > "$ISSUE_FILE"

if git show-ref --verify --quiet "refs/heads/$BRANCH"; then
  git switch "$BRANCH"
else
  git switch -c "$BRANCH"
fi

PROMPT=$(cat <<PROMPT
你是这个仓库的开发助手。
请阅读下面的 Issue，并做最小且有用的修改。

限制:
- 先检查相关文件，再开始编辑。
- 优先沿用现有架构、命名和测试风格。
- 需求不清楚时，不要凭空设计大方案，留下 TODO 或问题。
- 不要触碰密钥、环境文件或无关文章。
- 修改后让仓库保持可以运行 npm test 的状态。
- 不要 commit、push、创建 PR 或 merge。

Issue:
$(cat "$ISSUE_FILE")
PROMPT
)

claude -p "$PROMPT" \
  --max-turns 8 \
  --permission-mode acceptEdits \
  --output-format text 2>&1 | tee "$LOG_FILE"

npm test 2>&1 | tee -a "$LOG_FILE"
git diff --stat | tee -a "$LOG_FILE"

echo "Review the diff, then commit manually if it is correct."
echo "Log: $LOG_FILE"

这个例子把常见事故提前拦住了。没有 ANTHROPIC_API_KEY 会立即失败；分支名固定，所以重复运行不会生成一堆分支；日志保存在 .claude-logs，方便第二天追查当时给了什么指令、测试在哪里失败。

用例2：把 PR 审查放进 GitHub Actions

官方 Claude Code GitHub Action 可以在 PR 事件中运行。下面的工作流只做审查，不允许改代码、push 或 merge。

保存为 .github/workflows/claude-review.yml。

name: Claude Review Gate

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

permissions:
  contents: read
  pull-requests: write
  issues: write

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

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

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            请审查这个 Pull Request。
            重点看 bug、安全、测试不足、向后兼容性和运维日志。
            每条问题标记 high / medium / low，并给出具体修复建议。
            不要编辑代码、push 或 merge。
          claude_args: |
            --max-turns 6
            --permission-mode plan

权限要尽量窄。只做 PR 审查时，核心通常是 contents: read 和 pull-requests: write。如果还要评论 Issue，再加 issues: write。

复制旧示例前，先看 Claude Code CLI 官方参考、Claude Code GitHub Actions 官方文档 和 GitHub Actions 工作流语法。旧的 @beta 或 direct_prompt 示例应更新为现在的 @v1 和 prompt。

用例3：用 Node.js 生成定期维护报告

定期维护不一定要改文件。每天或每周生成一份报告，列出失败测试、过大差异、过期 TODO、缺少日志和回滚风险，已经能减少很多返工。

保存为 scripts/claude-maintenance.mjs。

#!/usr/bin/env node
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
import { join } from "node:path";

const logDir = ".claude-logs";
const lockFile = join(logDir, "maintenance.lock");
const stamp = new Date().toISOString().replace(/[:.]/g, "-");
const logFile = join(logDir, `maintenance-${stamp}.log`);

function fail(message) {
  console.error(message);
  process.exit(1);
}

function run(command, args, options = {}) {
  const result = spawnSync(command, args, {
    encoding: "utf8",
    shell: process.platform === "win32",
    ...options,
  });

  const output = `${result.stdout || ""}${result.stderr || ""}`;
  if (result.status !== 0) {
    writeFileSync(logFile, output);
    fail(`Command failed: ${command} ${args.join(" ")}. See ${logFile}`);
  }
  return output;
}

if (!process.env.ANTHROPIC_API_KEY) {
  fail("Set ANTHROPIC_API_KEY before running this script.");
}

mkdirSync(logDir, { recursive: true });
if (existsSync(lockFile)) {
  fail(`Another maintenance run is active: ${lockFile}`);
}

writeFileSync(lockFile, String(process.pid));

try {
  const status = run("git", ["status", "--short"]);
  const tests = run("npm", ["test", "--", "--runInBand"]);
  const prompt = [
    "你是这个仓库的维护审查员。",
    "请阅读 git status 和测试输出，总结今天需要关注的风险。",
    "不要编辑、删除、commit 或 push 任何内容。",
    "按 credentials / idempotency / retry / rollback / logs / human approval 分组。",
    "",
    "git status:",
    status || "(clean)",
    "",
    "test output:",
    tests.slice(-12000),
  ].join("\n");

  const review = run("claude", [
    "-p",
    prompt,
    "--max-turns",
    "5",
    "--permission-mode",
    "plan",
    "--output-format",
    "text",
  ]);

  writeFileSync(logFile, review);
  console.log(`Maintenance report written to ${logFile}`);
} finally {
  rmSync(lockFile, { force: true });
}

如果你的测试工具不是 Jest，可以把 npm test -- --runInBand 改成项目自己的测试命令。脚本只把最后 12000 个字符传给 Claude Code，是为了避免提示词过长。日志太长时，真正有用的失败行反而会被淹没。

用例4：用 cron 或任务计划程序定期运行

Linux 和 macOS 可以用 cron，Windows 可以用任务计划程序。GitHub Actions 的 schedule 也能做定时任务，但如果检查需要本地数据库、VPN 或内部凭据，本机执行通常更现实。

# 工作日 08:15 运行
15 8 * * 1-5 cd /path/to/repo && /usr/bin/node scripts/claude-maintenance.mjs >> .claude-logs/cron.log 2>&1

# 注册每天运行的 Windows 任务
schtasks /Create /TN "ClaudeMaintenance" /SC DAILY /ST 08:15 /F /TR "powershell -NoProfile -ExecutionPolicy Bypass -Command \"cd C:\path\to\repo; node scripts\claude-maintenance.mjs\""

定时任务必须考虑幂等性。幂等性是指同一任务重复执行，也不会制造重复 PR、重复评论或重复分支。锁文件、固定分支名、已有 PR 检查和日志保存都很重要。

用例5：把人工审批写进提示词

提示词短并不一定安全。好的工作流提示词应该写明允许什么、禁止什么、哪些决定必须交给人。

claude -p "
目标:
  处理 PR #123 的审查意见。

允许:
  - 编辑相关实现文件和测试文件。
  - 运行 npm test。
  - 总结失败日志。

禁止:
  - git push
  - gh pr merge
  - 显示 .env 或密钥
  - 无关重构

需要人工审批:
  - 改变 API 响应兼容性
  - 增加数据库迁移
  - 删除已有测试

最后报告:
  - 修改的文件
  - 运行的测试
  - 剩余风险
  - 回滚步骤
" --max-turns 6 --permission-mode acceptEdits

想整理审查格式，可以参考 Claude Code 审查清单 和 验证记录工作流。

必须提前设计的失败模式

失败模式	会发生什么	实用对策
提示词太长	约束被埋没，执行变慢	只传相关文件和日志末尾
凭据缺失	CI 因 ANTHROPIC_API_KEY 或 GH_TOKEN 失败	开头检查环境变量
没有幂等性	出现重复 PR、评论或分支	固定名称、锁和状态检查
没有日志	无法知道代理做过什么	保存 .claude-logs 或 GitHub artifacts
重试粗糙	临时失败变成重复写入	只重试读取，写入前重新检查状态
无法回滚	一个大提交很难 revert	小 PR，并要求回滚说明
没有审批点	代理替你做产品或发布决定	兼容性、数据、计费、删除和合并必须人工批准

相关主题可以继续看 Claude Code 安全审计、Claude Code 测试策略 和 Git 工作流自动化。

收益导线和 AdSense 注意点

这类文章的自然转化不是夸张承诺，而是实际帮助。个人开发者可以先使用 Claude Code 免费速查表。团队如果需要按仓库定制提示词、审查门禁、审批策略和导入培训，可以查看 Claude Code 培训与咨询。想快速拿到可复用设置材料，也可以购买 Claude Code 设置指南。

广告和 CTA 不要插在命令步骤中间。对 AdSense 质量来说，包含可运行代码、真实失败模式、官方链接、内部链接和实际验证结果，比泛泛的信息汇总更安全。

总结

Claude Code 工作流自动化可靠的关键，是先设计停止点。先做 Issue 分诊和 PR 审查，再做小修改，最后再加定期维护和带人工审批的 CI 门禁。

Masa 实际试用后发现，收益最大的不是完全自动创建 PR，而是可重复的 Issue 日志和固定的 PR 审查提示词。ANTHROPIC_API_KEY 缺失、测试输出过长、同一分支重复运行都各造成过一次失败，但加入环境变量检查、只传日志末尾、固定分支名后，下一次排查明显轻松了。