---
{
  "title": "Git 协作与 AI 开发：变更、验证与授权",
  "summary": "从 Git 的协作机制出发，分析 AI Coding Agent 如何进入任务、实现、审查与仓库治理，并用五个公开项目和研发效能研究说明可靠提效所需的验证、权限与责任边界。",
  "date": "2026-08-10",
  "updated": "2026-08-10",
  "topic": "agent-systems",
  "tags": ["git", "coding-agent", "ci", "code-review", "developer-productivity"],
  "kind": "article",
  "status": "published",
  "visibility": "public",
  "canonicalUrl": "https://blog.k1412.top/articles/git-collaboration-ai-development/",
  "sourceRepo": "https://git.k1412.top/wuyang/research-blog",
  "preview": "/articles/git-collaboration-ai-development/git-collaboration-flow.png"
}
---

软件开发不是“把代码写出来”，而是把一个不确定的想法，经过决策、实现、验证和授权，变成能够由团队长期维护的产品变化。

Git 解决的是版本和变更记录问题；Issue、PR/MR、CI、代码审查、分支保护和发布系统共同解决协作与质量问题。AI 加入后，变化最大的不是 Git 命令，而是代码调查、实现、测试和初步审查可以大量并行。新的难题随之出现：生成速度超过审核速度、上下文不完整会被快速放大、Agent 可能接触不可信输入和写权限、局部任务变快却不一定让整个团队更快。

本文先解释这套系统怎样运转，再拆解 OpenClaw、OpenAI Codex、GitHub Copilot cloud agent、GitHub Agentic Workflows 和 Claude Code Action 的公开实现。重点不是产品介绍，而是回答四个问题：

1. 一项改动由谁决定，怎样进入主分支？
2. 团队如何证明它做对了，而不只是“代码能跑”？
3. AI 可以接管哪些工作，哪些权力不能交给同一个 Agent？
4. 怎样判断 AI 真的提高了研发效率，而不是只增加代码和 PR？

公开资料核对日期为 2026 年 8 月 10 日。源码分析固定在 OpenClaw `af73dbcc` 与 OpenAI Codex `a16863f8`；产品文档会持续变化，文中把“源码已验证”“官方产品文档”和“本文归纳”分开表述。

## 软件变更需要五类控制

一套可靠的开发流程，可以压缩成下面五句话：

1. **先定义变化。** 说明问题、目标、范围、风险和验收标准，再开始实现。
2. **把实现隔离。** 每项工作在独立分支或 worktree 中完成，不直接改主分支。
3. **用多种证据证明。** Diff、测试、静态检查、运行证据和审查意见解决不同问题，任何单一信号都不等于“正确”。
4. **用系统执行门禁。** 必需检查、Owner 审批和合并权限由平台强制执行，不能只写在文档里。
5. **把缺陷变成资产。** 真实问题修复后留下能在旧版本失败、在新版本通过的回归测试，避免同类错误再次进入主分支。

AI 不会改变这五件事。它改变的是每一步中“谁来执行”：人可以把调查、编码、测试和初审交给 Agent，但目标定义、风险接受和最终授权仍需要预先确定的责任人或确定性策略。

真正成熟的 AI 开发，不是让模型自由行动，而是把模型放进一个**权限有限、结果可验证、过程可追踪、失败可恢复**的工程系统。

---

## 一项改动如何进入软件系统

### 1. Git 不是完整开发流程

Git 原生擅长三件事：

- 保存每个版本的文件状态；
- 记录版本之间的父子关系；
- 合并来自不同分支的变化。

Git 本身不知道以下事情：

- 这项需求有没有价值；
- 代码是否符合产品意图；
- 测试是否充分；
- 谁有资格批准安全风险；
- 某次发布是否让线上故障率升高。

这些能力来自 Git 托管平台和团队流程：

| 对象 | 它保存什么 | 它解决什么问题 | 它不能单独证明什么 |
| --- | --- | --- | --- |
| Issue / 任务卡 | 问题、目标、讨论、Owner、优先级 | 为什么做、由谁推进 | 实现已经正确 |
| 分支 / worktree | 与主分支隔离的工作状态 | 并行开发、独立验证和回滚 | 改动值得合并 |
| Commit | 一组文件变化、父提交、作者和说明 | 形成可定位、可比较的版本 | 每个提交都达到发布质量 |
| PR / MR | 分支差异、讨论、检查和批准 | 把“请求合并”变成可审查事件 | 所有风险都已被发现 |
| CI | 在统一环境中执行脚本后的状态和日志 | 自动重复确定性检查 | 脚本没覆盖的行为一定正确 |
| CODEOWNERS / 审批规则 | 路径与责任人的映射 | 让高风险改动进入正确审核人视野 | Reviewer 一定理解所有上下文 |
| 分支保护 | 必需状态、批准数和禁止操作 | 把流程要求变成平台约束 | 规则本身设计正确 |
| Release / Deploy | 构建产物、版本和环境变化 | 把确定版本交付到环境 | 用户体验没有回退 |
| 监控与事故记录 | 指标、日志、告警和处置过程 | 发现测试未覆盖的真实问题 | 自动给出完整根因 |

所以，“使用 Git 开发”通常实际意味着：以 Git 版本为基础，通过 Issue、PR/MR、CI、Review、分支保护和发布系统，建立一条受控的变化链路。

![多人协作开发流程：需求、方案、Issue、分支开发、PR/MR、CI、人工评审和合并发布](/articles/git-collaboration-ai-development/git-collaboration-flow.png)

### 2. 把改动理解成状态迁移

新人经常把开发理解为“接到任务 → 写代码 → 提交”。团队真正管理的是一连串状态迁移，每次迁移都需要新的证据和相应的授权。

![一项软件改动从提出问题、接受工作、形成方案、分支开发、PR/MR、合入主分支到部署观察的状态与证据](/articles/git-collaboration-ai-development/change-evidence-state.svg)

| 从哪里到哪里 | 要回答的问题 | 最小证据 | 谁通常有权决定 |
| --- | --- | --- | --- |
| 问题 → 接受工作 | 值不值得做，现在做吗？ | 用户影响、复现或机会、目标和优先级 | 产品负责人或项目 Owner |
| 接受工作 → 形成方案 | 打算改变什么，哪些不改？ | 影响范围、约束、风险和验收标准 | 技术负责人、模块 Owner；重大变化需要架构或安全批准 |
| 方案 → 分支开发 | 信息是否足够开始实现？ | 可执行任务、Owner、依赖和环境 | 任务负责人 |
| 分支开发 → PR/MR | 候选改动是否达到审查条件？ | Diff、测试、文档、已知限制和检查清单 | 开发者或实现 Agent |
| PR/MR → 主分支 | 证据是否满足仓库门禁？ | 必需 CI 状态、审查意见、批准和最新主分支兼容性 | 平台规则与指定 Reviewer |
| 主分支 → 发布 | 这个版本是否可以进入目标环境？ | 构建产物、发布策略、环境检查和回滚准备 | 发布系统、值班 Owner 或变更审批策略 |
| 发布 → 继续保留 | 真实环境是否符合预期？ | 业务指标、SLO、日志、错误率和用户反馈 | 运营/研发 Owner；异常时触发回滚或修复 |

这里的关键不是“流程越多越安全”，而是每个决定有明确对象。一个拼写修复不需要架构评审；一个认证协议变化不能只因为单元测试通过就自动合并。

### 3. 三类决定不要混在一起

开发中的争论经常来自把不同层级的问题混成一个问题。

#### 3.1 产品决定

回答“为什么做、服务谁、优先级多高、做到什么程度”。例如：

- 是修复 1% 用户遇到的边界错误，还是先做影响 40% 用户的新能力？
- 一个失败应该自动重试，还是立即向用户显示错误？
- 兼容旧行为要保留多久？

这类问题没有编译器答案。AI 可以整理数据和提出方案，但最终取舍需要对产品结果负责的人决定。

#### 3.2 技术决定

回答“系统应该在哪里拥有这项行为”。例如：

- 权限检查放在 API 网关、业务服务还是客户端？
- 一个状态由数据库记录，还是由多个日志信号推断？
- 改动是否改变公开协议、数据迁移或安全边界？

小改动可以由模块 Owner 直接决定；跨模块、协议、安全和不可逆数据变化通常需要 RFC、设计文档或 ADR。

#### 3.3 实现决定

回答“在已确定方案下，代码具体怎样组织”。例如函数拆分、数据结构、错误类型和测试夹具。实现者或 Agent 可以承担大部分工作，但不能借实现细节悄悄改变产品和架构决定。

判断一项讨论属于哪一层，可以问一句：**如果换一种实现，用户行为或系统责任边界会不会变化？** 会变化，就不只是实现问题。

### 4. 按风险调整流程，而不是所有改动一刀切

流程成本应该和失败代价匹配。可以先用四档理解：

