SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场code-review

code-review

编程与开发

查看项目

更新于 10-15 14:30

技能介绍

用途

Code Review — Standards and Spec 是一个代码审查技能，用于审查自某个固定基准点（提交 SHA、分支名、标签、main、HEAD~5 等）以来的变更。它沿两条相互独立的轴进行审查：

  • 标准轴（Standards）：代码是否符合本仓库文档化的编码规范？
  • 规格轴（Spec）：代码是否忠实实现了来源 issue / 规格说明？

两条轴以并行子代理运行，避免相互污染上下文，随后由本技能汇总双方发现。适用于用户想审查分支、PR、进行中的改动，或提出“审查自 X 以来的变更”。

该技能从 mattpocock/skills（MIT）导入，上游为模型调用。

主要能力

  • 双轴并行审查：Standards 与 Spec 分别由独立子代理执行，最后并排呈现，不合并、不重新排序。
  • 固定基准点：用户指定基准点后，捕获一次 diff 命令 git diff <fixed-point>...HEAD（三点，与 merge-base 比较），并记录提交列表 git log <fixed-point>..HEAD --oneline。
  • 前置校验：在进入并行子代理前，先确认基准点可解析（git rev-parse <fixed-point>）且 diff 非空；坏引用或空 diff 应在此处失败。
  • 规格来源识别：按顺序查找来源规格——提交信息中的 issue 引用（#123、Closes #45、GitLab !67 等，通过 docs/agents/issue-tracker.md 的工作流获取）、用户作为参数传入的路径、docs/、specs/ 或 .scratch/ 下与分支名或功能匹配的规格文件。若找不到则询问用户；若用户表示没有规格，Spec 子代理跳过并报告“no spec available”。
  • 标准来源识别：仓库中记录代码应如何编写的任何文件，如 CODING_STANDARDS.md 或 CONTRIBUTING.md。
  • 气味基线：在仓库文档之外，标准轴始终携带一组固定的 Fowler 代码气味（《重构》第 3 章）作为基线，即使仓库未记录任何规范也适用。两条约束：仓库覆盖——文档化的仓库标准始终优先，若其认可某基线会标记的做法，则抑制该气味；始终是判断性判断——每个气味都是带标签的启发式（如“possible Feature Envy”），绝非硬性违规，且跳过工具已强制执行的任何内容。
  • 气味清单（每条读作“是什么 → 如何修复”）：Mysterious Name（名称不揭示其作用或内容 → 重命名；若想不出诚实的名字，说明设计模糊）、Duplicated Code（同一逻辑形态出现在多个 hunk 或文件 → 提取共享形态，两处调用）、Feature Envy（方法访问另一对象的数据多于自身 → 将方法移到它所羡慕的数据上）、Data Clumps（同一组字段或参数总是一起出现 → 打包成一个类型传递）、Primitive Obsession（用原始类型或字符串代替值得拥有自身类型的领域概念 → 给该概念一个小类型）、Repeated Switches（同一类型上的同一 switch/if 级联在变更中反复出现 → 用多态或共享映射替换）、Shotgun Surgery（一次逻辑变更迫使在 diff 中许多文件里分散编辑 → 将一起变化的内容聚到一个模块）、Divergent Change（一个文件或模块因多个不相关原因被编辑 → 拆分，使每个模块只因一个原因变化）、Speculative Generality（为规格没有的需求添加抽象、参数或钩子 → 删除，内联回去直到出现真实需求）、Message Chains（调用方不应依赖的长 a.b().c().d() 导航 → 在第一个对象上用单个方法隐藏该遍历）、Middle Man（类或函数大多只是转发 → 删掉，直接调用真实目标）、Refused Bequest（子类或实现者忽略或覆盖了它继承的大部分内容 → 放弃继承，改用组合）。

使用方式

  1. 固定基准点：用户所说的基准点（提交 SHA、分支名、标签、main、HEAD~5 等）。若未指定则询问。捕获 diff 命令与提交列表，并先确认基准点可解析、diff 非空。
  2. 识别规格来源：按上述顺序查找；找不到则询问用户。
  3. 识别标准来源：仓库文档文件，加上气味基线。
  4. 并行生成两个子代理：
    • Standards 子代理提示包含：完整 diff 命令与提交列表；第 3 步找到的标准来源文件列表，以及完整粘贴的气味基线（子代理无其他途径获取）。任务简述：“按文件/hunk 报告：(a) diff 违反文档化标准的每一处：引用标准（文件 + 规则）；(b) 发现的任何基线气味：命名并引用该 hunk。区分硬性违规与判断性判断：文档化标准的违反可以是硬性的，但基线气味始终是判断性判断，且文档化的仓库标准覆盖基线。跳过工具已强制执行的任何内容。400 字以内。”
    • Spec 子代理提示包含：diff 命令与提交列表；规格的路径或已获取内容。任务简述：“报告：(a) 规格要求但缺失或部分实现的需求；(b) diff 中未被要求的行为（范围蔓延）；(c) 看似已实现但实现有误的需求。每条发现引用规格原文。400 字以内。”
    • 若规格缺失，跳过 Spec 子代理并在最终报告中注明。
  5. 汇总：在 ## Standards 和 ## Spec 标题下呈现两份报告，逐字或轻度清理。不要合并或重新排序发现，因为两条轴是刻意分开的。最后以一行总结收尾：每条轴的发现总数，以及每条轴内最严重的问题（如有）。不要跨轴选出单一赢家。

适用场景

  • 审查分支、PR、进行中的改动。
  • 用户要求“审查自 X 以来的变更”。
  • 需要同时检查代码规范符合度与规格实现忠实度的场景。

限制

  • 需要用户提供固定基准点；未提供时需询问。
  • 需要规格来源；若缺失，Spec 轴跳过并报告“no spec available”。
  • 若 docs/agents/issue-tracker.md 缺失，需提示用户运行 /setup-matt-pocock-skills。
  • 基线气味始终是判断性判断，非硬性违规；文档化仓库标准覆盖基线；跳过工具已强制执行的内容。
  • 两条轴刻意分开，不合并、不重新排序、不跨轴选单一赢家。
  • 本地路由：与仓库无关的审查路由简述（严重性阶梯、缺失证明检查，以及路由到 debugging、testing-strategies、code-refactoring）现位于 references/jeo-review-routing.md。当请求是“我们应如何审查这个”而非“现在运行审查”时阅读它。

最佳实践

  • 先在一个狭窄范围应用本技能，确认输出符合上述形态，再扩展到完整任务。
  • 当某步骤需要来自仓库或环境的事实时，去查找而不是询问用户。
  • 保持上游流程完整；明确记录偏差，而不是默默即兴发挥。
  • 在本技能标记为属于用户的每个决策点停下并把控制权交还用户。
  • 偏好小而可逆的变更，并陈述假设而不是埋没它们。

参考

  • 上游技能：mattpocock/skills skills/engineering/code-review/SKILL.md（commit 3cca18b，MIT）
  • 项目标准：.agent-skills/skill-standardization/SKILL.md
  • 校验脚本：.agent-skills/skill-standardization/scripts/validate_skill.sh