Claude Code 自动化 PR 治理：用文件名回溯量化「免人工审查」边界与工程落地

导语：当 Claude Code 等 AI 智能体能够自主创建 PR 时，工程瓶颈便从「写代码」转移到了「人工审查与合并」。本文基于一个真实运行的「一人公司」实验——由 Claude Code 定期启动、自主选择任务并提交 PR——深入剖析如何利用 gh、grep、awk 等命令行工具，以「变更文件名」为维度回溯统计历史 PR，量化「自动放行」与「人工介入」的边界。你将获得一套可复用的治理流程、边界策略演进思路以及生产环境避坑指南。

一、背景：AI 智能体 PR 洪流下的审查瓶颈

在一个由 Claude Code 定期驱动、自主选择任务并提交 PR 的「一人公司」实验环境中，人类设计者于 2026-10-19 记录到：在此之前，仅有 1 个 PR 在无人工审查的情况下被合并，其余 PR 均需等待人类合并 0.5 至 2 天。随着 AI 生成 PR 的数量增长，人工审查成为整个交付链路的瓶颈。

为了在「完全人工审查」与「完全自动放行」之间找到合理的边界，设计者提出了一种基于「变更文件名」的量化方法：在制定放行规则之前，先回溯历史 PR，统计「如果采用某条边界，将有多少 PR 可以免于人工审查」。这样，边界的宽窄便能用历史数据说话，而非凭直觉拍板。

二、核心方法：用文件名回溯统计历史 PR

2.1 准备两个目录清单

在仓库外创建工作目录（如 ~/pr-count），并创建两个文本文件：

• auto.txt：允许自动放行的文件路径 glob 列表（如预测路径代码、对应测试、版本号文件）。
• never.txt：禁止 AI 触碰的文件路径 glob 列表（如涉及真实资金的代码、危险阈值配置、CI/部署/容器定义）。

这两个清单是后续统计与治理的基础，需纳入版本控制并定期评审。

2.2 使用 gh 拉取已合并 PR 的文件列表

gh pr list 支持 --json files,headRefName 参数，并可通过 --state merged 筛选已合并 PR。默认 --limit 为 30，可根据需要调整。

#!/usr/bin/env bash
# 拉取最近 100 个已合并 PR 的文件列表与分支名
gh pr list --state merged --limit 100 --json files,headRefName 
  --jq '.[] | {branch: .headRefName, files: [.files[].path]}' 
  > merged_prs.json

2.3 用 grep 与 awk 按边界分类统计

将 auto.txt 与 never.txt 中的 glob 转换为正则表达式，对每个 PR 的文件列表进行匹配，输出三类计数：

• 自动放行：所有变更文件均匹配 auto.txt，且不匹配 never.txt。
• 人工审查：存在变更文件不匹配 auto.txt，或匹配 never.txt。
• 禁止触碰：存在变更文件匹配 never.txt（此类 PR 应被阻止创建）。

#!/usr/bin/env bash
# 将 glob 转为正则（简化示例，实际需处理 ** 与 * 差异）
AUTO_REGEX=$(paste -sd'|' auto.txt | sed 's/*/.*/g')
NEVER_REGEX=$(paste -sd'|' never.txt | sed 's/*/.*/g')

jq -r '.[] | [.branch, (.files | join(" "))] | @tsv' merged_prs.json |
while IFS=$'t' read -r branch files; do
  auto_match=true
  never_match=false
  for f in $files; do
    if echo "$f" | grep -qE "$NEVER_REGEX"; then never_match=true; fi
    if ! echo "$f" | grep -qE "$AUTO_REGEX"; then auto_match=false; fi
  done
  if $never_match; then
    echo -e "$brancht禁止触碰"
  elif $auto_match; then
    echo -e "$brancht自动放行"
  else
    echo -e "$brancht人工审查"
  fi
done | awk -F't' '{count[$2]++} END {for (k in count) print k, count[k]}'

三、真实案例：边界策略的演进与数据验证

3.1 初始白名单策略（2026-10-15）

人类设计者最初规定：仅当 PR 的所有变更文件均位于 auto.txt 白名单内时，才允许免人工审查合并。白名单包含：预测路径代码、对应测试、版本号文件。

截至 2026-10-18，公司共创建 4 个 PR，其中仅 1 个完全落在白名单内，被自动合并；其余 3 个因涉及任务调度目录（2 个）和危险管理目录（1 个）而转人工审查。值得注意的是，被自动合并的那个 PR，其指示书原本标注「需人工审查」，但实际变更文件恰好全部落在白名单内——边界由文件名决定，而非创建者的预期。

3.2 转向黑名单策略（2026-10-19）

2026-10-19，人类设计者将策略反转：不再要求「白名单内才放行」，而是「只要不触碰黑名单，全部放行」。黑名单保留：真实资金相关代码、危险阈值配置、CI/部署/容器定义。触碰黑名单的任务不会生成 PR。

策略放宽后，2026-10-19 至 2026-10-24 18:00 期间，自动化系统共合并 95 个 PR。同期有 41 条「未合并」记录，原因均为 CI 失败、与开发分支冲突或合并命令失败，无一因文件名被拒。

3.3 边界的持续迭代

边界并非一成不变。2026-10-23 与 2026-10-24，人类设计者再次调整黑名单，将部分非资金相关代码移出。这印证了一个原则：边界清单需要定期回顾与修正，用统计数据驱动调整，而非一次性设定。

四、工程落地：可复用的治理流程

4.1 流程步骤

• 定义边界清单：创建 auto.txt 与 never.txt，纳入版本控制。
• 回溯统计：使用上述脚本对历史已合并 PR 进行分类计数，评估不同边界下的自动放行比例。
• 制定门禁：在 CI 中集成文件名检查，阻止触碰黑名单的 PR 创建或合并。
• 持续监控：定期运行统计脚本，观察自动放行率与人工审查负载，动态调整清单。

4.2 关键配置示例

以下为 GitHub Actions 工作流片段，用于在 PR 创建时校验变更文件是否触碰黑名单：

name: PR Guard
on:
  pull_request:
    types: [opened, synchronize]
jobs:
  check-files:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check against never list
        run: |
          NEVER_REGEX=$(paste -sd'|' never.txt | sed 's/*/.*/g')
          git diff --name-only origin/${{ github.base_ref }}...HEAD | while read f; do
            if echo "$f" | grep -qE "$NEVER_REGEX"; then
              echo "::error file=$f::File is in never list, PR blocked."
              exit 1
            fi
          done

五、总结与展望

本文介绍的方法以极低的工具成本（gh、grep、awk）实现了 AI 智能体 PR 治理的量化决策。核心思想是：用历史数据预演边界效果，用文件名清单表达风险策略，用持续迭代替代一次性设定。随着 AI 生成代码的比例上升，这种「以文件为粒度」的治理模式将成为工程团队不可或缺的基础设施。