| 风险 | 典型改动 | 通常需要的检查和批准 |
| --- | --- | --- |
| 低 | 拼写、内部注释、无行为文档 | 格式、链接、文档构建；通常不需要专门 Owner |
| 中 | 局部逻辑、普通 Bug、非关键 UI | 相关单元/集成测试、普通 Review、标准 CI |
| 高 | 公共 API、配置默认值、持久化、并发、核心流程 | 兼容性检查、历史回归、相关端到端测试、模块 Owner |
| 极高 | 权限、认证、支付、数据删除、密钥、发布系统、CI 门禁本身 | 永久安全检查、威胁建模、独立 Reviewer、最小权限和明确人工批准 |

风险不是只看修改行数。下面几种“小 Diff”可能非常危险：

- 把默认值从 `false` 改成 `true`；
- 删除一个权限判断；
- 放宽测试断言；
- 修改数据库迁移顺序；
- 修改 CI 中“哪些失败可以跳过”的逻辑；
- 改变 Agent 可以访问的网络或写权限。

相反，大量自动生成代码、重命名或机械迁移可能行数很多，但风险边界清楚。可靠流程关注的是**行为面、依赖面和失败代价**，不是单纯 Diff 大小。

### 5. 本地钩子、CI 和分支保护分别负责什么

三者常被混为“自动检查”，实际可信度不同。

#### 本地钩子：尽快反馈

`pre-commit`、`pre-push` 或开发脚本适合在开发者等待最少的时候发现格式、静态错误和局部测试失败。它们提高体验，但可以被跳过，也可能受本机环境影响，因此通常不是最终信任边界。

#### CI：在统一环境重新计算

CI 从确定 Commit 检出代码，在受控 Runner 中执行编译、测试、扫描和构建。它的重要性不是“云端比本机高级”，而是结果可以被其他人和平台重复验证。

CI 仍有三个限制：

1. 仓库只会检查 CI 配置中写到的内容；
2. 测试和工作流本身也可能被错误修改；
3. 来自外部 PR 的代码可能是不可信输入，不能随意接触主仓库密钥。

#### 分支保护：执行合并政策

分支保护把以下要求变成 Git 平台的强制规则：

- 禁止直接推送默认分支；
- 必需状态全部成功；
- 必须获得指定数量或指定 Owner 的批准；
- 新 Commit 到来后旧批准是否失效；
- 是否允许强推、删除或管理员绕过。

因此，一套规则只有写进 CI 和分支保护后，才从“开发建议”升级成“不能静默绕过的门禁”。文档负责解释为什么，代码和平台负责执行已经确定的部分。

---

## 一项改动如何得到证明

### 6. “CI 绿了”不是完整结论

软件正确性不是一个布尔属性，而是一组不同问题：

| 证据 | 能回答什么 | 典型盲区 |
| --- | --- | --- |
| 编译、类型检查 | 语法、类型和依赖能否成立 | 产品行为是否正确 |
| lint、静态规则 | 是否违反明确的编码、安全或架构规则 | 运行时组合行为 |
| 单元测试 | 单个函数或模块在给定输入下是否满足断言 | 模块接线、真实依赖和环境 |
| 集成/契约测试 | 多组件交互、API/schema、数据库和依赖契约是否成立 | 完整用户路径和真实平台差异 |
| 端到端 Case | 从入口到结果的关键路径是否成立 | 未覆盖场景、环境稳定性和判定器错误 |
| 性能基线 | 延迟、资源、调用次数是否异常 | 功能是否正确、噪声来源 |
| 安全扫描 | 已知漏洞模式、密钥和依赖风险 | 业务授权和未知攻击方式 |
| AI Review | 大范围阅读、语义冲突和可疑遗漏 | 稳定复现、最终责任和确定性保证 |
| 人工 Review | 目标、方案、维护性和风险是否合理 | 代替机器执行所有重复检查 |
| 线上观测 | 真实负载下是否出现未知问题 | 发布前阻止问题 |

真正的合并结论是：“对本次风险而言，必须获得的证据已经齐全且通过。”这就是门禁策略的含义。

### 7. 为什么不能每次都跑全量测试

大型仓库的完整检查可能持续数小时，并占用大量 Runner。每次都跑全量会产生三个后果：反馈慢、队列拥堵、开发者倾向绕过检查。只跑开发者记得的几个测试又会漏掉间接影响。

所以成熟 CI 通常在两者之间做**影响分析和测试选择**。

![从 Git Diff、目录映射、依赖图、显式风险映射和历史测试生成检查清单，并在不确定时扩大检查范围](/articles/git-collaboration-ai-development/test-selection-funnel.svg)

第一版选择器通常不需要机器学习，可以按以下顺序工作：

1. **读取 Diff。** 区分新增、修改、删除和重命名；删除和公共入口变化通常更难安全缩小范围。
2. **目录映射。** 例如 `web/` 变化触发前端检查，`proto/` 变化触发生成物和兼容性检查。
3. **依赖图。** 找到直接依赖被改模块的构建目标和测试。
4. **相邻测试。** 源文件对应的同目录测试、集成套件和消费者测试。
5. **显式业务映射。** 权限、认证、发布、公共协议等风险不能只靠 import graph 推导；无论改动在哪，都追加永久门禁。
6. **历史失败映射。** 某类改动曾经让特定路径回退，就把对应回归 Case 固定加入。
7. **生成 Manifest。** 写明选了什么、跳过什么、依据是什么。
8. **不确定时扩大。** 公共契约、测试选择器自身、删除/重命名、依赖解析失败或影响面过大时，回退到模块全量或完整套件。

选择器本身也需要测试，因为“测试没有运行”比“测试运行失败”更隐蔽。最终 Required Gate 应同时判断：

- 选中的检查是否通过；
- 必需检查是否都被选择；
- 跳过是否来自 Manifest 的合法决策；
- failed、cancelled、timed out 和非法 skipped 是否都被正确视为失败。

### 8. 统一 Required Gate 为什么重要

分支保护如果直接绑定几十个 Job 名称，会很难演进：矩阵变化、任务改名和条件跳过都可能造成误判。更稳妥的结构是让内部 Job 自由拆分，最后只由一个聚合 Job 给出稳定状态。

```text
影响分析 → 选择检查 A / B / C
                     ↓
       A 成功，B 成功，C 失败
                     ↓
        required = 失败，并列出 C
```

聚合任务必须使用“无论上游成功还是失败都执行”的语义。否则上游失败后，聚合任务可能被平台标成 skipped，而分支保护看不到明确失败。OpenAI Codex 的 `blocking-ci.yml` 和 OpenClaw 的 `openclaw/ci-gate` 都使用了稳定聚合入口。

### 9. 把一次缺陷变成长期资产

“修复完成”不等于“这个问题以后不会回来”。要形成长期保护，至少经历六步：

1. **复现。** 在旧版本或已知错误版本上看到预期失败。
2. **定义判定器。** 明确怎样才算这个问题发生，而不是只看某条日志是否出现。
3. **修复责任源头。** 找到拥有错误状态或规则的模块，避免只在下游打补丁。
4. **候选版本通过。** 同一 Case 在新版本上满足预期。
5. **覆盖同类变体。** 防止测试只匹配一个用户输入、一个 ID 或一句固定文案。
6. **绑定未来改动。** 选择器能够在相关代码变化时自动运行这条 Case。

一条高质量回归 Case 至少包含：来源 Issue、初始状态、输入或刺激、预期结果、必须/禁止发生的过程、超时、环境要求、清理步骤、结构化证据和 Owner。

尤其要区分三种失败：

| 结果 | 含义 | 下一步 |
| --- | --- | --- |
| 旧版本没有按预期失败 | Case 没有复现原问题，不能证明修复 | 修正环境、输入或判定器 |
| 环境/凭据/Runner 在判定前失败 | Harness failure，不是产品结论 | 修复测试基础设施后重跑 |
| 旧版本按预期失败，新版本通过 | 修复证据成立 | 把 Case 固化到回归与影响映射 |

这正是 OpenClaw Mantis 把 baseline、candidate 和 harness failure 分开的原因。

### 10. 文档、规则、代码和测试怎样保持一致

AI 开发特别依赖文档，但文档并不会自动约束程序。可以把项目知识分为四类：

| 信息 | 例子 | 最合适的载体 |
| --- | --- | --- |
| 长期不可随意改变的原则 | 安全边界、兼容性承诺、架构禁区 | 宪法、Accepted ADR、协议正典 |
| 当前功能与操作方式 | 配置、API、用户流程、部署方式 | 产品/工程文档、README、Runbook |
| Agent 的执行纪律 | 测试命令、目录约束、代码风格、审查规则 | 根目录和局部 `AGENTS.md`、Skills |
| 可自动判断的行为 | schema、依赖方向、测试断言、性能阈值 | 静态检查、测试、CI 策略 |

关键原则是：**规则应尽量靠近它约束的代码，但能够确定执行的规则最终要落成机器检查。**

