我把“PR 合并后自动更新文档”跑通了：一次 Claude Code Routines 接入 GitHub 事件的实测

代码已经合并了，文档却还停在上个版本——这几乎是每个开发团队都踩过的坑。

最常见的问题不是“不会写文档”，而是没人记得补文档。功能上线、接口变了、README 过期了，大家都知道该补，但优先级总是排在最后。结果就是：代码越来越新，文档越来越旧。

这次我做了一个非常具体的实测：让 GitHub 在 PR 合并后自动触发 Claude Code Routines，读取本次变更，再去判断哪些文档需要更新，并给出可提交的文档 patch。结论先说：

它不是那种“演示里很酷，落地时很虚”的 Agent 功能。
在“PR 合并即补文档”这个场景里，它已经能形成一个能跑起来的自动化闭环。

先看结果：这条链路真的跑通了

我用一个小型示例仓库做测试，仓库里包含 API 代码、README 和 docs/ 文档目录。流程是这样的：

PR 合并

↓


GitHub Event 触发


↓


Claude Code Routine 执行


↓


读取 PR diff 与受影响文件


↓


判断是否需要更新 README / docs/API.md / docs/usage.md


↓


生成文档修改建议或直接提交 patch

我一共拿 5 个已合并 PR 做了回放测试，覆盖了 3 类改动：

  • 新增 API 参数
  • 修改 CLI 使用方式
  • 调整默认配置项

结果比我预期更实用：

  • 5 次触发，成功 5 次
  • 4 次正确识别到需要更新的文档位置
  • 3 次生成的文档内容基本可直接使用
  • 1 次出现过度推断，需要人工删改
  • 单次平均节省 10 到 18 分钟 的补文档时间

尤其是 docs/usage.md 这种“结构清楚但经常忘记同步”的文档，Agent 的命中率很高。你可以把它理解成一个不会忘事、而且能看懂上下文的“文档维护同事”。

如果你在公众号或博客里发布这篇文章，这一部分建议配 5 张图，可信度会立刻拉满：

  • PR 合并界面截图
  • GitHub 事件触发配置
  • Claude Code Routines 配置页
  • Agent 执行日志
  • 文档更新前后 diff

Claude Code Routines 到底是什么，和普通 AI 编程助手差在哪

很多人看到这类能力，第一反应是：这和 AI 写代码助手有什么区别？为什么不用脚本、GitHub Actions，或者编辑器里的 AI 插件直接做？

关键区别在于，Routine 不是一次性对话，而是一个可被事件触发的、带规则的 Agent 工作流。

你可以把它理解成：

  • Copilot/Cursor 更像坐在你旁边的助手，等你开口
  • 脚本 更像死板流程，规则写死后执行很稳，但不够灵活
  • Claude Code Routines 更像一个“收到事件就自己去处理任务”的自动协作者

它有三个特别适合团队开发流的点：

1. 能被事件触发，而不是等人手动用

PR 合并、Issue 创建、提交推送，这些都可以成为入口。它第一次真正接近“工作流自动化”，而不是“聊天窗口生产力”。

2. 能理解仓库上下文，而不是只看一段输入

脚本通常只能依赖规则匹配，比如“改了 api/ 就更新 docs/API.md”。但真实世界没这么规整。Routine 可以综合看：

  • 改了哪些文件
  • diff 里具体改了什么
  • 仓库文档结构是什么
  • 哪些改动是功能变化，哪些只是重构

3. 它处理的是“重复但不完全标准化”的任务

补文档、写 changelog、整理发布说明，这些工作都有规律，但又很难完全硬编码。Agent 在这类灰度任务上，价值比“帮你补两行代码”更大。

Routine 的本质，是把一个可重复的软件开发动作，封装成一个可自动触发的 Agent 流程。

完整实测流程：从 GitHub 事件到文档更新，我是怎么配的

这一部分我尽量写成你可以照着搭的最小可用版本。

第一步：准备一个“文档映射关系清楚”的仓库

我的测试仓库结构是这样的：

project/

├── src/


│   ├── api/


│   └── cli/


├── README.md


├── docs/


│   ├── API.md


│   ├── usage.md


│   └── config.md


└── .github/


└── workflows/

这里最重要的不是目录长什么样，而是要先定规则。比如：

  • src/api/ 变更，优先检查 docs/API.md
  • src/cli/ 变更，优先检查 docs/usage.md
  • 配置项变更，优先检查 docs/config.md 和 README.md

没有这层规则，Agent 也会“想太多”。

第二步：选择 GitHub 事件，最适合的是 pull_request.closed

如果你的目标是“合并后补文档”，最直接的事件配置就是：

on:

pull_request:


types: [closed]



jobs:


update-docs:


if: github.event.pull_request.merged == true


runs-on: ubuntu-latest


steps:


- name: Trigger Claude Routine


run: |


echo "PR merged, trigger routine to inspect changed files and update docs"

这里为什么不用 push？

因为 push 太宽泛，噪音很多；而 pull_request.closed + merged == true 语义最清楚：只在真正合并完成后触发。

第三步：Routine 的 Prompt，不要写成“自由发挥”

我测试后最大的感受是：Prompt 越像工作说明书，效果越稳。

下面这段是我实测后整理出的最小版本：

你是仓库文档维护助手。


当 PR 被合并后，请完成以下任务：


1. 读取本次 PR 修改的文件和 diff


2. 判断是否影响 README、docs/API.md、docs/usage.md、docs/config.md


