pr-antipattern-review

PR 反模式审查

通过将差异与项目的切片目录进行比较来审查差异。找出与已声明切片不符之处以及通用反模式。输出包含 path:line 引用的审查结果，可直接粘贴为 PR 评论。

此技能采用比较式审查，而非百科式审查。它会将差异与 BLUEPRINT.md 进行比较，而不是运行通用检查清单。

**默认情况下，输出仅临时保留。**审查结果会发送到聊天中。仅在用户要求时才保存到文件。

---

核心原则

1. Blueprint 是规则手册。如果项目有 BLUEPRINT.md，它就决定了什么是对的、什么是错的。没有 blueprint 依据的审查结果可信度较低（属于建议，而非违规）。
2. 切片是比较的基本单位。问题不是“这个 PR 是否违反通用原则”，而是“它是否遵循正在修改的切片”。
3. 判断问题交由人工参与。遇到有歧义的情况时，不要自行判定严重性。不要将偏差归类为有意还是意外——应当询问。
4. 童子军规则。对于被修改文件中原本就存在的问题，除非 PR 让问题变得更严重，否则不应归咎于该 PR。
5. 输出仅临时保留。审查结果发送到聊天中。绝不自动写入文件。绝不自动提交。

---

工作流

第 1 步 — 检测输入格式

根据用户提供的内容进行处理：

输入	操作
URL github.com/<owner>/<repo>/pull/<N>	gh pr diff <URL> — 备用方案：使用可用的浏览器／网页工具或 curl -L 获取 <URL>.diff
URL gitlab.com/.../merge_requests/<N>	glab mr diff <N> — 备用方案：使用可用的浏览器／网页工具或 curl -L 获取 <URL>.diff
PR #<N> 或仅 <N>	在当前仓库中运行 gh pr diff <N>
40 位十六进制值／“commit ”	git show <sha>
以 diff --git 开头的差异文本	按原样使用
未提供具体内容	执行 git diff <base>...HEAD，其中 <base> 为默认分支；备用方案：git diff HEAD~1

如果输入有歧义，先检查 git status 和 git log -1。

第 2 步 — 确认差异涉及哪些项目

对于差异中的每个文件：

• 根据路径匹配仓库中的项目
• 按项目对更改分组

⏸ 停下并询问的检查点 1（仅当差异涉及多个项目时）：

“此差异涉及项目 A 和 B。要审查两个项目、仅审查 A、仅审查 B，还是将其视为一个跨项目更改？”

如果差异仅涉及一个项目：无需检查点，继续操作。

第 3 步 — 加载 blueprint

对于每个涉及的项目，在以下位置查找 BLUEPRINT.md：

• docs/architecture/<project>/BLUEPRINT.md（monorepo 约定）
• docs/architecture/BLUEPRINT.md（单项目约定）
• docs/BLUEPRINT.md

如果 monorepo 中有 docs/architecture/SYSTEM_MAP.md，也要加载它——当差异涉及跨项目边界更改时需要此文件。

如果找不到 blueprint：

• 告知用户：“找不到项目 X 的 BLUEPRINT.md。现在仅运行通用检查——审查结果可信度较低，也可能遗漏项目特定约定。要我建议先运行 project-blueprint 吗？”
• 以较低置信度继续

第 4 步 — 解析差异

对于每个更改的文件：

• 状态：新增／修改／删除／重命名
• 包含 + 和 - 行的代码块
• 新导入项（分层问题的重要信号）
• 新文件路径（切片／非切片的重要信号）
• 净行数变化和公共 API 变化

步骤 5 — 将每项更改归类到对应切片

对于 diff 中的每个文件：

1. 根据文件路径和结构，确定它所属的切片
2. 如果无法明确判断属于哪个切片，⏸ 询问：

   “文件 X 不明显属于切片 Y 或 Z。这属于哪个切片，还是一个新切片？”

3. 根据切片声明的约束检查文件的新内容：
   • 导入项是否符合切片允许的范围？
   • 命名是否符合切片约定？
   • 框架／库是否与规范一致？
   • 是否包含共同创建的文件（测试、DI 注册等）？
4. 检查切片的状态：
   • frozen — 将新增实例标记为回归
   • deprecated — 将任何新增内容标记出来
   • active — 正常比较
5. 检查变体：
   • 实例符合现有变体 → 没问题，记录下来
   • 实例属于新变体 → ⏸ 询问这是有意为之（需要决策规范）还是意外情况

步骤 6 — 应用通用检查