例如“修改 Agent 逻辑必须增加集成测试”可以写在模块 `AGENTS.md` 中，让实现者和 Reviewer 知道要求；CI 仍要运行该模块的集成测试。再例如“配置 schema 与帮助文档必须同步”如果能通过生成器和快照计算，就不应只让人或 LLM 阅读判断。

语义一致性无法全部静态化。一个文档声称“危险操作需要确认”，代码是否真的进入确认流程，可能需要 AI 进行跨文件审查，再通过动态 Case 执行真实链路。稳妥顺序是：

```text
AI 发现疑似冲突 → 人或权威文档确认正确含义
                 → 能静态化的写成规则
                 → 需要运行的写成 Case
                 → 进入 CI 或发布门禁
```

不要让同一个实现 Agent 临时解释规则、修改代码、修改测试、更新基线并宣布自己通过。那等于让被考核者同时出题、答题和判卷。

---

## AI 如何进入现有开发流程

### 11. AI 参与开发的四种位置

| 位置 | 工作方式 | 典型产物 | 主要风险 |
| --- | --- | --- | --- |
| 编程助手 | 人控制编辑器和节奏，AI 提供补全、解释和局部修改 | 代码片段、说明 | 人容易接受看似合理但未验证的输出 |
| Coding Agent | 接收完整任务，调查仓库、修改代码、运行测试并形成分支/PR | Commit、Draft PR、验证记录 | 上下文不足、范围膨胀、错误自证 |
| Review Agent | 独立读取 Diff、规则和相邻代码，输出分级问题 | Review findings | 误报、漏报、与实现 Agent 共享盲区 |
| Agentic Workflow | 由 Issue、PR、CI、定时任务或告警触发，持续处理维护工作 | Issue、评论、报告、受限修复 | 提示注入、权限过大、成本失控和自动化噪声 |

四者可以同时存在。开发者本地用助手，云端 Agent 处理一个 Issue，独立 Review Agent 审查 PR，定时 Workflow 调查 flaky tests。不能用“我们用了 AI”描述这四种完全不同的授权关系。

### 12. AI 让任务定义变得更重要

人类开发者遇到模糊需求时，会通过会议、经验和组织关系补上下文。Agent 不知道哪些隐含约定最重要，往往会选择最容易自洽的解释。任务越自动化，输入越需要接近可执行契约。

一份适合交给 Agent 的任务，至少说明：

| 字段 | 要回答的问题 | 反例 |
| --- | --- | --- |
| 问题 | 现在实际发生了什么？ | “优化一下这里” |
| 目标 | 用户或系统最终应看到什么？ | “让测试通过” |
| 范围 | 哪些模块和行为在本次内，哪些不在？ | 默认允许顺手重构整个仓库 |
| 验收 | 什么证据能证明完成？ | 只要求 Agent 自述“已修复” |
| 风险 | 权限、数据、兼容、性能或发布有哪些边界？ | 未说明不可逆操作 |
| 权威 | 冲突时以哪份协议、ADR 或 Owner 为准？ | 让 Agent 自选旧文档 |
| 预算 | 时间、模型调用、工具、文件和网络限制是什么？ | 无限循环直到“感觉完成” |

好的任务不是提前指定每一行代码，而是把正确性和权力边界说清楚，给实现保留空间。

### 13. Agent 怎样获得项目上下文

Agent 的上下文通常来自四层：

1. **全局工作约定。** 例如通用安全要求、提交偏好和工具使用规则。
2. **仓库级规则。** 项目构建、测试、文档和架构入口。
3. **目录级规则。** 某个服务、UI、协议或数据库模块的特殊要求。
4. **任务期证据。** Issue、Diff、代码、历史 Commit、测试输出和运行日志。

OpenAI Codex 的 `AGENTS.md` 发现机制从项目根目录走到当前工作目录，越靠近当前目录的规则越晚加载，可以覆盖上层规则。官方文档还建议把 repository-wide 的 Code Review Rules 放在根目录，把服务特定规则放在相应子目录。

这解决的是“Agent 看见哪些要求”，不等于要求已经执行。可以把规则分成三类：

| 规则类型 | 示例 | 最终保障方式 |
| --- | --- | --- |
| 操作指导 | 使用 `just test`，不要直接运行 `cargo test` | Agent 指令 + CI 使用同一入口 |
| 语义审查 | 不要在消费者层掩盖上游状态错误 | AI/人工 Review + 架构测试或历史 Case |
| 硬约束 | 不允许修改默认分支、不能访问生产密钥 | 沙箱、权限系统、分支保护和独立执行器 |

如果一个安全要求只写在 Prompt 里，模型忽略它时系统仍会执行危险动作，这就不是可靠的安全边界。

### 14. Agent 的权限边界怎样设计

Agent 会读取 Issue、PR 评论、代码、网页和工具结果。这些内容可能包含错误说明，也可能包含提示注入。安全设计不能假设模型总能识别恶意文本。

![从不可信事件进入只读上下文和 Agent 沙箱，候选输出经过确定性验证与独立写入任务，再由 CI、Code Owner 和人工批准控制合并](/articles/git-collaboration-ai-development/agent-trust-boundary.svg)

一条成熟的权限链通常包含：

1. **限制触发者。** 高权限任务只允许有写权限的成员、受信 Bot 或明确事件触发。
2. **隔离运行。** 使用临时容器、云环境或 worktree，不直接在生产机器和主分支工作。
3. **最小读取。** 只提供完成任务所需仓库、网络和 MCP；不默认挂载所有内部系统。
4. **Agent 不持有写凭据。** Agent 先生成补丁或结构化请求。
5. **确定性验证输出。** 检查 schema、允许操作、目标仓库、数量、补丁大小、路径和威胁信号。
6. **独立写入任务。** 只有通过验证的请求，才使用短期、最小权限凭据写入分支、Issue 或评论。
7. **分支保护继续有效。** Agent 产生的 PR 仍需 CI、Owner 和批准。
8. **保留审计记录。** 保存触发者、输入、Agent 运行、Commit、检查和授权动作。

这叫职责分离：即使 Agent 被误导，它能直接造成的影响仍受沙箱和权限限制；即使它生成恶意请求，独立验证器仍可拒绝；即使它成功创建 PR，也不能自行批准和合并。

### 15. 人、AI 和工程系统的职责不是按职位切分

![AI 加入后，人、AI 与工程系统在目标、实现、验证和审批中的职责分工](/articles/git-collaboration-ai-development/ai-responsibility-lanes.png)

| 环节 | AI 擅长 | 工程系统擅长 | 人必须承担的部分 |
| --- | --- | --- | --- |
| 需求 | 汇总反馈、搜索证据、提出候选方案 | Issue 模板、路线图和决策记录 | 决定价值、优先级和不做什么 |
| 调查 | 搜索调用关系、相邻实现、历史和依赖 | 代码索引、依赖图、日志平台 | 判断哪些证据足够改变方向 |
| 实现 | 编码、重构、补测试和文档 | 分支/worktree、文件和工具权限 | 处理关键歧义和批准范围变化 |
| 验证 | 生成测试、分析失败、提出影响范围 | 编译、测试、schema、扫描和性能阈值 | 确认验收是否代表真实需求 |
| 审查 | 进行大范围第一轮 Review | Diff、CODEOWNERS、审计日志 | 评估维护成本、产品和安全风险 |
| 合并 | 准备 PR 和证据 | Required Gate、分支保护和合并队列 | 接受高风险改动与例外责任 |
| 线上 | 汇总日志、关联变化、提出修复 | 监控、回滚、事故和回归系统 | 决定处置、发布和用户沟通 |

一句话概括：**AI 处理大量阅读、生成和比较；工程系统执行可重复规则；人负责意图、取舍和责任。**

---

## 五个公开项目如何把 AI 放进 Git 流程

![AI 在编程助手、Coding Agent、Review Agent 和 Agentic Workflow 四种工作方式中的位置](/articles/git-collaboration-ai-development/ai-project-workflow-positions.png)

这一部分不比较模型“谁更聪明”，而是比较工程控制面：任务从哪里来、Agent 能做什么、结果由谁验证、什么条件下可以改变仓库状态。五个案例解决的问题并不相同，不能放在一张“AI 编程产品排行榜”里直接比较。

| 案例 | AI 的主要位置 | 公开实现最值得研究的点 | 默认信任边界 |
| --- | --- | --- | --- |
| OpenClaw | 社区贡献者使用 AI；仓库内维护 Agent | 修复证据图、按改动选测试、baseline/candidate、受限自动优化 | 普通 PR 门禁；极少数专用任务拥有受限写权限 |
| OpenAI Codex 仓库 | 人或 Agent 实现，维护者审核；Codex 可独立 Review | 目录级规则、相关快速检查、统一 Required Gate、主分支全量验证 | PR 不能因为实现者是 Agent 而跳过维护者和 CI |
| GitHub Copilot cloud agent | 云端 Coding Agent | 独立分支、会话日志、默认不自批/不自合、Actions 审批 | 有写权限者触发；Agent 只产出待审 PR |
| GitHub Agentic Workflows | 事件驱动的通用 Agent Workflow | Agent 只读、safe outputs、独立写入任务、允许列表 | 不可信事件与有凭据写入严格分离 |
| Claude Code Action | GitHub Actions 中的 Coding Agent | 触发者限制、短期 token、事件安全、提交到默认分支时转成 PR | 默认只允许有写权限用户触发，变更仍走 PR |

