wuyang6
69 KiB
title, summary, date, updated, topic, tags, kind, status, visibility, canonicalUrl, sourceRepo, preview
| title | summary | date | updated | topic | tags | kind | status | visibility | canonicalUrl | sourceRepo | preview | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Git 协作与 AI 开发：变更、验证与授权 | 从 Git 的协作机制出发，分析 AI Coding Agent 如何进入任务、实现、审查与仓库治理，并用五个公开项目和研发效能研究说明可靠提效所需的验证、权限与责任边界。 | 2026-08-10 | 2026-08-10 | agent-systems |
|
article | published | public | https://blog.k1412.top/articles/git-collaboration-ai-development/ | https://git.k1412.top/wuyang/research-blog | /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 的公开实现。重点不是产品介绍，而是回答四个问题：
- 一项改动由谁决定，怎样进入主分支？
- 团队如何证明它做对了，而不只是“代码能跑”？
- AI 可以接管哪些工作，哪些权力不能交给同一个 Agent？
- 怎样判断 AI 真的提高了研发效率，而不是只增加代码和 PR？
公开资料核对日期为 2026 年 8 月 10 日。源码分析固定在 OpenClaw af73dbcc 与 OpenAI Codex a16863f8；产品文档会持续变化，文中把“源码已验证”“官方产品文档”和“本文归纳”分开表述。
软件变更需要五类控制
一套可靠的开发流程，可以压缩成下面五句话：
- 先定义变化。 说明问题、目标、范围、风险和验收标准，再开始实现。
- 把实现隔离。 每项工作在独立分支或 worktree 中完成，不直接改主分支。
- 用多种证据证明。 Diff、测试、静态检查、运行证据和审查意见解决不同问题，任何单一信号都不等于“正确”。
- 用系统执行门禁。 必需检查、Owner 审批和合并权限由平台强制执行，不能只写在文档里。
- 把缺陷变成资产。 真实问题修复后留下能在旧版本失败、在新版本通过的回归测试，避免同类错误再次进入主分支。
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、分支保护和发布系统，建立一条受控的变化链路。
2. 把改动理解成状态迁移
新人经常把开发理解为“接到任务 → 写代码 → 提交”。团队真正管理的是一连串状态迁移，每次迁移都需要新的证据和相应的授权。
| 从哪里到哪里 | 要回答的问题 | 最小证据 | 谁通常有权决定 |
|---|---|---|---|
| 问题 → 接受工作 | 值不值得做，现在做吗？ | 用户影响、复现或机会、目标和优先级 | 产品负责人或项目 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 仍有三个限制：
- 仓库只会检查 CI 配置中写到的内容；
- 测试和工作流本身也可能被错误修改；
- 来自外部 PR 的代码可能是不可信输入，不能随意接触主仓库密钥。
分支保护：执行合并政策
分支保护把以下要求变成 Git 平台的强制规则：
- 禁止直接推送默认分支；
- 必需状态全部成功；
- 必须获得指定数量或指定 Owner 的批准；
- 新 Commit 到来后旧批准是否失效；
- 是否允许强推、删除或管理员绕过。
因此，一套规则只有写进 CI 和分支保护后，才从“开发建议”升级成“不能静默绕过的门禁”。文档负责解释为什么，代码和平台负责执行已经确定的部分。
一项改动如何得到证明
6. “CI 绿了”不是完整结论
软件正确性不是一个布尔属性，而是一组不同问题：
| 证据 | 能回答什么 | 典型盲区 |
|---|---|---|
| 编译、类型检查 | 语法、类型和依赖能否成立 | 产品行为是否正确 |
| lint、静态规则 | 是否违反明确的编码、安全或架构规则 | 运行时组合行为 |
| 单元测试 | 单个函数或模块在给定输入下是否满足断言 | 模块接线、真实依赖和环境 |
| 集成/契约测试 | 多组件交互、API/schema、数据库和依赖契约是否成立 | 完整用户路径和真实平台差异 |
| 端到端 Case | 从入口到结果的关键路径是否成立 | 未覆盖场景、环境稳定性和判定器错误 |
| 性能基线 | 延迟、资源、调用次数是否异常 | 功能是否正确、噪声来源 |
| 安全扫描 | 已知漏洞模式、密钥和依赖风险 | 业务授权和未知攻击方式 |
| AI Review | 大范围阅读、语义冲突和可疑遗漏 | 稳定复现、最终责任和确定性保证 |
| 人工 Review | 目标、方案、维护性和风险是否合理 | 代替机器执行所有重复检查 |
| 线上观测 | 真实负载下是否出现未知问题 | 发布前阻止问题 |
真正的合并结论是：“对本次风险而言，必须获得的证据已经齐全且通过。”这就是门禁策略的含义。
7. 为什么不能每次都跑全量测试
大型仓库的完整检查可能持续数小时，并占用大量 Runner。每次都跑全量会产生三个后果：反馈慢、队列拥堵、开发者倾向绕过检查。只跑开发者记得的几个测试又会漏掉间接影响。
所以成熟 CI 通常在两者之间做影响分析和测试选择。
第一版选择器通常不需要机器学习，可以按以下顺序工作：
- 读取 Diff。 区分新增、修改、删除和重命名；删除和公共入口变化通常更难安全缩小范围。
- 目录映射。 例如
web/变化触发前端检查，proto/变化触发生成物和兼容性检查。 - 依赖图。 找到直接依赖被改模块的构建目标和测试。
- 相邻测试。 源文件对应的同目录测试、集成套件和消费者测试。
- 显式业务映射。 权限、认证、发布、公共协议等风险不能只靠 import graph 推导；无论改动在哪，都追加永久门禁。
- 历史失败映射。 某类改动曾经让特定路径回退，就把对应回归 Case 固定加入。
- 生成 Manifest。 写明选了什么、跳过什么、依据是什么。
- 不确定时扩大。 公共契约、测试选择器自身、删除/重命名、依赖解析失败或影响面过大时，回退到模块全量或完整套件。
选择器本身也需要测试，因为“测试没有运行”比“测试运行失败”更隐蔽。最终 Required Gate 应同时判断：
- 选中的检查是否通过；
- 必需检查是否都被选择；
- 跳过是否来自 Manifest 的合法决策；
- failed、cancelled、timed out 和非法 skipped 是否都被正确视为失败。
8. 统一 Required Gate 为什么重要
分支保护如果直接绑定几十个 Job 名称，会很难演进：矩阵变化、任务改名和条件跳过都可能造成误判。更稳妥的结构是让内部 Job 自由拆分，最后只由一个聚合 Job 给出稳定状态。
影响分析 → 选择检查 A / B / C
↓
A 成功，B 成功，C 失败
↓
required = 失败，并列出 C
聚合任务必须使用“无论上游成功还是失败都执行”的语义。否则上游失败后，聚合任务可能被平台标成 skipped，而分支保护看不到明确失败。OpenAI Codex 的 blocking-ci.yml 和 OpenClaw 的 openclaw/ci-gate 都使用了稳定聚合入口。
9. 把一次缺陷变成长期资产
“修复完成”不等于“这个问题以后不会回来”。要形成长期保护，至少经历六步：
- 复现。 在旧版本或已知错误版本上看到预期失败。
- 定义判定器。 明确怎样才算这个问题发生，而不是只看某条日志是否出现。
- 修复责任源头。 找到拥有错误状态或规则的模块，避免只在下游打补丁。
- 候选版本通过。 同一 Case 在新版本上满足预期。
- 覆盖同类变体。 防止测试只匹配一个用户输入、一个 ID 或一句固定文案。
- 绑定未来改动。 选择器能够在相关代码变化时自动运行这条 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 执行真实链路。稳妥顺序是：
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 的上下文通常来自四层：
- 全局工作约定。 例如通用安全要求、提交偏好和工具使用规则。
- 仓库级规则。 项目构建、测试、文档和架构入口。
- 目录级规则。 某个服务、UI、协议或数据库模块的特殊要求。
- 任务期证据。 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 评论、代码、网页和工具结果。这些内容可能包含错误说明，也可能包含提示注入。安全设计不能假设模型总能识别恶意文本。
一条成熟的权限链通常包含：
- 限制触发者。 高权限任务只允许有写权限的成员、受信 Bot 或明确事件触发。
- 隔离运行。 使用临时容器、云环境或 worktree，不直接在生产机器和主分支工作。
- 最小读取。 只提供完成任务所需仓库、网络和 MCP；不默认挂载所有内部系统。
- Agent 不持有写凭据。 Agent 先生成补丁或结构化请求。
- 确定性验证输出。 检查 schema、允许操作、目标仓库、数量、补丁大小、路径和威胁信号。
- 独立写入任务。 只有通过验证的请求，才使用短期、最小权限凭据写入分支、Issue 或评论。
- 分支保护继续有效。 Agent 产生的 PR 仍需 CI、Owner 和批准。
- 保留审计记录。 保存触发者、输入、Agent 运行、Commit、检查和授权动作。
这叫职责分离：即使 Agent 被误导，它能直接造成的影响仍受沙箱和权限限制；即使它生成恶意请求，独立验证器仍可拒绝；即使它成功创建 PR，也不能自行批准和合并。
15. 人、AI 和工程系统的职责不是按职位切分
| 环节 | AI 擅长 | 工程系统擅长 | 人必须承担的部分 |
|---|---|---|---|
| 需求 | 汇总反馈、搜索证据、提出候选方案 | Issue 模板、路线图和决策记录 | 决定价值、优先级和不做什么 |
| 调查 | 搜索调用关系、相邻实现、历史和依赖 | 代码索引、依赖图、日志平台 | 判断哪些证据足够改变方向 |
| 实现 | 编码、重构、补测试和文档 | 分支/worktree、文件和工具权限 | 处理关键歧义和批准范围变化 |
| 验证 | 生成测试、分析失败、提出影响范围 | 编译、测试、schema、扫描和性能阈值 | 确认验收是否代表真实需求 |
| 审查 | 进行大范围第一轮 Review | Diff、CODEOWNERS、审计日志 | 评估维护成本、产品和安全风险 |
| 合并 | 准备 PR 和证据 | Required Gate、分支保护和合并队列 | 接受高风险改动与例外责任 |
| 线上 | 汇总日志、关联变化、提出修复 | 监控、回滚、事故和回归系统 | 决定处置、发布和用户沟通 |
一句话概括：AI 处理大量阅读、生成和比较；工程系统执行可重复规则；人负责意图、取舍和责任。
五个公开项目如何把 AI 放进 Git 流程
这一部分不比较模型“谁更聪明”，而是比较工程控制面：任务从哪里来、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，不是对未来版本的承诺。
16.1 接受 AI 贡献，但不降低证据要求
它的 CONTRIBUTING.md 明确允许 AI/vibe-coded PR，同时要求贡献者披露 AI 使用情况、说明测试证据并完成自动审查。这种政策的重点是：作者可以是人，也可以大量借助 AI；合并条件不因此改变。
这比“禁止 AI 代码”和“默认相信 AI 代码”都更可执行，因为仓库真正能控制的是改动和证据，无法可靠判断每一行代码由谁键入。
16.2 Repair Doctrine 先画改动证据图，再决定改哪里
OpenClaw 根目录 AGENTS.md 的 Repair Doctrine 要求修复前建立一张简化证据图：
用户可见症状
↓
最先出现错误状态的位置
↓
拥有这个状态或规则的模块
↓
读取该状态的相邻功能
↓
覆盖这些行为的已有测试
为什么这对 Agent 特别重要？因为模型看到一个失败断言后，很容易在断言附近增加分支，使当前 Case 通过，却没有修复产生错误状态的上游。
举一个抽象例子：消息列表重复显示一条回复。最小 Diff 可能是在 UI 中去重；责任源头却可能是重试后服务端重复提交。如果只改 UI：
- 其他客户端仍会重复；
- 统计和通知仍会按两条消息计算；
- 数据库继续积累错误状态；
- 原本应幂等的服务责任被掩盖。
证据图要求实现者同时检查生产代码、直接消费者、相邻功能和已有测试，再把修改放到拥有责任的边界。它不是要求每次遍历整个仓库，而是防止“只围着失败文件打补丁”。
16.3 测试范围由改动影响推导，不由 Agent 随口决定
OpenClaw 的 docs/ci.md 描述了 PR preflight：先根据改动生成检查清单，再运行目标检查。选择依据包括：
- 文件所在区域；
- 测试与源文件的相邻关系；
- import/dependency graph；
- 显式维护的路径映射；
- 无法可靠缩小范围时的 broad fallback。
同时，安全检查属于永久门禁，不因为“这次看起来只改文档或 UI”就完全交给模型判断是否需要。主分支再运行更广的套件，用快速 PR 反馈与完整覆盖换取平衡。
preflight manifest 很重要：它让团队看到“没跑哪些测试，以及为什么没跑”。如果只展示绿勾，人们无法区分“测试通过”和“测试根本没被选择”。
16.4 openclaw/ci-gate 把复杂流水线收口成一个合并结论
内部任务可以并行、按条件跳过或采用矩阵，但最终 openclaw/ci-gate 会汇总结果，并检查 PR 证据是否齐全。分支保护绑定这个稳定名称，不必了解每个内部 Job 的动态变化。
这是一种两层设计：
执行层：尽量快地选择、并行和扩展检查
政策层：用一个稳定 Gate 判断是否满足合并要求
前者可以经常优化，后者保持对分支保护的稳定接口。
16.5 Mantis 用已知错误版本证明“测试真的能抓住问题”
OpenClaw 的 Mantis 将修复验证拆成两个隔离 worktree：
- baseline：包含已知问题的版本；
- candidate：包含候选修复的版本。
同一个 typed oracle 分别执行。有效证据不是“candidate 通过”，而是：
baseline 触发了预期缺陷
candidate 不再触发缺陷并满足正向行为
harness 本身没有在到达判定前失败
这样可以发现一种常见假修复：测试从未真正到达错误路径，所以两个版本都通过。Mantis 还输出结构化比较和证据文件，使 Reviewer 能复盘结论，而不是只相信 Agent 的摘要。
16.6 Test Performance Agent 展示了自动写入应该多么克制
OpenClaw 的 test-performance-agent.yml 是少见的高自治示例，但它并不是“把整个仓库交给 Agent”：
- 只从受信任且成功的主分支运行，也可按日触发；
- 先运行完整 baseline；
- Agent 在受限工作区中优化测试性能；
- 禁止新增、删除、重命名和未跟踪文件；
- 只允许修改明确路径；
- 修改后再次运行完整报告和仓库检查；
- 测试数量不能减少；
- 只有全部门禁通过，自动化步骤才提交并推送结果。
这揭示了一个重要原则：越接近自动写入，任务目标越要单一，修改面越要窄，判定器越要确定。 “让 Agent 自主完成任意 Issue 并直接提交主分支”几乎没有同等强度的可计算约束，因此不能照搬这种自治等级。
17. OpenAI Codex 仓库：快速 PR 检查与主分支完整验证分层
本节基于 OpenAI Codex 固定源码快照 a16863f8。它展示的不是 Codex 产品全部能力，而是这个大型 Rust 仓库怎样管理贡献和 CI。
17.1 先就问题和方案达成一致，再投入实现
docs/contributing.md 对外部贡献采取邀请方式，并强调先讨论 Issue 和方案。Bug 修复应提供能够在修复前失败、修复后通过的测试；Commit 保持原子性，维护者审核后通常 squash merge。
这并不是认为代码稀缺，而是认为维护承诺稀缺。AI 将实现成本压低后，团队更需要先判断：
- 这个行为是不是项目愿意长期支持的；
- 方案是否符合已有架构方向；
- 新配置、API 和依赖是否增加长期表面积；
- 谁会在作者离开后继续维护。
17.2 AGENTS.md 把局部测试纪律放到对应目录
Codex 仓库根和子目录中的 AGENTS.md 会给 Agent 精确命令和模块规则。例如，Agent 逻辑变化必须增加集成测试，UI 变化需要更新快照。这比把所有规则堆在根目录更有效：进入具体目录工作的 Agent 只加载与当前作用域更相关的约束。
OpenAI 的 AGENTS.md 官方文档 说明了发现顺序：从项目根目录到当前工作目录加载规则，越接近工作目录的文件越具体。这里必须再次区分：AGENTS.md 是上下文注入，不是权限系统；规则中的测试命令仍应由 CI 重跑。
17.3 PR 优先获得相关快速反馈，主分支承担更广验证
rust-ci.yml 先检测改动区域，再安排相关构建和测试；blocking-ci.yml 汇总 Bazel、blob size、依赖许可与漏洞、拼写、仓库检查、Rust CI 和 SDK 检查，最后由一个始终执行的 required Job 决定合并状态。
进入主分支后，postmerge-ci.yml 再执行更完整的 Rust 和 V8 canary 验证。
这是一种常见分层：
| 时点 | 目标 | 策略 |
|---|---|---|
| PR 内 | 尽快告诉作者“当前候选能否合并” | 相关检查、永久风险门禁、稳定聚合结论 |
| 合入主分支后 | 发现跨改动组合或罕见平台问题 | 更全矩阵、canary、完整套件 |
| 发布前/后 | 证明产物和真实环境可用 | 产物验证、渐进发布、监控与回滚 |
后置检查不是降低 PR 质量，而是承认低概率、跨平台和组合问题不一定适合阻塞每个开发者数小时。前提是主分支异常能被快速发现、停止发布并明确修复。
17.4 Codex Review 是额外审查者，不是合并授权者
OpenAI 官方 Code Review 支持审查相对基线、未提交改动、单个 Commit 或自定义范围，输出问题但不修改工作树；GitHub 集成可自动审查或通过 @codex review 按需触发，发现问题后再启动独立修复任务。仓库还能用 AGENTS.md 中的 Code Review Rules 定义作用域规则。
这种分离减少了实现 Agent 自证的偏差：
实现 Agent：目标是完成任务
Review Agent：目标是寻找候选缺陷
CI：重复执行确定性检查
人类 Reviewer：决定风险和维护责任是否可接受
四者仍可能共享盲区，所以重要改动不能只依靠“第二个模型看过了”。
18. GitHub Copilot cloud agent：Agent 创建候选分支，人保留合并权
Copilot cloud agent 处理 Issue 或任务后，在云环境中修改代码并创建 PR。其公开安全模型值得注意，因为它没有把“能写代码”等同于“能改变默认分支”。根据 GitHub 的风险与缓解措施：
- 默认只有拥有仓库写权限的用户可以触发；
- Agent 在单独的
copilot/分支或指定 PR 分支工作； - 分支保护和 Required Checks 继续生效；
- Agent 不能把自己的 PR 标记 Ready、批准或合并；
- 其触发的 Actions 默认需要有写权限用户批准，触发任务的人不能自己批准该次运行；
- Commit 和会话日志保留身份与过程证据；
- GitHub 会过滤提示中的隐藏字符，但这只是防护的一层。
这里存在两个不同的“人”：任务发起人允许 Agent 开始工作；另一个有资格的人批准高风险 Actions 或 Review。这样避免同一个人借 Agent 绕过原本需要独立批准的规则。
仓库还可以增加自定义 guardrails，例如阻止特定路径、验证生成文件、限制依赖或强制额外测试。Guardrail 应执行仓库确定的政策，而不是把一个模糊问题再次交给模型自由判断。
19. GitHub Agentic Workflows：最清楚的“读与写分离”范式
GitHub Agentic Workflows 允许用自然语言描述定时或事件触发的维护任务，例如总结 Issue、分类反馈、调查测试失败或生成候选修复。它与一般 GitHub Actions 最大的差别，不是多了 LLM，而是为不可信上下文设计了一套编译和运行边界。
19.1 Agent 默认只读且看不到 Secrets
Agent 在隔离环境中读取事件和仓库内容，默认没有仓库写权限，也不直接拿到长期 Secrets。网络访问和工具受到沙箱或防火墙约束。这样，即使 Issue 评论包含提示注入，模型也无法直接把任意内容写回仓库或泄露所有凭据。
19.2 Agent 只能申请 safe outputs
Agent 不直接调用“创建 Issue”“提交 PR”之类高权限 API，而是生成结构化 safe output，例如：
{
"operation": "create_issue",
"title": "候选标题",
"body": "候选正文",
"labels": ["triage"]
}
运行时先缓存请求，做 schema、数量、允许操作、目标、补丁大小、路径和威胁检测；通过后再由独立、持有短期凭据的 Job 执行。官方 safe outputs 文档 还支持允许列表和最大数量等约束。
这个结构与普通工具调用的本质差异是：Agent 生成的不是已经完成的副作用，而是一份待授权的动作请求。
19.3 Safe output 不是绝对安全
官方文档明确说明，safe outputs 主要降低 Agent 内容引发的风险，不能修复底层 Runner、Actions 配置、依赖供应链或错误权限策略。若独立写入 Job 本身接受任意 shell、拥有过大 token 或使用不安全事件，前面的隔离仍可能被绕过。
因此，一条完整边界需要同时审查：
事件可信度 → Agent 沙箱 → 输出 schema → 政策验证
→ 写入凭据 → GitHub 权限 → 分支保护 → 人工授权
20. Claude Code Action：事件类型本身也是安全边界
Anthropic 的 claude-code-action 安全文档 强调：默认只有有写权限的用户可触发，Bot 默认不能触发；运行使用短期、仓库范围 token；如果任务需要向默认分支提交，推荐创建 PR 供人审查。
它特别提醒谨慎使用 pull_request_target 和 workflow_run。原因不是名称危险，而是这类事件可能在有主仓库权限或 Secrets 的上下文中运行，同时又检出外部贡献者可以控制的代码。一个典型危险组合是：
外部 PR 控制工作流要执行的脚本
+ pull_request_target 提供主仓库权限或 Secret
+ Workflow 检出并执行外部 PR 的 head
= 不可信代码获得受信任权限
防护不能只靠 Prompt 说“不要泄露 Secret”，而应避免把不可信代码与高权限运行上下文放在同一 Job；需要写操作时，使用最小权限、固定动作和独立审批。
21. 五个案例共同说明了什么
公开实现中没有一个成熟方案把全部权力交给同一个 Agent。它们的共同结构是：
- 用 Issue、任务契约或受信事件定义工作；
- 在独立分支、worktree 或云环境中产生候选改动；
- 让 Agent 读取与目录相关的规则，而不是依赖一个无限长总 Prompt；
- 用确定性检查重新验证模型输出；
- 对测试选择、跳过和失败保留结构化证据；
- 将写操作限制在分支、PR、评论或经过验证的 safe outputs；
- 由独立 Gate、Owner 或人类保留合并和高风险授权。
它们也有明显差异：OpenClaw 更像社区仓库内的 AI 开发纪律与专项自治实验；Codex 展示大型仓库的贡献和 CI 分层；Copilot cloud agent 与 Claude Code Action 是托管 Coding Agent；Agentic Workflows 则是事件驱动自动化框架。把其中一个案例的“自动 Commit”单独截出来，会丢失它前后非常严格的触发、路径和判定限制。
如何判断 AI 是否提高研发效率
22. 先区分局部速度和系统吞吐
AI 最容易加速的是一个人当前正在做的动作：搜索代码、生成样板、写测试、解释失败和准备 PR。团队真正关心的是从需求进入到用户获得可靠变化的总时间。
可以用一个简化价值流理解：
等待决策 → 等待上下文 → 调查与实现 → 等待 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 年公布的受控实验中，95 名专业开发者完成一个固定 JavaScript HTTP server 任务，使用 Copilot 的一组平均快约 55%。这个结论适合说明：在边界明确、可快速验收的编码任务上，补全工具可能显著缩短实现时间。
它不能直接推导“整个研发组织快 55%”，因为实验没有包含长期设计、多人审查、遗留系统、发布和线上维护。
熟悉真实仓库的任务：上下文和验证成本会占主导
METR 在 2025 年发布的早期研究观察 16 名熟悉大型开源仓库的开发者完成 246 个真实任务，早期 2025 工具条件下使用 AI 反而慢 19%。参与者却主观认为自己更快，说明感受、生成速度和完整任务时间可能不同。
METR 随后在 2026 更新中认为更新工具很可能已经改善结果，但指出选择偏差、计时和并行 Agent 使测量更困难：开发者可能把适合 AI 的任务留给实验，把更难任务排除；等待 Agent 时还会并行做其他事。更新数据不足以给出一个稳定、普适的净加速数字。
组织层面：AI 会放大已有系统
DORA 2025 报告把 AI 描述为组织能力的放大器。拥有清晰文档、快速反馈、可靠平台和小批量交付的团队，更容易把生成速度转成稳定吞吐；需求混乱、测试脆弱、审查拥塞的团队，会更快地产生返工和积压。
这三组结论并不矛盾：
固定任务测“做一个明确动作有多快”
真实仓库测“补足上下文并交付一个改动有多快”
组织研究测“整个系统能否吸收更多变化”
24. 不要用代码量、Commit 数和 PR 数评价人
代码行数、Commit 数、PR 数和 Agent 会话数容易收集，却很容易被优化错：
- Agent 把一个简单函数写成更多代码，指标反而更好；
- 团队拆出大量低价值 PR，吞吐看似上升；
- 开发者因为担心指标而减少重构、删除代码和帮助同事；
- 自动生成测试数量上涨，但断言只验证实现细节；
- Review Agent 输出更多评论，不代表发现更多真实问题。
这些数字适合用来解释负载，例如“PR 数翻倍导致 Review 等待升高”，不适合作为个人绩效目标。
25. 一个可用的指标框架：结果、流动、质量、人的体验与治理
指标不是越多越好。先明确要做什么决策，再选择能改变该决策的少量指标。
25.1 交付与稳定性：DORA 五项指标
DORA 指标指南当前列出五项软件交付指标：
| 指标 | 回答什么 | AI 场景中的解释 |
|---|---|---|
| Change lead time | 一项变化从开始到进入生产需要多久 | 编码变快是否真正缩短总周期 |
| Deployment frequency | 团队多频繁向生产交付变化 | 是否能够以更小批次稳定发布 |
| Failed deployment recovery time | 失败发布后恢复服务需要多久 | AI 是否帮助诊断和回滚，而非放大事故 |
| Change fail rate | 部署后需要修复、回滚或处置的比例 | 更快生成是否牺牲正确性 |
| Deployment rework rate | 部署中用于处理非计划返工的比例 | AI 生成的变化是否增加隐藏返工 |
这五项应按服务或价值流观察趋势，不要用来比较不同性质的个人和仓库。
25.2 工作流拆解：等待时间比“AI 思考时间”更重要
对每个 PR/MR 可以记录状态时间戳：
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 框架 包含 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 流程前后，最常见的错误是直接拿两个时期的平均开发时间。任务难度、人员、仓库活跃度和发布节奏可能同时变化。
一个轻量但更可信的设计可以是：
- 选择同一仓库中可重复、边界明确的任务类型，例如依赖更新、普通 Bug 或测试补全；
- 为任务记录风险、模块、规模和历史熟悉度；
- 比较相近任务，或让同类任务在不同流程中随机/交替分配；
- 同时观察 lead time、返工、质量、人工投入和计算成本；
- 保留失败任务，不只统计 Agent 成功交付的样本；
- 至少跨越多个发布周期，避免一次新鲜感或短期学习效应；
- 将结果描述为当前仓库和流程中的效应，不外推为普遍比例。
对于并行 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 至少回答：
问题与目标是什么？
改了哪些行为，明确没改什么？
风险在哪里？
运行了哪些检查，结果和证据链接是什么？
哪些检查没有运行，为什么？
是否涉及文档、协议、迁移、权限或发布？
如果异常，怎样回滚？
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 和相关历史。搜索得到：
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 和业务通知状态：
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 个问题
目标与责任
- 谁决定这项工作值得做，谁能改变范围？
- 高风险变化的模块 Owner、安全 Owner 和发布 Owner 是否明确？
- Agent 遇到权威文档冲突时，知道应暂停并找谁吗？
上下文与实现
- 新人和 Agent 能否在十分钟内找到架构、命令、规则和最新状态？
- 根规则和目录规则是否各自只包含适用作用域的信息？
- Agent 是否在独立分支/worktree/沙箱中工作？
- 任务范围扩张是否需要新的授权？
验证与审查
- Bug Case 能否证明旧版本失败、新版本通过？
- 测试由独立规则选择，还是只由实现者或 Agent 自选？
- 能否看到实际运行、跳过和 fallback 的 Manifest？
- Required Gate 是否把 failed、cancelled、timeout 和非法 skipped 都视为失败？
- AI Review、确定性检查和人工 Review 的职责是否不同？
- 新 Commit 是否使需要重审的旧批准失效？
权限与供应链
- 不可信 Issue、PR、网页和工具输出能否直接触发写操作？
- Agent 是否持有超出当前任务所需的 token、Secrets、网络或 MCP？
- 高权限写入是否由独立任务对结构化请求重新验证？
- Agent 能否批准或合并自己产生的改动？
反馈与演进
- Agent 任务、Commit、PR、CI、部署和事故能否用 ID 关联？
- 缺陷修复后是否会留下自动回归并进入影响映射？
- 团队是否知道当前瓶颈在决策、实现、CI、Review、发布还是恢复，并据此调整 WIP？
如果多数问题的答案依赖“大家应该会记得”，流程仍主要靠个人经验；如果答案能从仓库、平台规则和证据记录中直接查到，才具备多人和多 Agent 快速协作的基础。
结语
Git 让变化可保存和比较，PR/MR 让变化可讨论，CI 让明确规则可重复执行，分支保护让合并政策不可静默绕过，线上观测让未知问题进入下一轮改进。
AI 增加了调查、生成和比较的供给，但没有消除决定、证明和承担责任的需要。成熟方向不是让一个 Agent 模拟所有角色，而是把工作拆成相互制衡的部分：
人定义价值与风险
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：本文核对其AGENTS.md、CONTRIBUTING.md、CI 文档、Mantis 和 Test Performance Agent Workflow。 - OpenAI Codex
a16863f8：本文核对其贡献指南、AGENTS.md和 PR/post-merge CI Workflows。
官方产品与安全文档
- OpenAI：Code Review、
AGENTS.md、GitHub Code Review 用例。 - GitHub Copilot cloud agent：Risks and mitigations、Custom guardrails。
- GitHub Agentic Workflows：概览、架构、权限、Safe outputs。
- Anthropic Claude Code Action：Security。
研发效能研究
- DORA：2025 报告、五项软件交付指标、Value stream management。
- Microsoft Research：SPACE of Developer Productivity。
- GitHub：2022 Copilot 固定任务实验。
- METR：Early-2025 experienced OSS developer study、2026 uplift update。
本文对源码中实际存在的规则标注了固定 Commit；产品行为以链接的官方文档为准；跨项目共同模式、建设等级和示例流程是本文归纳，不是上述项目共同发布的标准。公开文档不能证明某家公司内部全部研发流程，本文不作这种外推。