tracer-code-review

对比 HEAD 与用户提供的固定点的双轴审查：

• 标准 — 代码是否符合此仓库记录的编码标准？
• 规范 — 代码是否忠实实现了源问题 / PRD / 规范？

两个轴会作为并行子 Agent运行，避免彼此的上下文受到干扰，然后由此技能汇总其发现。每个轴都会返回按严重性分级的发现和明确的结论——只做叙述而没有结论的审查，无法指导任何人采取行动。

流程

1. 锁定固定点

用户指定的任何内容都是固定点——提交 SHA、分支名、标签、main、HEAD~5 等。如果用户没有指定，请向其询问。工作流调用方会提供自己的固定点和审查预算。

记录一次 diff 命令：git diff <fixed-point>...HEAD（使用三点语法，因此比较的是合并基点）。同时记录提交列表：git log <fixed-point>..HEAD --oneline。

继续之前，确认固定点可解析（git rev-parse <fixed-point>），且 diff 非空。无效引用或空 diff 应在此处失败，而不是在两个并行子 Agent 内失败。

2. 确定规范来源

按以下顺序查找源规范：

1. 调用方作为参数传入的路径或问题引用。
2. 提交消息中的问题引用（#123、Closes #45 等）——如果 docs/agents/issue-tracker.md 存在，则通过其中的跟踪器工作流获取。
3. docs/、specs/ 或 .tracer/ 下与分支名或功能匹配的 PRD / 规范文件。
4. 如果没有找到任何内容，请询问用户规范的位置。如果用户表示没有规范，规范子 Agent 将跳过并报告“没有可用的规范”。

3. 确定标准来源

仓库中任何记录代码编写规范的内容，例如 CODING_STANDARDS.md 或 CONTRIBUTING.md。

除了仓库文档中规定的内容，标准这一维度始终包含以下代码异味基准——一组固定的 Fowler 代码异味（Refactoring，第 3 章），即使仓库没有任何相关文档也适用。此基准受两条规则约束：

• 以仓库规范为准。 仓库中有文档记录的规范始终优先；如果规范认可了基准会标记的做法，就忽略该异味。
• 始终需要判断。 每种异味都是带标签的启发式提示（“可能存在 Feature Envy”），绝不是硬性违规——而且与这里的任何标准一样，跳过工具已强制执行的内容。

每种异味都按是什么 → 如何修复来说明；请对照 diff 检查：

• 神秘命名（Mysterious Name） — 函数、变量或类型的名称无法说明其作用或所保存的内容。→ 重命名；如果想不出恰当的名称，说明设计不清晰。
• 重复代码（Duplicated Code） — 变更中的多个代码块或文件出现相同的逻辑结构。→ 提取共用结构，并在两处调用。
• 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. 并行启动两个子 Agent

发送一条包含两个 Agent 工具调用的消息，并等待两者都返回结果。每个都使用一个全新的 general-purpose 子 Agent；Standards 和 Spec 是评审标准，不是已配置的 Agent 类型。两个提示词都附带以下前言：

核实，不要轻信。提交消息、代码注释和实现者报告都属于未经核实的说法——只根据差异内容进行判断。只读审查：绝不修改工作树、索引或 HEAD。

为每项发现评定等级：Critical（错误、数据丢失、安全问题、功能失效）、Important（修复前无法信任——行为不正确或脆弱、遗漏要求、错误被吞掉、测试没有断言任何内容），或 Minor（润色、风格、“覆盖面可以更广”）。并非所有问题都是 Critical。每项发现都要引用文件:行号，并说明其影响。最后给出结论：Approved 或 Needs fixes（任何 Critical/Important 发现都意味着 Needs fixes）。

Standards 子 Agent 提示词——还要包含：

• 完整的差异命令和提交列表。
• 步骤 3 中找到的标准来源文件列表，以及步骤 3 中的气味基线全文——子 Agent 无法通过其他方式访问这些内容。
• 简要说明：“报告——按文件/差异块（如相关）列出：(a) 差异中每一处违反文档标准的内容：引用该标准（文件 + 规则）；(b) 你发现的任何基线气味：指出其名称并引用差异块。违反文档标准的问题按其影响评定严重程度；基线气味属于判断性问题，默认评为 Minor，除非造成了明确损害（例如，逐字重复一整个逻辑块属于 Important）。文档化的仓库标准优先于基线。跳过工具已强制检查的内容。”

Spec 子 Agent 提示词——还要包含：

• 差异命令和提交列表。
• 规范文件的路径或获取到的规范内容。
• 简要说明：“报告：(a) 缺失——规范要求但未实现或仅部分实现的内容；(b) 额外——差异中未被要求的行为（范围蔓延）；(c) 理解错误——看似已实现但实现有误的要求。每项发现都要引用规范原文。缺失或理解错误的问题至少评为 Important。”

如果规范不存在，则跳过 Spec 子 Agent，并在最终报告中注明。

5. 汇总

分别在 ## Standards 和 ## Spec 标题下呈现两份报告，每份报告都以其结论收尾。不要合并或重新排序问题——这两个评审维度是刻意分开的（详见 为何采用两个维度）。

最后用一行总结：列出各维度的结论和发现数量，并分别指出各维度中的最严重问题（如有）。不要跨维度选出单一赢家——这正是将评审维度分开的目的。

6. 处理审查结果

**由工作流负责的审查：**在第 5 步后返回。由调用方负责裁定、修复和停止规则。任何进一步的审查都必须在预算内获得指派。

独立自审：如果存在已确认但尚未解决的 Critical/Important 问题，就意味着工作尚未完成——报告问题不等于解决问题。如果你产出了差异，且没有上层工作流负责其修复预算：

1. 实施前先核实。 每项问题都是一项主张——请对照代码库核查。如果某项问题不适用于此代码库（会破坏现有行为、忽略上下文、违反 YAGNI——在“正确实现”之前，先 grep 确认实际用法），请给出技术理由予以反驳，或交由用户决定；不要盲目照做。也不要为了表示赞同而赞同——先评估，再修复或反驳。
2. 一次性修复。 派出一个修复子 Agent（或直接修复），并提供已确认的 Critical/Important 问题完整列表——绝不能为每项问题各派一个修复者。修复者需重新运行覆盖相关内容的测试并报告结果。
3. 在更新后的差异上，重新审查未通过的维度。循环进行，直到两个维度都为 Approved。
4. Minor 问题：要么现在顺手修复，要么记录下来并确保用户能看到——绝不能默默丢弃。

如果用户要求审查他人的更改，请在第 5 步后停止——报告就是交付物。

为什么要分成两个维度

一项更改可能通过一个维度，却未通过另一个维度：

• 代码遵循所有标准，却实现了错误的内容 → 标准通过，规范未通过。
• 代码完全按照问题要求实现，却违反了项目约定 → 规范通过，标准未通过。

分别报告这两个维度，可以避免一个维度掩盖另一个维度。