无论是否有蓝图，都要检查：

• 在已提交文件中引入的机密信息
• 清单级依赖反转（.csproj / package.json 新增了反转架构依赖方向的引用）
• 安全回归（移除了身份验证、移除了验证、放宽了 CORS）
• 未作说明的测试移除
• 新增的捕获并吞掉异常的代码
• 未给出理由的类型检查器屏蔽操作

完整清单和检测命令见 references/universal-checks.md。

步骤 7 — 童子军规则筛选

对于每项发现，检查同一文件中的问题在此次 PR 之前是否已经存在：

• 如果存在，且 PR 没有使问题恶化 → 降级为“既存问题背景”（提及一次，不计入 PR 的问题）
• 如果存在，且 PR 使问题恶化（例如，给臃肿服务新增第 26 个方法）→ 计入 PR 的问题

PR 恰好涉及但并未使之恶化的既存问题，不算作发现。

步骤 8 — 对严重程度进行分类

级别	评审结论
阻塞项	要求修改
应修复项	留言（建议合并前修复）
小问题	LGTM，附注释

如果无法确定是阻塞项还是应修复项，⏸ 询问：

“这项发现［描述］可能属于阻塞项，也可能属于应修复项，具体取决于上下文。该 PR 的情况是［上下文］。你希望将其归为哪一类？”

对于可能属于任一类别的问题，不要擅自决定严重程度。

步骤 9 — 确定评审结论

条件	评审结论
存在任何阻塞项	❌ 要求修改
4 项或以上应修复项，或多次出现同类应修复项	⚠️ 留言
1–3 项有可行变通方案的应修复项，或只有小问题	✅ LGTM，附注释
未标记任何问题	✅ LGTM

步骤 10 — 提交前摘要

输出最终评审前：

⏸ 停止并询问检查点 2（仅在要发布、保存或严重程度／分类存在歧义时）：

“发现的问题：N 项阻塞项、M 项应修复项、K 项小问题。评审结论：[X]。确认一下，或者你想在我撰写评审前调整任何分类吗？”

这是输出评审前发现误判的最后机会。

步骤 11 — 输出评审

使用 assets/review-template.md 在聊天中输出评审。发现项采用 path:line 格式，方便用户将其粘贴为 PR 评论。

然后询问：

“要我将其保存为 Markdown 文件吗？否则内容会保留在聊天记录中。”

只有用户明确同意后才保存到文件。默认只在聊天中输出。

---

停止并询问检查点摘要

#	检查点	触发时机
1	多项目评审范围	步骤 2，仅当 diff 涉及多个项目时
2	文件的切片分类	步骤 5，仅当分类不明确时
3	变体是有意还是意外	步骤 5，仅当检测到新变体时
4	严重程度不明确	步骤 8，仅当阻塞项／应修复项的归类确实存在争议时
5	提交前确认	步骤 10，仅当要发布、保存或仍存在歧义时

如果出现任何意外情况，还应暂停询问 — 绝不擅自做决定。

---

Agent 观察什么，人类决定什么

Agent 观察：

• 文件属于哪个切片（根据路径和结构）
• 文件是否符合切片的规范结构
• 导入是否遵守分层／切片约束
• 是否存在测试
• 清单级依赖变更
• 可通过 grep 查找的反模式（机密信息、零散的环境变量、捕获后忽略异常）

人类决定：

• 新变体是有意添加还是意外产生
• 存在争议时的严重程度（是否有意引入安全回退？是否为旧版兼容方案？）
• 是否将现有问题计入此 PR
• 是否将审查结果保存为文件

---

此技能不会做什么

• 生成蓝图（请使用 project-blueprint）
• 自动提交任何内容
• 除非用户明确要求，否则不自动写入文件
• 将通用反模式目录当作项目规则套用
• 忽略已存在的蓝图

---

没有蓝图时

如果没有 BLUEPRINT.md，此技能只会执行通用检查：

• 机密信息、清单依赖反转、安全回退、被移除的测试、屏蔽类型检查器、捕获后忽略异常

输出会明确说明："未找到项目蓝图——审查仅基于通用检查。检查结果可能遗漏项目特定约定。运行 project-blueprint 以启用基于切片的比较。"

---

另请参阅

• references/slice-comparison.md — 如何根据切片目录检查差异
• references/universal-checks.md — 与项目无关的观察项
• references/diff-checks.md — 无论项目如何都适用的可 grep 查找模式
• assets/review-template.md — 输出格式