### 16. OpenClaw：不是“AI 自动写代码”，而是一套证据纪律

OpenClaw 是一个公开、活跃且接受 AI 辅助贡献的仓库。它的特殊价值不在于使用了某个模型，而在于把 Agent 容易犯的错误写成了具体工程纪律。本节基于固定源码快照 [`af73dbcc`](https://github.com/openclaw/openclaw/tree/af73dbcc834027e84d8717e17c504020a17e567a)，不是对未来版本的承诺。

#### 16.1 接受 AI 贡献，但不降低证据要求

它的 [`CONTRIBUTING.md`](https://github.com/openclaw/openclaw/blob/af73dbcc834027e84d8717e17c504020a17e567a/CONTRIBUTING.md) 明确允许 AI/vibe-coded PR，同时要求贡献者披露 AI 使用情况、说明测试证据并完成自动审查。这种政策的重点是：**作者可以是人，也可以大量借助 AI；合并条件不因此改变。**

这比“禁止 AI 代码”和“默认相信 AI 代码”都更可执行，因为仓库真正能控制的是改动和证据，无法可靠判断每一行代码由谁键入。

#### 16.2 Repair Doctrine 先画改动证据图，再决定改哪里

OpenClaw 根目录 [`AGENTS.md`](https://github.com/openclaw/openclaw/blob/af73dbcc834027e84d8717e17c504020a17e567a/AGENTS.md) 的 Repair Doctrine 要求修复前建立一张简化证据图：

```text
用户可见症状
    ↓
最先出现错误状态的位置
    ↓
拥有这个状态或规则的模块
    ↓
读取该状态的相邻功能
    ↓
覆盖这些行为的已有测试
```

为什么这对 Agent 特别重要？因为模型看到一个失败断言后，很容易在断言附近增加分支，使当前 Case 通过，却没有修复产生错误状态的上游。

举一个抽象例子：消息列表重复显示一条回复。最小 Diff 可能是在 UI 中去重；责任源头却可能是重试后服务端重复提交。如果只改 UI：

- 其他客户端仍会重复；
- 统计和通知仍会按两条消息计算；
- 数据库继续积累错误状态；
- 原本应幂等的服务责任被掩盖。

证据图要求实现者同时检查生产代码、直接消费者、相邻功能和已有测试，再把修改放到拥有责任的边界。它不是要求每次遍历整个仓库，而是防止“只围着失败文件打补丁”。

#### 16.3 测试范围由改动影响推导，不由 Agent 随口决定

OpenClaw 的 [`docs/ci.md`](https://github.com/openclaw/openclaw/blob/af73dbcc834027e84d8717e17c504020a17e567a/docs/ci.md) 描述了 PR preflight：先根据改动生成检查清单，再运行目标检查。选择依据包括：

- 文件所在区域；
- 测试与源文件的相邻关系；
- import/dependency graph；
- 显式维护的路径映射；
- 无法可靠缩小范围时的 broad fallback。

同时，安全检查属于永久门禁，不因为“这次看起来只改文档或 UI”就完全交给模型判断是否需要。主分支再运行更广的套件，用快速 PR 反馈与完整覆盖换取平衡。

preflight manifest 很重要：它让团队看到“没跑哪些测试，以及为什么没跑”。如果只展示绿勾，人们无法区分“测试通过”和“测试根本没被选择”。

#### 16.4 `openclaw/ci-gate` 把复杂流水线收口成一个合并结论

内部任务可以并行、按条件跳过或采用矩阵，但最终 `openclaw/ci-gate` 会汇总结果，并检查 PR 证据是否齐全。分支保护绑定这个稳定名称，不必了解每个内部 Job 的动态变化。

这是一种两层设计：

```text
执行层：尽量快地选择、并行和扩展检查
政策层：用一个稳定 Gate 判断是否满足合并要求
```

前者可以经常优化，后者保持对分支保护的稳定接口。

#### 16.5 Mantis 用已知错误版本证明“测试真的能抓住问题”

OpenClaw 的 [`Mantis`](https://github.com/openclaw/openclaw/blob/af73dbcc834027e84d8717e17c504020a17e567a/docs/concepts/mantis.md) 将修复验证拆成两个隔离 worktree：

- baseline：包含已知问题的版本；
- candidate：包含候选修复的版本。

同一个 typed oracle 分别执行。有效证据不是“candidate 通过”，而是：

```text
baseline 触发了预期缺陷
candidate 不再触发缺陷并满足正向行为
harness 本身没有在到达判定前失败
```

这样可以发现一种常见假修复：测试从未真正到达错误路径，所以两个版本都通过。Mantis 还输出结构化比较和证据文件，使 Reviewer 能复盘结论，而不是只相信 Agent 的摘要。

#### 16.6 Test Performance Agent 展示了自动写入应该多么克制

OpenClaw 的 [`test-performance-agent.yml`](https://github.com/openclaw/openclaw/blob/af73dbcc834027e84d8717e17c504020a17e567a/.github/workflows/test-performance-agent.yml) 是少见的高自治示例，但它并不是“把整个仓库交给 Agent”：

- 只从受信任且成功的主分支运行，也可按日触发；
- 先运行完整 baseline；
- Agent 在受限工作区中优化测试性能；
- 禁止新增、删除、重命名和未跟踪文件；
- 只允许修改明确路径；
- 修改后再次运行完整报告和仓库检查；
- 测试数量不能减少；
- 只有全部门禁通过，自动化步骤才提交并推送结果。

这揭示了一个重要原则：**越接近自动写入，任务目标越要单一，修改面越要窄，判定器越要确定。** “让 Agent 自主完成任意 Issue 并直接提交主分支”几乎没有同等强度的可计算约束，因此不能照搬这种自治等级。

### 17. OpenAI Codex 仓库：快速 PR 检查与主分支完整验证分层

本节基于 OpenAI Codex 固定源码快照 [`a16863f8`](https://github.com/openai/codex/tree/a16863f8704831d13e041ed7dba2c4a57a2a940b)。它展示的不是 Codex 产品全部能力，而是这个大型 Rust 仓库怎样管理贡献和 CI。

#### 17.1 先就问题和方案达成一致，再投入实现

[`docs/contributing.md`](https://github.com/openai/codex/blob/a16863f8704831d13e041ed7dba2c4a57a2a940b/docs/contributing.md) 对外部贡献采取邀请方式，并强调先讨论 Issue 和方案。Bug 修复应提供能够在修复前失败、修复后通过的测试；Commit 保持原子性，维护者审核后通常 squash merge。

这并不是认为代码稀缺，而是认为维护承诺稀缺。AI 将实现成本压低后，团队更需要先判断：

- 这个行为是不是项目愿意长期支持的；
- 方案是否符合已有架构方向；
- 新配置、API 和依赖是否增加长期表面积；
- 谁会在作者离开后继续维护。

#### 17.2 `AGENTS.md` 把局部测试纪律放到对应目录

Codex 仓库根和子目录中的 `AGENTS.md` 会给 Agent 精确命令和模块规则。例如，Agent 逻辑变化必须增加集成测试，UI 变化需要更新快照。这比把所有规则堆在根目录更有效：进入具体目录工作的 Agent 只加载与当前作用域更相关的约束。

OpenAI 的 [`AGENTS.md` 官方文档](https://learn.chatgpt.com/docs/agent-configuration/agents-md) 说明了发现顺序：从项目根目录到当前工作目录加载规则，越接近工作目录的文件越具体。这里必须再次区分：`AGENTS.md` 是上下文注入，不是权限系统；规则中的测试命令仍应由 CI 重跑。

#### 17.3 PR 优先获得相关快速反馈，主分支承担更广验证

[`rust-ci.yml`](https://github.com/openai/codex/blob/a16863f8704831d13e041ed7dba2c4a57a2a940b/.github/workflows/rust-ci.yml) 先检测改动区域，再安排相关构建和测试；[`blocking-ci.yml`](https://github.com/openai/codex/blob/a16863f8704831d13e041ed7dba2c4a57a2a940b/.github/workflows/blocking-ci.yml) 汇总 Bazel、blob size、依赖许可与漏洞、拼写、仓库检查、Rust CI 和 SDK 检查，最后由一个始终执行的 `required` Job 决定合并状态。

进入主分支后，[`postmerge-ci.yml`](https://github.com/openai/codex/blob/a16863f8704831d13e041ed7dba2c4a57a2a940b/.github/workflows/postmerge-ci.yml) 再执行更完整的 Rust 和 V8 canary 验证。

这是一种常见分层：

| 时点 | 目标 | 策略 |
| --- | --- | --- |
| PR 内 | 尽快告诉作者“当前候选能否合并” | 相关检查、永久风险门禁、稳定聚合结论 |
| 合入主分支后 | 发现跨改动组合或罕见平台问题 | 更全矩阵、canary、完整套件 |
| 发布前/后 | 证明产物和真实环境可用 | 产物验证、渐进发布、监控与回滚 |

后置检查不是降低 PR 质量，而是承认低概率、跨平台和组合问题不一定适合阻塞每个开发者数小时。前提是主分支异常能被快速发现、停止发布并明确修复。

#### 17.4 Codex Review 是额外审查者，不是合并授权者

OpenAI 官方 [`Code Review`](https://learn.chatgpt.com/docs/code-review) 支持审查相对基线、未提交改动、单个 Commit 或自定义范围，输出问题但不修改工作树；GitHub 集成可自动审查或通过 `@codex review` 按需触发，发现问题后再启动独立修复任务。仓库还能用 `AGENTS.md` 中的 Code Review Rules 定义作用域规则。

这种分离减少了实现 Agent 自证的偏差：

```text
实现 Agent：目标是完成任务
Review Agent：目标是寻找候选缺陷
CI：重复执行确定性检查
人类 Reviewer：决定风险和维护责任是否可接受
```

四者仍可能共享盲区，所以重要改动不能只依靠“第二个模型看过了”。

### 18. GitHub Copilot cloud agent：Agent 创建候选分支，人保留合并权

Copilot cloud agent 处理 Issue 或任务后，在云环境中修改代码并创建 PR。其公开安全模型值得注意，因为它没有把“能写代码”等同于“能改变默认分支”。根据 GitHub 的[风险与缓解措施](https://docs.github.com/en/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/risks-and-mitigations)：

- 默认只有拥有仓库写权限的用户可以触发；
- Agent 在单独的 `copilot/` 分支或指定 PR 分支工作；
- 分支保护和 Required Checks 继续生效；
- Agent 不能把自己的 PR 标记 Ready、批准或合并；
- 其触发的 Actions 默认需要有写权限用户批准，触发任务的人不能自己批准该次运行；
- Commit 和会话日志保留身份与过程证据；
- GitHub 会过滤提示中的隐藏字符，但这只是防护的一层。

这里存在两个不同的“人”：任务发起人允许 Agent 开始工作；另一个有资格的人批准高风险 Actions 或 Review。这样避免同一个人借 Agent 绕过原本需要独立批准的规则。

仓库还可以增加[自定义 guardrails](https://docs.github.com/en/enterprise-cloud@latest/copilot/tutorials/cloud-agent/build-guardrails)，例如阻止特定路径、验证生成文件、限制依赖或强制额外测试。Guardrail 应执行仓库确定的政策，而不是把一个模糊问题再次交给模型自由判断。

### 19. GitHub Agentic Workflows：最清楚的“读与写分离”范式

[GitHub Agentic Workflows](https://github.github.com/gh-aw/) 允许用自然语言描述定时或事件触发的维护任务，例如总结 Issue、分类反馈、调查测试失败或生成候选修复。它与一般 GitHub Actions 最大的差别，不是多了 LLM，而是为不可信上下文设计了一套编译和运行边界。

#### 19.1 Agent 默认只读且看不到 Secrets

Agent 在隔离环境中读取事件和仓库内容，默认没有仓库写权限，也不直接拿到长期 Secrets。网络访问和工具受到沙箱或防火墙约束。这样，即使 Issue 评论包含提示注入，模型也无法直接把任意内容写回仓库或泄露所有凭据。

#### 19.2 Agent 只能申请 safe outputs

Agent 不直接调用“创建 Issue”“提交 PR”之类高权限 API，而是生成结构化 safe output，例如：

```json
{
  "operation": "create_issue",
  "title": "候选标题",
  "body": "候选正文",
  "labels": ["triage"]
}
```

运行时先缓存请求，做 schema、数量、允许操作、目标、补丁大小、路径和威胁检测；通过后再由独立、持有短期凭据的 Job 执行。官方 [safe outputs 文档](https://github.github.com/gh-aw/reference/safe-outputs/) 还支持允许列表和最大数量等约束。

这个结构与普通工具调用的本质差异是：Agent 生成的不是已经完成的副作用，而是一份**待授权的动作请求**。

#### 19.3 Safe output 不是绝对安全

官方文档明确说明，safe outputs 主要降低 Agent 内容引发的风险，不能修复底层 Runner、Actions 配置、依赖供应链或错误权限策略。若独立写入 Job 本身接受任意 shell、拥有过大 token 或使用不安全事件，前面的隔离仍可能被绕过。

因此，一条完整边界需要同时审查：

```text
事件可信度 → Agent 沙箱 → 输出 schema → 政策验证
→ 写入凭据 → GitHub 权限 → 分支保护 → 人工授权
```

### 20. Claude Code Action：事件类型本身也是安全边界

Anthropic 的 [`claude-code-action` 安全文档](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md) 强调：默认只有有写权限的用户可触发，Bot 默认不能触发；运行使用短期、仓库范围 token；如果任务需要向默认分支提交，推荐创建 PR 供人审查。

它特别提醒谨慎使用 `pull_request_target` 和 `workflow_run`。原因不是名称危险，而是这类事件可能在有主仓库权限或 Secrets 的上下文中运行，同时又检出外部贡献者可以控制的代码。一个典型危险组合是：

```text
外部 PR 控制工作流要执行的脚本
+ pull_request_target 提供主仓库权限或 Secret
+ Workflow 检出并执行外部 PR 的 head
= 不可信代码获得受信任权限
```

防护不能只靠 Prompt 说“不要泄露 Secret”，而应避免把不可信代码与高权限运行上下文放在同一 Job；需要写操作时，使用最小权限、固定动作和独立审批。

### 21. 五个案例共同说明了什么

公开实现中没有一个成熟方案把全部权力交给同一个 Agent。它们的共同结构是：

1. 用 Issue、任务契约或受信事件定义工作；
2. 在独立分支、worktree 或云环境中产生候选改动；
3. 让 Agent 读取与目录相关的规则，而不是依赖一个无限长总 Prompt；
4. 用确定性检查重新验证模型输出；
5. 对测试选择、跳过和失败保留结构化证据；
6. 将写操作限制在分支、PR、评论或经过验证的 safe outputs；
7. 由独立 Gate、Owner 或人类保留合并和高风险授权。

它们也有明显差异：OpenClaw 更像社区仓库内的 AI 开发纪律与专项自治实验；Codex 展示大型仓库的贡献和 CI 分层；Copilot cloud agent 与 Claude Code Action 是托管 Coding Agent；Agentic Workflows 则是事件驱动自动化框架。把其中一个案例的“自动 Commit”单独截出来，会丢失它前后非常严格的触发、路径和判定限制。

---

## 如何判断 AI 是否提高研发效率

### 22. 先区分局部速度和系统吞吐

AI 最容易加速的是一个人当前正在做的动作：搜索代码、生成样板、写测试、解释失败和准备 PR。团队真正关心的是从需求进入到用户获得可靠变化的总时间。

可以用一个简化价值流理解：

```text
等待决策  →  等待上下文  →  调查与实现  →  等待 CI
→ 等待 Review  →  返工  →  等待发布  →  线上恢复
```

假设一项改动原来需要：

| 阶段 | 原用时 | AI 后用时 |
| --- | ---: | ---: |
| 排队等需求明确 | 2 天 | 2 天 |
| 调查与编码 | 8 小时 | 3 小时 |
| CI 排队与运行 | 2 小时 | 3 小时 |
| 等待 Review | 1 天 | 2 天 |
| 修改 Review 意见 | 3 小时 | 5 小时 |
| 等发布窗口 | 2 天 | 2 天 |

编码快了 5 小时，但总交付时间可能更慢。原因可能是 Agent 生成了更大的 Diff、增加了 Reviewer 认知负担，或 PR 数量增长后 CI 和审查成为新瓶颈。

所以“生成代码速度”是活动效率；“从接受工作到可靠上线”是流动效率。后者才代表组织交付能力。

### 23. 公开研究为什么会给出看似冲突的答案

目前没有一个数字能代表所有团队的 AI 提效幅度。不同研究测量的任务、参与者、工具成熟度和结果质量不同。

#### 固定小任务：容易观察纯编码加速

GitHub 在 2022 年公布的[受控实验](https://github.blog/news-insights/research/research-quantifying-github-copilots-impact-on-developer-productivity-and-happiness/)中，95 名专业开发者完成一个固定 JavaScript HTTP server 任务，使用 Copilot 的一组平均快约 55%。这个结论适合说明：在边界明确、可快速验收的编码任务上，补全工具可能显著缩短实现时间。

它不能直接推导“整个研发组织快 55%”，因为实验没有包含长期设计、多人审查、遗留系统、发布和线上维护。

#### 熟悉真实仓库的任务：上下文和验证成本会占主导

METR 在 2025 年发布的[早期研究](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/)观察 16 名熟悉大型开源仓库的开发者完成 246 个真实任务，早期 2025 工具条件下使用 AI 反而慢 19%。参与者却主观认为自己更快，说明感受、生成速度和完整任务时间可能不同。

METR 随后在 [2026 更新](https://metr.org/blog/2026-02-24-uplift-update/)中认为更新工具很可能已经改善结果，但指出选择偏差、计时和并行 Agent 使测量更困难：开发者可能把适合 AI 的任务留给实验，把更难任务排除；等待 Agent 时还会并行做其他事。更新数据不足以给出一个稳定、普适的净加速数字。

#### 组织层面：AI 会放大已有系统

[DORA 2025 报告](https://dora.dev/research/2025/dora-report/)把 AI 描述为组织能力的放大器。拥有清晰文档、快速反馈、可靠平台和小批量交付的团队，更容易把生成速度转成稳定吞吐；需求混乱、测试脆弱、审查拥塞的团队，会更快地产生返工和积压。

这三组结论并不矛盾：

```text
固定任务测“做一个明确动作有多快”
真实仓库测“补足上下文并交付一个改动有多快”
组织研究测“整个系统能否吸收更多变化”
```

### 24. 不要用代码量、Commit 数和 PR 数评价人

代码行数、Commit 数、PR 数和 Agent 会话数容易收集，却很容易被优化错：

- Agent 把一个简单函数写成更多代码，指标反而更好；
- 团队拆出大量低价值 PR，吞吐看似上升；
- 开发者因为担心指标而减少重构、删除代码和帮助同事；
- 自动生成测试数量上涨，但断言只验证实现细节；
- Review Agent 输出更多评论，不代表发现更多真实问题。

这些数字适合用来解释负载，例如“PR 数翻倍导致 Review 等待升高”，不适合作为个人绩效目标。

### 25. 一个可用的指标框架：结果、流动、质量、人的体验与治理

指标不是越多越好。先明确要做什么决策，再选择能改变该决策的少量指标。

#### 25.1 交付与稳定性：DORA 五项指标

[DORA 指标指南](https://dora.dev/guides/dora-metrics/)当前列出五项软件交付指标：

| 指标 | 回答什么 | AI 场景中的解释 |
| --- | --- | --- |
| Change lead time | 一项变化从开始到进入生产需要多久 | 编码变快是否真正缩短总周期 |
| Deployment frequency | 团队多频繁向生产交付变化 | 是否能够以更小批次稳定发布 |
| Failed deployment recovery time | 失败发布后恢复服务需要多久 | AI 是否帮助诊断和回滚，而非放大事故 |
| Change fail rate | 部署后需要修复、回滚或处置的比例 | 更快生成是否牺牲正确性 |
| Deployment rework rate | 部署中用于处理非计划返工的比例 | AI 生成的变化是否增加隐藏返工 |

这五项应按服务或价值流观察趋势，不要用来比较不同性质的个人和仓库。

#### 25.2 工作流拆解：等待时间比“AI 思考时间”更重要

对每个 PR/MR 可以记录状态时间戳：

```text
issue_accepted_at
implementation_started_at
first_candidate_at
ci_ready_at
review_requested_at
first_human_review_at
approved_at
merged_at
deployed_at
incident_or_rollback_at
```

由这些事件推导：

- 首个候选耗时：开始实现到第一个可运行候选；
- CI 首次通过耗时和重跑次数；
- 首次人工 Review 等待时间；
- Review 后返工轮次；
- 合并等待和发布等待；
- 从接受到部署的总 lead time。

如果引入 Agent 后 `first_candidate` 快很多，而 `first_human_review` 和返工轮次上升，真正瓶颈已经从编码移到理解和验证。此时继续增加并行 Agent 只会扩大队列，应该缩小任务、提高 PR 证据质量或扩展 Review 容量。

#### 25.3 质量：不仅看“最终合并了”

质量至少包括：

- PR 前发现的缺陷；
- CI 发现的缺陷及其所属检查；
- Review 发现的真实问题、误报和严重级别；
- 合并后但发布前发现的问题；
- 发布后的回滚、热修和事故；
- 同类缺陷是否已有历史 Case 却未运行；
- 修复后是否留下新的自动回归。

“AI Review 评论数”不是质量指标。更有意义的是经人确认的有效发现率、漏到后续阶段的缺陷、严重问题平均发现时间，以及历史缺陷再次出现的比例。

#### 25.4 人的体验与协作：SPACE 提醒我们不要只看活动量

微软研究提出的 [SPACE 框架](https://www.microsoft.com/en-us/research/publication/the-space-of-developer-productivity-theres-more-to-it-than-you-think/) 包含 Satisfaction and well-being、Performance、Activity、Communication and collaboration、Efficiency and flow。它提醒团队从多个维度观察开发者生产力，而不是用单一活动指标代理。

AI 场景中可以定期询问：

- 开发者是否更容易理解陌生模块，还是更依赖无法验证的摘要？
- Reviewer 是否收到更完整证据，还是面对更多、更大的 PR？
- 值班人员是否更快找到根因，还是日志中增加了不可解释的 Agent 动作？
- 新人是否能靠项目规则独立完成低风险改动？
- 人是否能随时停止、接管和复盘 Agent 任务？

调查要与系统数据结合，避免只依赖“感觉更快”或“感觉被打扰”。

#### 25.5 Agent 专属过程指标：观察系统，不评价个人

| 维度 | 建议记录 | 它能帮助判断什么 |
| --- | --- | --- |
| 任务输入 | 任务类型、风险、验收字段完整度、上下文来源 | 失败是否来自任务定义不足 |
| 执行 | 模型/Agent 版本、轮次、工具调用、token、耗时、重试和停止原因 | 成本、死循环、工具或提示回退 |
| 改动 | 文件、行数、模块、依赖、生成/删除比例、范围变化 | PR 是否膨胀，是否偏离授权范围 |
| 验证 | Manifest、实际运行检查、跳过原因、baseline/candidate 结果 | “通过”是否有完整证据 |
| 审查 | AI/人发现、采纳、误报、返工轮次和首响 | Review 能力与认知负担 |
| 权限 | 触发者、凭据范围、网络、写操作、人工批准 | 是否发生越权或政策绕过 |
| 结果 | 合并、回滚、缺陷、用户结果和回归 Case | 局部成功是否转化为稳定交付 |

过程指标必须能关联同一个 `task_id / run_id / commit_sha / pr_id / deployment_id`。否则 Agent 日志、CI 和线上结果各自成岛，无法回答“这次自动改动最终造成了什么”。

### 26. 怎样做可信的前后对比

比较 AI 流程前后，最常见的错误是直接拿两个时期的平均开发时间。任务难度、人员、仓库活跃度和发布节奏可能同时变化。

一个轻量但更可信的设计可以是：

1. 选择同一仓库中可重复、边界明确的任务类型，例如依赖更新、普通 Bug 或测试补全；
2. 为任务记录风险、模块、规模和历史熟悉度；
3. 比较相近任务，或让同类任务在不同流程中随机/交替分配；
4. 同时观察 lead time、返工、质量、人工投入和计算成本；
5. 保留失败任务，不只统计 Agent 成功交付的样本；
6. 至少跨越多个发布周期，避免一次新鲜感或短期学习效应；
7. 将结果描述为当前仓库和流程中的效应，不外推为普遍比例。

对于并行 Agent，单个任务的墙钟时间可能很长但人类只投入十分钟，也可能 Agent 很快但人持续监督。建议同时统计：

- wall-clock time；
- active human time；
- compute/token cost；
- Reviewer time；
- 到可靠部署的总时间。

### 27. 指标必须连接动作，否则只是仪表盘

每项指标都应预先对应一个可能动作：

| 观察到的变化 | 先检查什么 | 可能采取的动作 |
| --- | --- | --- |
| 首个候选变快，Review 等待变慢 | PR 到达率、大小、Owner 负载 | 限制并行任务、缩小 PR、改善摘要与证据、增加轮值 |
| CI 重跑次数上升 | flaky、环境、选择器、Agent 是否先本地验证 | 修复 flaky、预构建环境、强制 preflight |
| token/轮次上升但结果不变 | 工具失败、上下文重复、停止条件、模型变化 | 修复工具、压缩上下文、增加预算门禁和回归 |
| Change fail rate 上升 | 缺陷类型、未运行测试、错误基线 | 增加回归、扩大高风险 Gate、减少自治范围 |
| AI Review 评论多但采纳少 | 规则是否明确、误报集中点 | 把确定规则静态化、收窄 Review 指令 |
| Agent 越权或接触多余信息 | 触发、token、MCP、网络和 safe output | 降权、拆读写任务、增加 allowlist 和审批 |

如果团队看到指标异常却不知道谁应该采取什么动作，这个指标还没有进入治理闭环。

---

## 团队如何逐步建设 AI 开发流程

### 28. 不要从“全自动开发”开始

AI 开发能力适合按可验证性逐步放权。下面的等级不是行业标准，而是本文根据前述公开实践归纳的建设顺序。

| 等级 | AI 可以做什么 | 系统必须具备什么 | 人保留什么决定 | 升级条件 |
| --- | --- | --- | --- | --- |
| L0 辅助 | 解释、补全、生成局部代码；人亲自操作 | 基本 Git、测试和 Review | 所有操作与提交 | 能稳定验证 AI 输出，不把生成视为正确 |
| L1 受控实现 | Agent 在分支/worktree 完成一项任务并运行检查 | 仓库规则、任务模板、统一命令、CI | 澄清范围、审查和合并 | 候选改动可复盘，失败能区分实现与环境 |
| L2 独立初审 | 第二个 Agent 审查 Diff、代码和规则 | Review 规则、结构化发现、确定性检查 | 判断有效发现和风险接受 | 误报可测，重大问题仍由 Owner 负责 |
| L3 事件驱动维护 | 定时/事件触发调查、分类、报告或候选 PR | 受信触发、沙箱、读写分离、预算和审计 | 批准写操作和合并 | 任务边界窄，判定器稳定，噪声可控 |
| L4 受限自动修复 | 在白名单路径对一种问题自动修改并提交分支 | baseline/candidate、全量门禁、回滚、最小权限 | 定义政策、处理例外、批准高风险 | 大量历史运行证明失败代价可控 |

关键不是达到最高等级。很多产品功能变化长期停留在 L1 或 L2 是合理的；格式修复、依赖锁文件更新和确定性测试优化可能进入 L3/L4。自治等级应由**任务的可计算性和失败代价**决定，而不是由模型能力宣传决定。

### 29. 建设顺序：先让现有流程可执行，再让 Agent 进入

#### 第一步：建立仓库事实入口

至少让新人和 Agent 能快速找到：

- 项目目标与不做什么；
- 当前架构和责任边界；
- 本地启动、测试、文档和发布命令；
- 权威协议、已接受决策和废弃信息；
- 各目录 Owner 与升级路径；
- 最近一次工作状态和已知问题。

这里的目标不是写一部百科全书，而是减少“每个 Agent 都重新猜一次”。过期文档比没有文档更危险，因此每个入口要有 Owner、适用范围和更新触发条件。

#### 第二步：统一开发与 CI 的执行入口

把常用操作收口成 `make test`、`just ci` 或仓库脚本，确保人、Agent 和 CI 调用同一逻辑。本机可跑快速子集，CI 在统一环境复算。

如果开发者用一套命令、Agent 猜一套命令、CI 再用第三套脚本，失败很难复现，Agent 也会浪费轮次探索环境。

#### 第三步：把主分支政策写进平台

至少配置：

- 禁止或严格限制直接推送默认分支；
- Required Gate；
- CODEOWNERS 或关键路径 Reviewer；
- 新 Commit 后旧批准是否失效；
- 外部代码运行时的 Secret 和 token 权限；
- 失败、取消、超时和跳过的聚合语义。

没有这一步，`AGENTS.md` 和开发规范只是提醒，无法阻止误操作。

#### 第四步：形成最小证据模板

每个 PR/MR 至少回答：

```text
问题与目标是什么？
改了哪些行为，明确没改什么？
风险在哪里？
运行了哪些检查，结果和证据链接是什么？
哪些检查没有运行，为什么？
是否涉及文档、协议、迁移、权限或发布？
如果异常，怎样回滚？
```

AI 可以自动填充 Commit、Diff、测试和日志事实；作者负责确认目标、范围和已知限制。不要让 Agent 用大段自然语言掩盖缺失的测试证据。

#### 第五步：按改动选择测试并保留 Manifest

先从目录映射和永久门禁做起，再逐步加入依赖图、显式业务映射和历史失败映射。每次选择都输出 Manifest。测试选择器变化本身视为高风险，需要自己的单元测试、快照和 broad fallback。

#### 第六步：把真实缺陷转成回归

事故、用户 Bug 和 Review 漏洞不能只关闭 Issue。先复现，建立 oracle，验证 baseline 失败和 candidate 通过，再把 Case 连接到相应改动范围。无法自动化时也要保留人工检查单，并明确为什么暂时无法自动判断。

#### 第七步：加入独立 Review Agent

Review Agent 使用不同目标和尽可能独立的上下文：阅读任务、Diff、相邻实现和规则，寻找问题，不直接修复。将确定性发现逐步迁移到 lint、schema 或测试，减少模型重复评论。

#### 第八步：只对窄任务开放事件驱动自治

从只读报告开始，例如 flaky tests 汇总、依赖风险分类、文档漂移候选和性能趋势。观察噪声、成本和权限后，再允许创建 Issue、评论或候选 PR。写入经 safe output 或等价验证层执行，不让 Agent 直接持有广泛 token。

### 30. 一个完整例子：修复“重试后重复发送通知”

下面是虚构的教学案例，用来展示前述机制怎样串起来，不代表某个真实仓库实现。

#### 30.1 问题进入系统

线上监控和用户反馈显示：任务执行超时后自动重试，部分用户收到两条完成通知。Issue 记录：

- 复现条件：第一次发送成功但响应丢失，Worker 判定失败并重试；
- 用户影响：重复通知，可能触发两次后续动作；
- 目标：同一任务完成事件最多产生一次业务通知；
- 非目标：本次不重写整个消息系统；
- 风险：幂等键、数据库迁移、重试兼容和历史任务；
- 验收：baseline 可稳定产生两条，candidate 只产生一条；正常单次发送不受影响。

产品 Owner 确认优先级，消息模块 Owner 确认幂等责任应位于服务端通知写入边界。

#### 30.2 Agent 调查并形成证据图

实现 Agent 在独立 worktree 中读取 Issue、架构文档、消息目录 `AGENTS.md` 和相关历史。搜索得到：

```text
Worker 重试
  → NotificationService.send(task_id, payload)
  → 数据库 insert notification
  → outbox publisher
  → 手机与邮件消费者
```

已有测试只覆盖单次发送；UI 有临时去重，但邮件消费者没有。Agent 将潜在改动范围和证据报告给人：若修改数据库唯一约束，需要迁移和历史数据处理；若只在 Worker 记忆“已发送”，进程重启会丢失状态。

技术 Owner 选择以 `(task_id, notification_kind)` 为幂等键，并要求兼容历史重复数据。这个决定改变持久化契约，不能由 Agent 静默决定。

#### 30.3 先建立能失败的 Case

Agent 增加集成测试：模拟数据库提交成功但 Worker 未收到确认，随后重试。oracle 不是匹配日志，而是查询 outbox 和业务通知状态：

```text
baseline:
  notification rows = 2
  outbox events = 2
  expected defect reproduced = true

candidate:
  notification rows = 1
  outbox events = 1
  single delivery behavior = pass
```

再增加三个边界：不同任务允许各发一次、同任务不同通知类型允许各发一次、并发重试仍只产生一条。

#### 30.4 实现候选修复

Agent 修改数据模型和写入逻辑，处理唯一冲突为幂等成功，并增加迁移。它没有删除 UI 去重，因为旧客户端和历史数据仍可能需要防御；是否后续删除另开任务。

这体现了“修责任源头”与“保留纵深防御”可以同时成立，而不是看到上游修复后就机械删除所有下游保护。

#### 30.5 CI 怎样选择检查

Diff 触发：

- 数据库 schema/迁移检查；
- NotificationService 单元与集成测试；
- outbox 消费者契约测试；
- 并发/重试历史 Case；
- 安全和依赖永久门禁；
- 迁移文件变化触发 broad database suite。

Manifest 同时说明 UI、语音和无关服务测试未运行。聚合 Gate 判断所有必需检查通过，且没有非法 skipped。

#### 30.6 Review Agent 和人分别看什么

Review Agent 找出：迁移在历史重复行存在时会失败；Agent 提出候选修复并增加迁移 fixture。人工 Reviewer 重点确认：

- 幂等键是否符合业务语义；
- 历史数据保留策略；
- 唯一冲突是否会掩盖 payload 不一致；
- 部署时新旧 Worker 并存是否兼容；
- 回滚迁移会发生什么。

这些是责任和风险取舍，不能仅由“测试绿了”决定。

#### 30.7 合并、发布和回归闭环

PR 通过 Owner、Required Gate 和迁移审批后合并。发布采用小流量，监控重复通知率、唯一冲突和发送失败。确认稳定后扩大流量。原始 Issue、baseline/candidate 证据、回归测试 ID、Commit、PR 和部署记录保持关联。

若半年后有人重构 outbox，影响选择器会自动运行这条 Case。新的改动若再次产生两条通知，Required Gate 阻止合并。这才叫“问题只需要付一次完整认知成本”。

### 31. 常见失败方式，以及它们为什么失败

| 做法 | 看起来的好处 | 实际问题 | 更稳妥的做法 |
| --- | --- | --- | --- |
| 给 Agent 一个模糊 Issue，让它自己决定一切 | 输入很短 | 模型会把缺失决策藏在实现里 | 明确目标、范围、验收、风险和权威；重大歧义暂停 |
| 一个 Agent 写代码、改测试、更新基线并宣布成功 | 全程自动 | 被考核者同时出题、答题和判卷 | 独立 oracle、Review Agent、CI 和人工授权 |
| CI 只展示一个绿勾，不展示选择结果 | 页面简洁 | 无法区分通过与未运行 | 保存 manifest、跳过原因和稳定聚合 Gate |
| 所有 PR 一律跑全量 | 看似最安全 | 反馈太慢、资源拥堵并诱发绕过 | 相关快速检查 + 永久门禁 + 不确定时扩大 + 主分支全量 |
| 只跑 Agent 自己挑的测试 | 速度快 | 容易选择证明自身实现的窄测试 | 由独立选择器按 Diff、依赖、风险和历史推导 |
| 把安全规则只写进 Prompt | 实现简单 | 模型受注入或误解时规则失效 | 用 token、沙箱、allowlist、分支保护和审批执行 |
| 让 Agent 在含 Secrets 的环境执行外部 PR 代码 | 方便验证 | 不可信代码可能窃取凭据 | 隔离不可信运行；读写分离；避免危险事件组合 |
| 用代码量和 PR 数评价 AI 或个人 | 数据易取 | 奖励冗余和低价值活动 | 看 lead time、质量、返工、人工投入和用户结果 |
| 生成更多 PR 来提高“吞吐” | 表面活跃 | Review 和 CI 队列膨胀 | 对瓶颈限流，控制 WIP 和 PR 大小 |
| 事故修完只加一条特殊 if | Diff 最小 | 根因未修复，相邻消费者仍错误 | 建证据图，修责任源头，留下可泛化回归 |
| 文档写了流程，但平台允许直接绕过 | 变化成本低 | 规则在压力下失效且无审计 | 把确定规则落到 Required Gate 和分支保护 |

### 32. 一项 AI 开发流程是否成熟，可以问这 20 个问题

#### 目标与责任

1. 谁决定这项工作值得做，谁能改变范围？
2. 高风险变化的模块 Owner、安全 Owner 和发布 Owner 是否明确？
3. Agent 遇到权威文档冲突时，知道应暂停并找谁吗？

#### 上下文与实现

4. 新人和 Agent 能否在十分钟内找到架构、命令、规则和最新状态？
5. 根规则和目录规则是否各自只包含适用作用域的信息？
6. Agent 是否在独立分支/worktree/沙箱中工作？
7. 任务范围扩张是否需要新的授权？

#### 验证与审查

8. Bug Case 能否证明旧版本失败、新版本通过？
9. 测试由独立规则选择，还是只由实现者或 Agent 自选？
10. 能否看到实际运行、跳过和 fallback 的 Manifest？
11. Required Gate 是否把 failed、cancelled、timeout 和非法 skipped 都视为失败？
12. AI Review、确定性检查和人工 Review 的职责是否不同？
13. 新 Commit 是否使需要重审的旧批准失效？

#### 权限与供应链

14. 不可信 Issue、PR、网页和工具输出能否直接触发写操作？
15. Agent 是否持有超出当前任务所需的 token、Secrets、网络或 MCP？
16. 高权限写入是否由独立任务对结构化请求重新验证？
17. Agent 能否批准或合并自己产生的改动？

#### 反馈与演进

18. Agent 任务、Commit、PR、CI、部署和事故能否用 ID 关联？
19. 缺陷修复后是否会留下自动回归并进入影响映射？
20. 团队是否知道当前瓶颈在决策、实现、CI、Review、发布还是恢复，并据此调整 WIP？

如果多数问题的答案依赖“大家应该会记得”，流程仍主要靠个人经验；如果答案能从仓库、平台规则和证据记录中直接查到，才具备多人和多 Agent 快速协作的基础。

## 结语

Git 让变化可保存和比较，PR/MR 让变化可讨论，CI 让明确规则可重复执行，分支保护让合并政策不可静默绕过，线上观测让未知问题进入下一轮改进。

AI 增加了调查、生成和比较的供给，但没有消除决定、证明和承担责任的需要。成熟方向不是让一个 Agent 模拟所有角色，而是把工作拆成相互制衡的部分：

```text
人定义价值与风险
Agent 调查、实现和初审
工程系统执行可重复规则与权限边界
独立 Reviewer 和 Owner 授权高风险变化
真实问题转成长期回归
```

当每次变化都能说明为什么做、改了什么、如何证明、谁批准、出了问题怎样恢复，AI 才会把团队已有能力放大成更快、更稳定的交付；否则，它只会更快地放大模糊需求、薄弱测试和拥塞的审核流程。

---

## 附录 A：常用概念

| 概念 | 简明解释 |
| --- | --- |
| Branch | 从某个 Git 版本分出的独立变化线。 |
| Worktree | 同一仓库同时检出多个分支的独立目录，便于并行和 baseline/candidate 隔离。 |
| Commit | Git 中一组带父版本和元数据的文件状态变化。 |
| PR / MR | 请求把一个分支合入另一个分支；GitHub 称 Pull Request，GitLab 称 Merge Request。 |
| CI | 由提交或事件触发，在受控环境中自动执行构建、测试和检查。 |
| Required Check / Gate | 分支保护要求必须通过的状态；Gate 可聚合内部多个检查。 |
| CODEOWNERS | 将路径映射到负责审查的个人或团队。 |
| Baseline / Candidate | 用于对照的已知版本与候选变化版本。 |
| Oracle / Validator | 根据结构化证据判断 Case 成功、失败或无法判定的规则。 |
| Harness failure | 评测环境、Runner、凭据或采集在到达产品判定前失败，不应算产品失败。 |
| Agent | 能读取上下文、规划、调用工具并产生结果的软件执行体；权限由外部系统决定。 |
| `AGENTS.md` | 给 Coding Agent 的仓库或目录级说明，不等于 CI 或安全权限。 |
| Safe output | Agent 提出的结构化动作请求，经独立验证后才由有权限的任务执行。 |
| Prompt injection | 不可信内容试图改变 Agent 原任务或诱导其泄露信息、执行越权动作。 |
| Lead time | 一项变化从开始到交付到生产所需时间。 |
| WIP | Work in Progress，系统中正在进行但尚未完成的工作量。 |

## 附录 B：主要来源与证据边界

### 源码快照

- [OpenClaw `af73dbcc`](https://github.com/openclaw/openclaw/tree/af73dbcc834027e84d8717e17c504020a17e567a)：本文核对其 `AGENTS.md`、`CONTRIBUTING.md`、CI 文档、Mantis 和 Test Performance Agent Workflow。
- [OpenAI Codex `a16863f8`](https://github.com/openai/codex/tree/a16863f8704831d13e041ed7dba2c4a57a2a940b)：本文核对其贡献指南、`AGENTS.md` 和 PR/post-merge CI Workflows。

### 官方产品与安全文档

- OpenAI：[Code Review](https://learn.chatgpt.com/docs/code-review)、[`AGENTS.md`](https://learn.chatgpt.com/docs/agent-configuration/agents-md)、[GitHub Code Review 用例](https://learn.chatgpt.com/codex/use-cases/github-code-reviews)。
- GitHub Copilot cloud agent：[Risks and mitigations](https://docs.github.com/en/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/risks-and-mitigations)、[Custom guardrails](https://docs.github.com/en/enterprise-cloud@latest/copilot/tutorials/cloud-agent/build-guardrails)。
- GitHub Agentic Workflows：[概览](https://github.github.com/gh-aw/)、[架构](https://github.github.com/gh-aw/introduction/architecture/)、[权限](https://github.github.com/gh-aw/reference/permissions/)、[Safe outputs](https://github.github.com/gh-aw/reference/safe-outputs/)。
- Anthropic Claude Code Action：[Security](https://github.com/anthropics/claude-code-action/blob/main/docs/security.md)。

### 研发效能研究

- DORA：[2025 报告](https://dora.dev/research/2025/dora-report/)、[五项软件交付指标](https://dora.dev/guides/dora-metrics/)、[Value stream management](https://dora.dev/guides/value-stream-management/)。
- Microsoft Research：[SPACE of Developer Productivity](https://www.microsoft.com/en-us/research/publication/the-space-of-developer-productivity-theres-more-to-it-than-you-think/)。
- GitHub：[2022 Copilot 固定任务实验](https://github.blog/news-insights/research/research-quantifying-github-copilots-impact-on-developer-productivity-and-happiness/)。
- METR：[Early-2025 experienced OSS developer study](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/)、[2026 uplift update](https://metr.org/blog/2026-02-24-uplift-update/)。

本文对源码中实际存在的规则标注了固定 Commit；产品行为以链接的官方文档为准；跨项目共同模式、建设等级和示例流程是本文归纳，不是上述项目共同发布的标准。公开文档不能证明某家公司内部全部研发流程，本文不作这种外推。
