用途
code-review 用于审查 HEAD 与用户指定固定点之间的代码变更(diff),从两个维度分别评估:
- 标准(Standards):代码是否遵循本仓库中记录的编码规范。
- 规格(Spec):代码是否忠实实现了对应的原始 issue / 规格说明。
两个轴作为并行子代理运行,避免相互污染上下文,最后由本技能汇总结果。使用前提是已向技能提供 issue 跟踪信息。
主要能力
1. 固定审查基准点
用户给出的任何内容即为固定点(commit SHA、分支名、tag、main、HEAD~5 等);未指定时需询问。捕获一次 diff 命令:git diff <fixed-point>...HEAD(三点语法,对 merge-base 比较),并记录提交列表 git log <fixed-point>..HEAD --oneline。继续之前确认固定点可解析(git rev-parse <fixed-point>)且 diff 非空;无效引用或空 diff 应在此处失败,而不是在并行子代理内部失败。
2. 识别规格来源
按以下顺序查找原始规格:
- 提交信息中的 issue 引用(#123、Closes #45、GitLab !67 等),通过
docs/agents/issue-tracker.md中的工作流获取。规格即该 issue 的实现契约;当跟踪器文档说明哪个评论或正文承载该契约时,按该内容审查,其余作为上下文。 - 用户作为参数传入的路径。
docs/、specs/或.scratch/下与分支名或功能匹配的规格文件。
若均未找到,询问用户规格在哪里;若用户表示没有规格,则 Spec 子代理跳过并报告“无可用规格”。
3. 识别标准来源
查找仓库中说明代码应如何编写的文档,例如 CODING_STANDARDS.md、CONTRIBUTING.md。在此之上,Standards 轴始终携带以下坏味道基线(Fowler《重构》第 3 章的固定代码坏味道集合),即使仓库未记录任何规范也适用。两条约束:仓库规范优先,已记录的仓库标准总是胜出,若其认可基线会标记的内容则抑制该坏味道;一切均为判断性提示,每个坏味道都是带标签的启发式(如“可能的 Feature Envy”),绝非硬性违规,且跳过工具已强制检查的内容。
每个坏味道按“是什么 → 如何修复”匹配 diff:
- 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:子类或实现者忽略或覆盖了大部分继承内容 → 放弃继承,改用组合。
4. 并行启动两个子代理
Standards 子代理的提示包括:完整 diff 命令与提交列表;步骤 3 找到的标准来源文件列表,加上完整粘贴的坏味道基线(子代理无其他途径获取);简报:“按文件/hunk 报告:(a) diff 违反已记录标准的每一处:引用标准(文件 + 规则);(b) 发现的任何基线坏味道:命名并引用该 hunk。区分硬性违规与判断性提示:已记录标准的违反可为硬性,但基线坏味道始终是判断性提示,且已记录的仓库标准覆盖基线。跳过工具检查的内容。400 词以内。”
Spec 子代理的提示包括:diff 命令与提交列表;规格的路径或已获取内容;简报:“报告:(a) 规格要求但缺失或不完整的需求;(b) diff 中未被要求的改动(范围蔓延);(c) 看似已实现但实现有误的需求。每条发现引用规格原文。400 词以内。”若规格缺失,跳过 Spec 子代理并在最终报告中注明。
5. 汇总
在 ## Standards 与 ## Spec 标题下分别呈现两份报告(逐字或轻度清理)。不要合并或重新排序发现,因为两个轴是刻意分开的。最后一行总结:每轴发现总数,以及各轴内最严重的问题(若有)。不要在轴之间选出唯一赢家,那正是分离双轴所避免的重新排序。
为什么两个轴
变更可能通过一个轴而失败于另一个轴:
- 遵循所有标准但实现了错误的东西 → 标准通过,规格失败。
- 完全按 issue 要求实现但违反项目约定 → 规格通过,标准失败。
分开报告可防止一个轴掩盖另一个轴。
读取文件
路径相对于仓库根目录:
docs/agents/issue-tracker.md:如何获取提交信息引用的 issue,以及哪个评论或正文承载 issue 的实现契约。缺失且未提供跟踪器时,按步骤 2 的其他位置查找规格,不阻塞审查。docs/、specs/或.scratch/下的规格文件。缺失时按步骤 2 询问用户规格在哪里。CODING_STANDARDS.md、CONTRIBUTING.md以及仓库中记录代码编写方式的其他内容。缺失时,Standards 轴仅携带坏味道基线。
适用场景与限制
适用于以固定点为基准、同时关心“合规”与“符合规格”的代码变更审查,尤其适合有 issue 跟踪与编码规范文档的仓库。限制:需要用户提供固定点,未提供需询问;需要规格来源,找不到需询问或由 Spec 轴跳过并注明;基线坏味道均为判断性提示而非硬性违规;不处理工具已强制检查的内容;不跨轴挑选单一最严重问题。