双轴并行代码审查解析 GitHub_Trending/skills13/skills 的 code-review 技能Standards × Spec【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skillscode-review是 GitHub_Trending/skills13/skills 仓库中一个面向真实工程实践的代码审查技能它对HEAD与某个固定点commit、分支、tag 或 merge-base之间的 diff 沿两条轴进行审查Standards代码是否符合仓库文档化的编码标准与Spec代码是否忠实实现了来源 issue / 规格文档。两条轴以并行子代理运行互不污染上下文最终报告分开呈现、绝不合并排序。读完本文你将掌握该技能的五步执行流程、十二条 Fowler 坏味道基线、两个子代理的提示词构造方法以及它在「规格 → 工单 → 实现 → 审查」构建链中的位置与常见坑位。技能定位它解决什么问题在 skills/engineering/README.md 中code-review被归类为Model-invoked模型可调用同时用户也可显式触发与tdd、domain-modeling、codebase-design等同组。顶层 README.md 对其一句话概括是「Two-axis review of the diff since a fixed point: Standards是否遵循仓库编码标准外加 Fowler 坏味道基线与 Spec是否忠实实现来源 issue/规格以并行子代理运行互不污染」。它的核心判断是两个独立问题轴提出的问题读取的输入报告内容Standards是否「造对了」Is it built right?仓库文档化的标准 坏味道基线文档化标准的违规可为硬性违规以及坏味道永远只是判断性结论Spec是否「造的是对的东西」Is it the right thing?来源 issue 或规格文档缺失/部分实现的需求、范围蔓延scope creep、实现疑似有误的需求每条 Standards 发现都必须引用标准文件与对应规则或点名坏味道并引用 hunk每条 Spec 发现都必须引用规格原文行。这个「每条发现强制携带引用」的设计是整套报告可核查性的基础。何时该用它你的处境该用什么有一份 diff既想知道它造得对不对又想知道它是否是该造的东西code-review想在 diff 里猎 bug空指针路径、竞态、off-by-oneClaude Code 内置的 review见下方「命名冲突」什么都还没写想测试先行tdd整个规格需要从零构建并包含审查implement它内部就会调用本技能整个代码库已经漂移而非某一份 diffimprove-codebase-architecture有东西坏了但不知道原因diagnosing-bugs从 tdd/SKILL.md 的「Rules of the loop」还可以看到它与 TDD 的边界约定重构不属于红绿循环它属于审查阶段code-review 技能。也就是说TDD 负责把功能按纵向切片做出来code-review负责在提交前对整段 diff 做最终把关。前置条件与固定点使用本技能时必须由用户提供固定点fixed point。如果用户没说技能会主动询问而不是猜测。固定点可以是 commit SHA、分支名、tag、main、HEAD~5等任何 git 能解析的引用。随后技能会验证两件事任何一项不通过就在启动子代理之前直接失败git rev-parse fixed-point能解析该引用坏引用立刻暴露而不是在两个并行子代理内部爆炸git diff fixed-point...HEAD非空。Standards 轴几乎不需要前置条件它读取仓库自带的任何文档化标准CODING_STANDARDS.md、CONTRIBUTING.md之类当仓库什么都没记录时回退到内置的坏味道基线。Spec 轴需要一份能找到的规格。查找顺序如下commit message 中的 issue 引用#123、Closes #45、GitLab!67通过 issue tracker 工作流获取用户作为参数传入的路径docs/、specs/或.scratch/下与分支名或功能名匹配的规格文件直接询问用户。其中第 1 步依赖 issue tracker 集成。本仓库中/setup-matt-pocock-skills负责生成docs/agents/issue-tracker.md而具体的三种后端约定分别记录在 issue-tracker-local.md.scratch/feature-slug/下的本地 Markdown 文件规格为spec.md工单为issues/NN-slug.md、issue-tracker-github.md用gh issue view number --comments拉取 issue 及评论与 issue-tracker-gitlab.md。若缺少该文件技能会提示用户运行/setup-matt-pocock-skills。即便没有集成用户直接传路径也能工作如果最终一份规格都没有Spec 子代理会被跳过报告注明「no spec available」而不是凭空编造需求。五步执行流程第一步钉住固定点无论用户给出的是何种引用都将其捕获为一条一次性记录好的 diff 命令git diff fixed-point...HEAD # 三点式three-dot对比基于 merge-base git log fixed-point..HEAD --oneline # 提交清单三点式是关键它从 merge-base 起算排除暂存区staged与工作区working-tree的未提交改动。因此如果implement尚未做中间提交即将提交的工作对本技能是不可见的。正确节奏是先 commit再 review之后 amend 或补 fixup。在深入之前必须确认引用可解析、diff 非空让坏引用或空 diff 在这里失败而不是在两个并行子代理内部失败。第二步定位规格来源按上述四个优先级查找来源规格。规格文本将被原样塞进 Spec 子代理的提示词中作为它逐条比对需求的依据。第三步定位标准来源与坏味道基线Standards 轴的依据分两层仓库文档化的标准CODING_STANDARDS.md、CONTRIBUTING.md等任何记录了「代码应该如何写」的文件。仓库自有文档是 Standards 轴的首要来源仓库永远覆盖基线凡文档化标准明确认可了基线会标记的东西就抑制该坏味道。坏味道基线smell baseline当仓库什么都没记录时兜底的一组固定判断。它来自 Fowler《重构》第 3 章共十二条。两条规则约束它仓库文档优先且每条坏味道都是有标签的启发式判断「possible Feature Envy」绝不是硬性违规。凡是工具链linter已强制的内容两条轴都会跳过。十二条坏味道每条都是「它是什么 → 怎么修」因此发现本身就附带了一个行动方案而不是一句抱怨坏味道它是什么怎么修Mysterious Name神秘命名函数、变量或类型的名字无法揭示其行为或内容重命名如果找不到诚实的名字说明设计本身就模糊Duplicated Code重复代码同一逻辑形状出现在改动中的多个 hunk 或多个文件提取共享形状两处都调用它Feature Envy依恋情结方法访问另一个对象的数据多于自己的数据把方法移到它羡慕的那个数据上Data Clumps数据泥团同样的几个字段或参数总是结伴出现一个等待诞生的类型把它们打包成一个类型传这个类型Primitive Obsession基本类型偏执用基本类型或字符串替代一个值得拥有独立类型的领域概念给该概念一个自己的小类型Repeated Switches重复的 switch改动中对同一类型反复出现相同的switch/if级联用多态替代或两处共享同一个映射Shotgun Surgery霰弹式修改一个逻辑改动被迫散落在 diff 的许多文件里把一起变化的东西收拢进一个模块Divergent Change发散式变化一个文件或模块因多个无关原因被修改拆分让每个模块只为一个原因变化Speculative Generality过度设计为规格并不需要的需求添加的抽象、参数或钩子删除它内联回去直到真实需求出现Message Chains消息链长的a.b().c().d()导航调用方不该依赖它把整段行走藏到第一个对象的一个方法后面Middle Man中间人一个类或函数大部分工作只是转发砍掉它直接调用真正的目标Refused Bequest被拒的遗产子类或实现者忽略或重写了它继承的大部分内容放弃继承改用组合第四步并行派生两个子代理两个子代理同时启动各自携带独立的上下文互不可见对方的推理。Standards 子代理提示词必须包含完整的 diff 命令与提交清单第三步找到的标准来源文件列表外加完整粘贴的坏味道基线子代理没有其他途径访问它简报brief「按文件/hunk 报告(a) diff 中每个违反文档化标准之处并引用该标准文件 规则(b) 你发现的任何基线坏味道点名并引用 hunk。区分硬性违规与判断性结论文档化标准的破坏可以是硬性的但基线坏味道永远是判断性结论且仓库文档化标准覆盖基线。跳过一切工具链已强制的内容。控制在 400 词以内。」Spec 子代理提示词必须包含diff 命令与提交清单规格的路径或已获取的内容简报「报告(a) 规格要求但缺失或仅部分实现的需求(b) diff 中并未被要求的行为范围蔓延(c) 看起来已实现但实现疑似有误的需求。每条发现引用规格原文行。控制在 400 词以内。」如果规格缺失跳过 Spec 子代理并在最终报告中注明。第五步汇总将两份报告分别呈现在## Standards与## Spec标题下逐字或轻度清理后呈现绝不合并、绝不重排发现。理由见下节「为什么双轴分离」。最后以一行总结收尾每条轴的发现总数以及每条轴内部最严重的问题如果有。拒绝跨轴选出一个「总冠军」那正是双轴分离要阻止的重排。为什么双轴分离一份改动可能通过一条轴而挂掉另一条轴遵循了所有标准但实现错了东西 →Standards 过Spec 挂完全按 issue 做了但破坏了项目约定 →Spec 过Standards 挂。分开报告就是为了防止其中一条轴掩盖另一条轴。正如 docs/engineering/code-review.md 所强调的一个不了解你仓库标准的通用审查技能恰恰是这个设计要规避的东西——它只会标记你代码库中有意为之的惯例却漏掉你代码库真正依赖的不变量。所以仓库自有文档才是 Standards 轴的首要来源。从子代理入口看agents/openai.yaml 将本技能对外的展示名定义为「Code Review」、简述为「Review a diff on standards and spec」与 SKILL.md 的 frontmattername: code-review保持一致。作为 Model-invoked 技能它的触发词设计得足够丰富让模型在「review a branch / a PR / work in progress / since X」等场景下能自然命中。常见问题与 Claude Code 内置/code-review冲突怎么办这是该技能被反馈最多的问题且官方并未修复。Claude Code 自带的/code-review做的是另一件事在 diff 里猎 bug空指针路径、竞态、off-by-one而本技能检查的是规格合规与仓库标准。安装本技能库后必有一方胜出胜出方取决于安装方式通过插件市场安装时一切技能都被别名到mattpocock-skills:前缀下内置技能在无前缀名上变得难以触达通过普通 skills 安装时本地文件胜出本技能遮蔽内置技能。一个干净的解法是彻底移除 Claude Code 的内置技能这还能省下大量上下文遮蔽行为本身也可视为 harness 的一个缺陷技能作者理应能自由命名技能因此另一个答案是给本地副本改名。注意修改 frontmatter 或重命名目录会在npx skills update时被还原用户报告过的持久方案是把技能 fork 成新名字、并从受管集合中剔除code-review同时记下 fork 时的 commit以便日后手动重新同步。它的子代理反复调用/code-review导致代理爆炸这是已知开放 bug多人、多个 harness 上都能复现。Standards 与 Spec 的提示词没有禁止委派因此子代理可能重新发现该技能并再次扩散有报告称一次审查扩散到 50 多个代理。社区在 fork 上的修复是在两份子代理简报末尾各追加一行「Do not invoke/code-reviewor spawn additional agents: perform this review directly.」。也有人倾向于在 harness 层处理让所有技能都继承这道闸。两种方案目前都未进入官方发布版。无人值守运行时请盯紧代理计数。应该在与写代码相同的会话里跑吗最好开一个新会话。一位读者的话很精辟「同一上下文审查自己那不是审查那是带斜杠命令的确认偏差。」在写作会话里的审查代理持有塑造了这段代码的全部假设——而独立审查者恰恰不该拥有这些假设。这也是为什么有人会要求 implement 不带其内置审查步骤它是在刚写出 diff 的同一个会话里执行审查的。从干净会话手动执行/code-review才是诚实的版本。每个工单都审还是分支末尾审一次两种都成立技能不替你决定。按工单逐个审能让每份 diff 足够小Spec 轴有且只有一个清晰的规格可对照这也是implement采用的模式。攒到分支末尾一次审则能捕捉到逐个工单审查各自错过的工单间交互。拿不准的话按工单审一遍再对着分支点跑一次最终审查。能信任发现吗不能不做核查就信。子代理输出是假设不是证据有团队报告文本式审查放过了一打破坏性变更而这些被本技能抓到了。技能对两份报告是逐字或轻度清理地汇总并不会逐条核对文件因此一条发现可能引用了错误位置或夸大影响。动手前先读每条发现附带的引用。正是因为每条发现都强制携带引用一条标准规则、一个坏味道加 hunk、或一行规格原文这套报告才是可核查的。为什么每次跑都能找到新问题因为修复会制造新的表面surface也因为 Standards 轴的判断性那一半在两次运行之间并非确定性的。一位读者把循环描述得很直白「/code-review 和 /improve-code-architecture 每次都找到新东西。我修完重跑又出新东西。」不存在收敛保证。把一次通过当作一份线索清单处理那些背后有明确规则引用的项然后停止不要循环跑到它干净为止因为它不会干净。它审查未提交的工作吗不。它做的是git diff fixed-point...HEAD三点式对比从 merge-base 起算排除了暂存区与工作区改动。如果implement没做中间提交即将提交的工作对审查不可见。先提交、再审查、之后 amend 或补 fixup。它工作正常的标志用以下验收标准判断一次执行是否符合设计坏引用或空 diff 时在任何子代理派生之前就拒绝启动报告以## Standards和## Spec两个独立区块呈现而不是一张合并清单每条 Standards 发现要么点名仓库文件中的一条规则要么点名十二条坏味道之一并引用 hunk每条 Spec 发现引用规格原文的一行结尾总结给出每条轴的最严重问题并拒绝选出跨轴的总冠军没有规格可用时Spec 区块如实说明而不是列出从代码里推断出来的需求。在技能链中的位置code-review位于构建链末尾的审查环节grill-with-docs → to-spec → to-tickets → implement → code-review它也可以独立指向任何分支或 PR。具体关系implement 是最近的邻居它驱动整个构建并在提交前调用本技能作为自己的收尾审查其 SKILL.md 明确写着「Once done, use /code-review to review the work」to-spec 与 to-tickets 生产出 Spec 轴要对照的文档一份含糊的规格会让该轴同样含糊improve-codebase-architecture 是整库级别的对应物本技能永远只看一份 diff。当你拿不准某个处境该用哪个技能时ask-matt 作为路由技能负责跨整个技能集导航。对于任何想要「既有标准合规检查、又有规格符合性检查且两种结论互不掩盖」的代码评审需求code-review就是这个仓库给出的答案。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考