隆重推出 PR 级别规则：
审查 PR，而不仅仅是代码
自动执行团队关于提交信息、PR 描述、破坏性变更等方面的约定
代码审查不仅仅是关于代码本身，更是关于上下文：为什么要做这个更改？PR 是否专注于一件事？破坏性变更是否有文档记录？直到现在，基于 AI 的代码审查工具一直忽略了这些。今天，这一切将改变。
我们很高兴推出 PR 级别规则 —— 一种新类别的规则，用于分析整个 Pull Request，而不仅仅是单个文件。通过两个新的特殊标签 pr-level 和 git-history，您现在可以自动执行团队的 PR 规范约定。
新功能介绍
传统的 AI 代码审查逐个分析文件，检查 bug、安全问题和代码模式。但是，优秀 PR 中一些最重要的方面无法在任何单个文件中找到：
PR 描述质量
描述是否解释了"为什么"而不仅仅是"做了什么"？
提交信息
是否遵循 Conventional Commits 格式？
PR 范围
是否专注于单个逻辑变更？
破坏性变更
是否附带迁移指南？
现在 diffray 可以自动检查所有这些内容 —— 适用于每一个 PR。
两个新标签：pr-level 和 git-history
我们添加了两个特殊标签，它们会改变 AI 代理处理规则的方式：
pr-level
用于分析整个 PR 的规则 —— 描述质量、变更范围、破坏性变更文档、新功能的测试覆盖率。
代理会查看整体情况：哪些文件被修改了？有多少个？整体意图是什么？
git-history
用于需要分析提交历史的规则 —— 消息格式、提交原子性、工单引用。
代理使用 git log 来检查提交信息和模式。
即用型规则示例
1. PR 描述应解释"为什么"
PR 最常见的问题是：它们列出了做了什么更改，但没有说明为什么。审查者可以看到 diff —— 他们需要的是上下文。
- id: pr_description_explain_why
agent: general
title: PR 描述应解释动机
importance: 7
always_run: true
match:
file_glob: ['**/*']
checklist:
- 检查 PR 描述是否解释了业务原因
- 确保回答了"为什么需要这个更改？"
- 寻找关于解决问题的上下文
tags:
- pr-level
- quality糟糕的 PR 描述
- 更新了 UserService.ts
- 为登录表单添加了验证
- 修复了支付 bug
优秀的 PR 描述
## 问题
用户在结账时购买 50+ 件商品会遇到超时，原因是 N+1 查询问题。
## 解决方案
使用 DataLoader 模式进行批量加载。
2. Conventional Commits 格式的提交信息
确保统一的提交格式，以便自动生成变更日志和语义化版本控制：
- id: commit_message_format
agent: general
title: 提交信息应遵循 Conventional Commits 格式
importance: 5
always_run: true
match:
file_glob: ['**/*']
checklist:
- 使用 git log --oneline 检查最近的提交
- 确保提交遵循 type(scope): description 格式
- 检查消息的清晰度（不要用 "fix stuff"、"WIP"）
examples:
bad: |
fix stuff
WIP
update code
good: |
feat(auth): add OAuth2 login with Google
fix(api): handle null response from payment service
tags:
- git-history
- automation3. 破坏性变更必须有文档记录
没有什么比未记录的破坏性变更进入生产环境更快地破坏信任了：
- id: breaking_changes_documented
agent: general
title: 破坏性变更必须有明确文档
importance: 9
always_run: true
match:
file_glob: ['**/*']
checklist:
- 检查变更是否修改了公共 API 或删除了功能
- 如果是破坏性变更，确保提交信息包含 BREAKING CHANGE
- 检查 PR 描述中是否有迁移指南
tags:
- pr-level
- git-history
- breaking-changes4. 单一职责的 PR
混合了新功能、bug 修复和重构的 PR 无法得到有效审查：
- id: pr_single_responsibility
agent: general
title: PR 混合了不相关的变更
importance: 7
always_run: true
match:
file_glob: ['**/*']
checklist:
- 检查已修改的文件以识别不同的变更区域
- 确保变更不涉及多个不相关的功能
- 如果 PR 同时涉及 auth、payments 和 styling，则进行报告
tags:
- pr-level
- quality5. 强制要求工单引用
为了可追溯性和发布说明，每个 PR 都应该关联一个任务：
- id: pr_ticket_reference
agent: general
title: PR 必须引用 issue 或工单
importance: 5
always_run: true
match:
file_glob: ['**/*']
checklist:
- 检查提交中是否有工单引用（PROJ-123、#123、ENG-456）
- 在提交信息中查找任务 URL
- 仅当没有任何提交包含工单引用时才报告
tags:
- pr-level
- git-history
- traceability底层工作原理
general 代理已更新了处理这些标签的特殊指令：
| 标签 | 代理行为 |
|---|---|
| pr-level | 分析整体 PR 上下文 —— 已修改的文件、变更范围、描述质量 |
| git-history | 使用 Bash 执行 git 命令：git log --oneline -20 —— 最近的提交git log --stat -5 —— 包含文件变更git log --format="%s%n%b" -10 —— 完整消息 |
带有 always_run: true 的规则会对每个 PR 执行，无论修改了哪些文件。这使它们非常适合不依赖特定文件模式的 PR 级别检查。
快速开始
为您的项目添加 PR 级别规则非常简单：
1. 创建规则目录
mkdir -p .diffray/rules/pr-quality2. 添加您的规则
创建带有 always_run: true 和相应标签的 YAML 文件
3. 打开一个 PR
diffray 将自动识别您的新规则
我们在 project-specific-rules 仓库 中发布了示例规则，您可以复制并根据需要进行自定义。
为什么这很重要
优秀的 PR 不仅仅是可运行的代码。它们是为未来开发者准备的文档，是合规审计的追踪记录，是"这里发生了什么？"和"哦，我明白了"之间的区别。
遵守 PR 标准的团队能交付更高质量的软件。 不是因为代码不同，而是因为上下文得到了保留。现在 diffray 可以帮助您自动维护这些标准。
PR 级别规则将团队的隐性知识转化为自动化检查。不再依赖于每个人都记得引用工单、记录破坏性变更和编写有意义的描述 —— 而是为每个 PR 获得一致的反馈。