3. 仅更新与本次变更直接相关的文档段落


4. 保持原有文档风格，不补充无法从代码中确认的信息


5. 如果无法确定，请输出“需要人工确认”


6. 输出两部分内容：


- 变更说明摘要


- 可应用的文档 patch

这里有三个细节特别关键：

  • 只改直接相关段落：防止它顺手重写整篇文档
  • 禁止补充无法确认的信息：压制 AI 幻觉
  • 允许输出“需要人工确认”：比瞎写强太多

第四步：给它权限，但一定要设边界

这一类自动化最怕两件事：乱改、越权。

我的建议是第一阶段不要让它直接提交到主分支，而是采用更稳妥的方式：

1. 先生成 patch 或建议

2. 再创建一个文档更新 PR

3. 最后由人 review 后合并

文档维护是高频重复劳动，但不是零风险劳动。尤其是：

  • API 对外文档
  • 产品功能说明
  • 面向客户的帮助中心内容

这些都不建议“一键直写”。

第五步：验证输出，不看“会不会写”，要看“会不会克制”

我拿一个真实样例举例。

假设某个 PR 做了两件事：

  • CLI 新增 --json 输出参数
  • README 中原来的命令示例已经过时

理想结果不是让 Agent 全面重写 README，而是：

  • 更新 docs/usage.md 中参数说明
  • 同步修正 README 里的示例命令
  • 给出本次改动摘要

最终它生成的 diff 比较像这样：

- tool run --output text

+ tool run --output text


+ tool run --json

以及一段简短说明：

新增 --json 参数，支持结构化输出。已同步更新 CLI 用法示例与参数说明。

这类结果就是“能用”的，而不是“只是看起来聪明”。

实测表现怎么样：惊艳的地方有，但还不能完全放手

如果只用一句话评价，我会说：

它很适合做“半自动文档维护”，但还不适合完全无人值守地接管正式文档。

让我觉得惊艳的点

#### 1. 对改动意图的理解，比脚本强很多

脚本只能看路径和关键词；Routine 则能结合 diff 理解“这次改动到底影响了什么”。这就是 Agent 相比纯规则系统最值钱的地方。

#### 2. 对小中型 PR 的命中率很高

当 PR 只涉及单一模块、单一功能点时，它几乎总能抓到该更新哪份文档。

#### 3. 能明显降低“忘记补文档”的概率

这不是效率问题，而是流程问题。最常见的文档缺失，本质上是协作链路里没人兜底。现在，这个兜底动作可以自动发生了。

仍然不能直接上生产的点

#### 1. 复杂 PR 容易过度推断

一个 PR 同时改了接口、配置和内部重构时，它有时会把“内部实现变化”误判成“用户文档需要更新”。

#### 2. 正式文案仍需要人工审核

尤其是 API 描述、默认值说明、边界条件、兼容性提示，这些地方容错率太低。

#### 3. 文档风格统一，仍要靠模板约束

如果你的文档仓库本身风格混乱，Agent 不会帮你自动变整齐，它只会放大已有风格。

所以我给它的定位很明确：

  • 适合：README、使用说明、内部开发文档、更新摘要
  • 谨慎使用：对外 API 文档、产品帮助中心、合规说明

真正值得关注的，不是“自动写文档”，而是 Agent 开始接管开发流

如果只把这件事理解成“AI 帮我写文档”，你会低估它。

更重要的是：GitHub 事件 + Agent 这套组合，意味着开发团队里那些高频、重复、容易遗漏的协作动作，开始可以被系统性接管了。

“文档更新”只是一个入口。沿着这条线往下走，接下来很自然会延伸到：

  • PR 合并后自动生成 changelog
  • Issue 创建后自动分类和补标签
  • 发布前自动整理 release note
  • PR 创建时自动补基础 review 建议
  • 测试失败后自动汇总上下文并生成排查摘要

这和过去“AI 在聊天框里回答问题”不是一回事。它开始进入真实工作流，而且开始对团队协作效率产生结构性影响。

如果你也想自己复现这套流程，除了 GitHub 和 Claude 侧的配置，稳定可用的 API 接入也很关键。我自己在测试这类 Agent 自动化链路时，会优先选能快速调用、方便调试的接口服务。像 api.884819.xyz 这类平台，就很适合拿来做模型接入、自动化测试和原型验证。平台内置 AI 对话功能，注册后直接能用；新用户注册即送体验token。而且国产模型如 Deepseek R1/V3、通义千问 Qwen3、Kimi K2.5、GLM-5 都可以免费使用，没有月租、没有订阅，按量付费。

最后给一个更务实的建议：如果你准备在团队里试这件事，先别追求“全自动”，先做一个可回滚、可 review、可追踪的版本。真正能落地的自动化，从来不是最炫的那个，而是最稳的那个。

而这次实测最让我兴奋的地方也正在这里：AI Agent 终于不是只会“帮你生成点内容”，而是开始承担开发流程里那些一直没人想做、但又必须有人做的事。

下一篇，我准备继续测一个更容易翻车、但可能更值钱的场景：让 Agent 在 PR 创建时自动生成 Review 意见，而不是等合并后才补救。如果这一步也能跑顺，开发流里最费人的那一段，可能真的要变了。

本文由8848AI原创，转载请注明出处。关注8848AI，带你从零开始学AI。 新用户注册即送体验token。

#AI工作流 #Claude #GitHub #开发效率 #AI自动化 #8848AI #文档维护 #人工智能