直接以正文开始。先想清楚一件事claude-code-action不是一个“把 Claude Code 跑在云端”的简单封装它解决的是开发工作流自动化中最后一个没人愿意干的环节——让 AI 真正进入 CI/CD 管线替人读代码、改代码、提 PR、补文档而不是停留在聊天框里。我第一次接触这个项目是因为团队的 PR 审查流程实在太折磨人了。早上打开仓库几十个 PR 等着看Lint 报错、类型问题、注释缺失这些一眼能看出的问题硬是要占用 reviewer 半小时。后来我把claude-code-action接进 GitHub Actions让 Claude Code 在每次 Pull Request 打开时自动跑一遍检查把问题直接评论在 PR 里有些简单问题甚至直接生成修复提交。折腾了两周reviewer 的工作量降了六成。这篇文章就把我这个过程的完整踩坑记录整理出来包括基础配置、关键参数、真实场景的 workflow 写法以及我踩过的认证、并发、成本控制这些坑。如果你正在做类似的事情可以直接抄作业。1. 先搞清楚 claude-code-action 到底解决什么问题1.1 从 Claude Code 说起在聊 Action 之前得先了解 Claude Code 本身。Claude Code 是 Anthropic 出品的终端 AI 编程助手它不像 ChatGPT 那样在网页里和你对话而是直接跑在你的命令行里能读写项目文件、执行命令、运行测试、提交代码。你给它一个任务比如“修复这个模块里的内存泄漏”它会自己去翻代码、定位问题、改代码、跑测试最后把改动展示给你确认。关键点在于Claude Code 天然是为“干活”设计的不是为“聊天”设计的。它有一套完整的工具调用体系可以操作文件系统、执行 shell 命令、调用 git 操作。这意味着它非常适合被集成进自动化流程——只要给它一个环境、一个任务、一个允许执行的操作边界它就能自主完成一整套代码工作。1.2 Action 到底替我们省了哪些事claude-code-action就是把 Claude Code 包装成 GitHub Actions 的一个标准组件。它在 GitHub 的 runner 上初始化一个完整的环境安装 Claude Code用你提供的 API Key 完成认证然后按你配置的 prompt 执行任务。这么说可能有点抽象我直接说几个实际能办到的场景自动代码审查每次 PR 打开Action 自动 checkout 代码让 Claude Code 审查变更把发现的问题以评论形式发到 PR 里。自动修复 lint 错误前端项目最常见的场景。运行 ESLint 发现几个自动修复不了的错误交给 Claude Code 分析并修改然后推送修复 commit。自动生成 PR 描述根据 diff 内容自动生成结构化 PR 描述包含改动概述、影响范围、测试建议。自动重构模块比如“把 utils 目录里所有 any 类型替换成具体类型”这种批量任务丢给 Action 完成后直接提交 PR。文档自动同步接口变动后自动更新对应的 README 或 API 文档。这些事以前要么靠人肉要么靠写死规则的脚本。规则写少了不管用写多了维护成本爆炸。而 Claude Code 的优势是能“理解”语义面对没有固定模式的问题也能处理。2. 核心原理与配置拆解2.1 workflow 基础配置示例先看一个最小可用的配置。创建一个.github/workflows/claude-review.yml文件内容如下name: Claude Code Review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest permissions: contents: write pull-requests: write issues: write steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: anthropics/claude-code-actionv1 with: claude-code-version: latest github-token: ${{ secrets.GITHUB_TOKEN }} max-failures: 0 prompt: | 请审查这个 PR 的所有代码变更。 重点关注 1. 潜在的 bug 和逻辑错误 2. 类型安全问题 3. 业务逻辑一致性问题 4. 明显需要改进的地方 请以评论形式将发现的问题发布到 PR 上 评论使用中文按严重程度排序每个问题注明文件和行号。这个配置里核心就三件事加载代码、启动 Action、让它干活。claude-code-version指定 Claude Code 版本github-token让 Action 有权限发布评论prompt是任务指令。2.2 关键参数逐项拆解我实际使用中验证过比较重要的参数有这么几个claude-code-version指定 Claude Code CLI 的版本。默认是latest但生产环境我不建议追新。Claude Code 迭代很快有时候新版会调整工具调用格式可能导致已有的 prompt 表现不稳定。我目前固定在某个经过验证的版本上比如1.0.24。等新版本发布一周、社区反馈稳定后再升级。github-token这个参数的作用是让 Action 能在 GitHub 上留下痕迹——发布评论、创建 commit、开 PR。它填secrets.GITHUB_TOKEN就行这是 GitHub 自动生成的临时凭证。注意使用这个 token 创建的 commit 会被标记为github-actions[bot]的提交而非你的个人账号。如果想以个人身份提交得用个人 access tokenPAT创建 secret 再传进去比如secrets.MY_PAT。max-failuresClaude Code 执行过程中如果出错最多容忍几次。默认是 0意思是第一次出错就停止。我建议保持默认因为一次执行失败往往意味着 prompt 或环境有问题连续重试只会浪费 token。model指定要使用的模型比如claude-sonnet-4-5或claude-opus-4-1。选型逻辑很简单普通的 lint 修复、代码审查用 sonnet 就够性价比高碰到复杂逻辑分析、跨模块重构我会上 opus。你可以按任务类型拆分成不同的 workflow分别指定模型。system-prompt给 Claude Code 设定身份和行为边界。比如“你是资深前端工程师你审查代码时重点关注性能和可访问性”这样能显著提升输出质量。这个参数在实践中非常有用几乎每个稳定运行的 workflow 都配了。run-command默认情况下Action 会执行claude -p --output-format stream-json来跑 prompt。你可以覆盖这个命令传入claude -p ...形式的自定义指令。适合需要添加额外参数比如--allowedTools白名单的场景。2.3 为什么用“单次执行”而不是“长时间对话”用过 Claude Code 的同学可能会问为什么不在 Action 里启动一个长期的交互式会话让它不断执行多轮任务这个问题的答案和 GitHub Actions 的运行机制有关。一个 runner 实例有超时时间通常是 6 小时而且每次执行逻辑越复杂越难排查问题。claude-code-action走的是“单次执行”模式每次 Action 运行启动一个干净的 Claude Code 会话执行完 prompt 就退出结果通过文件输出或 GitHub API 反馈回来。这个设计的优势是可重复性和可调试性。一次运行就是一个黑盒跑完看日志就能知道发生了什么。如果任务需要多轮处理应该在 workflow 的层面编排比如 job A 跑完代码修复触发 job B 跑测试而不是寄希望于单个 Claude Code 会话里执行几十个步骤。3. 实操从零搭建一个自动代码审查流水线3.1 搭建前的准备第一步准备 API Key。登录 Anthropic 控制台创建一个 API Key。注意这个 Key 的文本只会完整显示一次创建后赶紧复制保存。把它添加到仓库的 Settings - Secrets and variables - Actions 里命名成ANTHROPIC_API_KEY。顺带说明一下计费。Claude Code 按 token 计费日常代码审查每次大约消耗 1 万到 3 万 token具体取决于代码量和模型。用 sonnet 级别模型的话一次完整的 PR 审查成本大概是几美分。但如果每个 PR 都跑一个月累积下来也是笔不小的数字。我的经验是在团队项目里只对特定 label 的 PR 自动审查或者只在 draft 转 ready 的时候触发一次。第二步确认仓库权限设置。在 GitHub 仓库的 Settings - Actions - General - Workflow permissions 里确保选择了Read and write permissions否则 Action 没有权限推送 commit 和创建评论。第三步建立基础目录结构。我习惯在 repo 根目录放一个.claude文件夹里面放settings.json和commands.md。settings.json可以配置环境变量commands.md用来定义自定义指令。比如/pod-review 你是资深 DevOps 工程师。请审查这个 PR 中所有与 Kubernetes 部署相关的文件 重点关注镜像标签是否正确、资源限制是否合理、健康检查配置是否完整。 如果发现问题在 PR 评论中逐条列出并说明修复方案。这样一来workflow 里的 prompt 就不用写大段内容直接引用自定义指令干净很多。3.2 完整配置一个审查工作流下面是我目前生产环境中在用的一个比较完善的配置加了开关、模型选择和提交反馈机制name: claude-code-review on: pull_request: types: [opened, synchronize, reopened] branches: [main, develop] jobs: claude-review: if: contains(github.event.pull_request.labels.*.name, ai-review) runs-on: ubuntu-latest timeout-minutes: 30 permissions: contents: write pull-requests: write issues: write steps: - name: Checkout code uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run Claude Code Review uses: anthropics/claude-code-actionv1 env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} with: claude-code-version: 1.0.24 github-token: ${{ secrets.GITHUB_TOKEN }} model: claude-sonnet-4-5 max-failures: 0 prompt: | 请审查这个 PR 的代码变更并重点关注以下方面 1. 逻辑错误和潜在的运行时异常 2. 类型安全问题尤其是 any 的滥用 3. 数据库操作是否有性能隐患N1 查询等 4. 错误处理是否完备是否存在吞异常的情况 5. 初级的代码问题比如未使用的变量、死代码、硬编码 审查结果请以评论形式发布到 PR 上。要求 - 每条评论必须包含具体文件和行号 - 按严重程度从高到低排序 - 每个问题附带一句简单的修复建议 - 如果代码没有问题请回复一句话说明一切正常 - 使用中文回复这里有两个设计要点。一是加了if条件限制。只有带有ai-reviewlabel 的 PR 才会触发审查。为什么不所有 PR 都跑因为成本还是次要的主要原因是噪声。不是每个 PR 都值得 AI 看一遍比如文档改动、配置文件调整审查意义不大。控制触发范围接口的评论质量会高很多。二是用了timeout-minutes: 30。Claude Code 处理一个中等规模的 PR 大概需要 3 到 5 分钟但有些 PR 改动特别多或者仓库很大耗时会飙到十几分钟。设置 30 分钟阀值可以避免异常情况下 runner 长时间占用的费用问题。3.3 运行过程会发生什么工作流触发后可以到仓库的 Actions 页面看到运行日志。正常情况下日志会显示 Claude Code 正在初始化然后开始调用工具读取代码。每一步操作都有输出包括读取了哪些文件、执行了什么命令、最终生成的内容。第一次跑我强烈建议盯着日志看一遍。你会看到 Claude Code 怎么在代码库中定位相关信息。比如你让它审查登录模块它会先搜索路由定义找到 login 相关的 controller 和 service 文件然后逐个打开阅读。这个过程中的每一步都对应了一次工具调用。熟悉这个过程后你再写 prompt 就会有的放矢知道怎么引导它更快地找到重点。运行结束后Action 会调用 GitHub API 把结果发布成 PR 评论。你可以直接在 PR 页面看到结构化的问题列表每条都带着文件和行号。4. 常见问题与避坑指南4.1 认证和权限问题集锦我踩过的最基础的坑是ANTHROPIC_API_KEY没有正确配置。第一次配置 Action 时贪方便直接写在 YAML 文件里先不管安全性纯粹为了验证流程。结果 GitHub 直接拒绝运行提示包含敏感的硬编码密钥。后面改成 secrets 配置后一切正常。所以千万别图省事secrets 是唯一正解。还有一个坑是关于GITHUB_TOKEN的权限范围。如果你在 workflow 里配置了permissions块但只写了pull-requests: read那么 Action 发布评论时会收到 403 错误。日志里会显示类似Resource not accessible by integration的信息。解决方法是把permissions配置成全尤其是pull-requests: write和contents: write不能少。关于 fork 类 PR这里有个很微妙的限制。从 fork 仓库发来的 PR默认情况下无法访问仓库的 secrets这是 GitHub 的安全机制。所以如果你做开源项目外部贡献者的 PR 是没有办法用这个 Action 跑 Claude Code 审查的至少不能直接跑。我现在的做法是对于 fork 的 PR在评论里用/ai-review这种 slash 命令手动触发一个 workflow_dispatch 事件来运行审查这需要额外配置一个监听 issue_comment 事件的 workflow。4.2 成本控制的几个技巧成本是这类 Action 落地最大的阻力也是最容易被忽略的。我第一次全量跑了一个中型后端项目的所有 PR一周下来账单让我吃了一惊。控制成本的第一步是控制触发范围我前面已经说过了。第二步是限定模型同一套代码opus 的执行成本大概是 sonnet 的三到四倍普通功能开发项目完全用不到 opus。第三步是限制 Claude Code 的行动边界。关于行动边界这里有一个关键参数值得展开--allowedTools。如果不限制Claude Code 可以执行任何 shell 命令、读写任何文件。在 CI 环境里这问题不大runner 是临时的但成本上会出问题——它可以因为一个简单的类型错误把整个测试套件跑一遍甚至尝试安装依赖。这会浪费大量 token。我现在的做法是在 workflow 里显式限定工具白名单。比如审查任务只允许读文件和发布评论不允许执行命令run-command: claude -p --allowedTools Read Write Edit --output-format stream-json注意Edit是必要的否则它无法修改代码。但像Bash这种工具就不给了。这样一来任务聚焦token 消耗能减少一半。还有一个技巧是缓存机制没有意义别浪费时间研究这个方向。每个 runner 都是全新的环境Claude Code 的依赖安装是每次跑都要执行的。缓解的办法是接受这个现实或者干脆用自建的 repository runner让环境的启动速度快一些。4.3 稳定性与 Prompt 调优的实战心得Claude Code 在 CI 环境里的表现和你本地终端里不太一样。没有交互式反馈它一旦理解偏差就会沿着错误的方向跑下去。这时候 prompt 的质量就无比关键。我在实践中总结出三条 prompt 调优原则原则一明确输出格式。不说明输出格式Claude Code 可能输出一段散文而不是结构化的问题列表。我一般在 prompt 末尾加上“使用列表输出每条包含文件路径和行号”。有了这个约束结果提取和处理都方便很多。原则二给定判断依据。单纯说“检查代码质量”太模糊。我会说明具体的检查项比如“检查是否存在内存泄漏”、“检查错误处理是否吞掉异常”、“检查 SQL 是否有 N1 查询”。给它明确的检查清单相当于帮它划定了重点准确率明显提升。原则三提供正反示例。在系统提示里放一小段“好代码”示例和“坏代码”示例效果立竿见影。这其实是在用少样本学习的方式引导它的判断标准和人们带新人时给范例是一个道理。稳定性方面还有一个绕不开的问题是 API 限流。Anthropic API 有速率限制如果团队同时有多个 PR 触发审查可能遇到 429 错误。我在 workflow 里加了continue-on-error: false同时在 Action 运行前加了一个等待步骤用sleep做一个简单的随机退避。虽然不是最优雅的方案但有效。5. 场景扩展把 claude-code-action 真正用起来5.1 自动修复 Lint 错误并推送修复提交这个场景是我用得最多的特别好用。工作流触发时机是PR 打开时先跑一遍npm run lint如果失败把失败的输出作为 prompt 的一部分传给 Claude Code让它修复eslint/tsc报告的错误然后自动提交修复 push 到当前分支。- name: Run lint check run: npm run lint || true - name: Fix lint errors with Claude uses: anthropics/claude-code-actionv1 env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} with: github-token: ${{ secrets.GITHUB_TOKEN }} model: claude-sonnet-4-5 prompt: | 运行 npm run lint 检查代码修复所有报告的错误。 修复完成后运行测试确保没有破坏现有功能。 最后提交并推送所有修改。这里有个小心机npm run lint || true。这样即使 lint 失败后面的 steps 也能继续执行。因为 Claude Code 接手后自然会处理这些问题粗暴中断反而不利于流程推进。不过要注意自动修复 lint 和自动提审有本质区别。lint 修复结果是可预期的由工具规范化所以让 AI 自主提交不会有太大风险。但涉及业务逻辑的修改一定要保留在“生成 patch 人工确认”的模式不要让它直接 push。5.2 自动生成 PR 描述很多人写 PR 描述像挤牙膏要么不写要么用一句“Update”糊弄。这个场景非常适合用 Claude Code 处理因为它的输出天然就是给你看的内容。配置其实简单到不可思议直接用actions/checkout拿到 diff再传给 Claude Code让它根据 diff 生成描述通过 API 更新 PR。我的配置是这样的- name: Generate PR description uses: anthropics/claude-code-actionv1 env: ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} with: github-token: ${{ secrets.GITHUB_TOKEN }} prompt: | 请根据当前 PR 的代码变更生成一个结构清晰的 PR 描述。 包括 - 本次改动的背景和目的 - 核心设计思路 - 关键改动点按模块分类 - 影响范围评估 - 需要 reviewer 重点关注的代码位置 格式使用 GitHub 风格的 Markdown。这个方法一句话总结就是“把写 PR 描述的成本从开发者转移到 AI让不该花时间的人去写代码让 AI 去写文档”。实测下来生成的质量普遍高于团队 70% 成员手写的内容至少结构上完全可用。5.3 文档自动更新API 改了忘更新文档是团队协作中最常见的摩擦点之一。Claude Code 可以做这件事。思路是在代码合并到 main 后触发 workflow让 Claude Code 对比上一次 release 版本的 API 定义与当前代码的差异找到对应的文档文件更新并推送 commit。和 lint 修复类似这一步完全可以在无人值守下跑通。但有一点必须注意文档改动涉及很多上下文比如设计决策、历史背景这些信息不在代码里。所以这个流程更适合给“机械动作”兜底比如函数签名变更、参数增减、返回类型调整这类硬性变更不适合做大篇幅的设计文档重写。6. 聊聊我的一些习惯和建议最后分享一个我用了一段时间之后形成的习惯每个用 claude-code-action 的任务都先在本地跑一遍同样的 prompt 再进 CI。Claude Code 本来就是本地工具。你在仓库里claude -p 你的 prompt跑一次消耗的是你的本地资源验证 prompt 的效果后在推给 CI。这比每次都在 GitHub Actions 里等 5 分钟看结果要高效得多。还有一个小习惯是关于日志的。Action 跑完以后我会把 stdout 日志保存下来按日期归档。这不是为了审计而是为了调 prompt。当某个流程的效果退化或者突然翻车时翻出之前正常时的日志对比能快速找到是在哪一步开始偏离的。这个习惯帮我避免过至少三次“大改 prompt 结果全部变差”的灾难。你可能也注意到了这类工具强大的同时带来的核心问题其实是信任边界。它能写代码、能提 PR、能操作任何它能接触到的系统。GitHub Action 本身提供了权限隔离但你得自己定义好边界。我的底线是任何涉及生产环境的操作AI 只能生成建议不能直接执行。这个原则从来没有变过。claude-code-action并不复杂它做的事情用官方的描述来说是“把 Claude Code 装进 GitHub Actions”但真正用好它的关键不在于 YAML 怎么写而在于你怎么定义问题、怎么控制边界、怎么把任务拆到“AI 能胜任”和“必须留给人类”之间那条清晰的分割线。希望这篇实践记录能帮你少走点弯路。
