PR 和代码评审

目的

定义代码如何安全进入 main。

工具

需要 工具
Pull request GitHub
Required checks GitHub branch protection
Review owner CODEOWNERS
CI GitHub Actions
Issue link Linear / GitHub integration

PR 模板

使用 templates/PR模板-pr-template.md。

每个 PR 必须说明：

  1. 改了什么。
  2. 为什么改。
  3. 如何测试。
  4. 风险是什么。
  5. 如何回滚。
  6. UI/API 行为变化时提供截图或证据。

还必须能看出闭环角色：

字段 用途
Driver 谁负责把 PR 推到 merge / close / retry
Reviewer 谁负责代码和风险判断
Approver 谁负责产品、上线或风险接受
Operator 如需发布，谁负责部署和回滚

评审门禁

变更类型 Review 要求
小 bug fix 1 个 reviewer + CI
用户可见功能 1 个 reviewer + 产品验收
数据库 migration reviewer + migration plan
Auth/security/payment/production config tech lead approval
跨模块架构变化 先 RFC/ADR，再实现
Runtime/Agent 权限变化 platform owner approval

评审结论只能是四种之一：

结论 含义
Approve 可以进入下一步
Request changes 需要修改后再审
Blocked 需要外部决策、信息或依赖
Close / reject 不再继续，必须记录原因

不要让 PR 长期处于“大家都看过但没人拍板”的状态。

三角色 PR 判断

角色 在 PR 中必须能看到 常见结论
产品负责人 用户可见变化、截图 / 录屏、验收结论、反馈入口 通过验收 / 需要改产品行为
技术负责人 scope、架构影响、测试、风险、回滚 approve / request changes / block
平台 / 资深工程师 CI、命令输出、migration、发布和监控入口 补检查 / 补脚本 / 补文档

分支保护

Main 分支应要求：

  1. PR review。
  2. Required CI checks。
  3. 禁止 force push。
  4. 必要时要求分支 up-to-date 或使用 merge queue。
  5. 敏感路径使用 CODEOWNERS。

评审者检查表

  1. 是否解决了正确问题？
  2. Scope 是否足够小？
  3. 是否尊重模块边界？
  4. 测试是否有意义？
  5. 生产风险是否清楚？
  6. 是否能回滚？
  7. Secret 和权限是否处理正确？

新人 PR 额外建议

新人前几个 PR 应优先小 scope，并在 PR 描述里多写一点上下文：

  1. 关联任务和验收标准。
  2. 自己理解的改动范围。
  3. 改了哪些关键文件。
  4. 跑了哪些检查，结果是什么。
  5. 哪些地方不确定，希望 reviewer 重点看。

Reviewer 对新人 PR 不只看代码，也要指出项目约定、测试习惯和文档入口。能写进文档的反馈，不要只留在一次性评论里。

后续 Agent 就绪要求

这一节在人类 PR review 已经能稳定执行后再看。

Agent 生成的 PR 也必须满足同一模板。Agent 可以生成证据，但最终 approval 由人类 reviewer 负责。

Agent PR 额外要求：

  1. 说明输入 task 和 scope。
  2. 列出 Agent 改过的文件。
  3. 附上测试命令和结果。
  4. 标出未验证风险。
  5. 给出 human reviewer 的下一步选项：merge、request changes、retry、close。

下一步阅读

读完或填完这份文档后，通常继续看：