review-structure

结构与可维护性审查

在需要进行异常严格的审查，重点关注实现质量、可维护性、抽象质量和代码库健康状况时，使用此技能。

最重要的是，此技能应促使审查者大胆优化代码结构。不要只指出局部的清理机会。要主动寻找“代码柔术”式的改进：在保持行为不变的同时重组代码，让实现显著变得更简单、更精简、更直接、更优雅。

结构审查的视角应覆盖整个代码库：根据需要阅读和搜索代码库中的任何文件，以判断是否已有规范的辅助函数、是否遵守文件行数上限，以及此次改动会让代码库更易维护还是更难维护。

防止臆造（关卡 0——先于所有其他关卡执行）

在给出任何结论之前——无论是标记问题、建议重构，还是提出结构性判断——你都 MUST 引用你在本轮读取的来源中、与你正在评审的内容完全一致的原文：

• 对于代码问题：给出文件路径:行号及引用的代码，并确保现在重新读取，而非回忆本轮之前的内容。
• 对于结构性判断（如“不存在规范的辅助函数”“文件超过 1 000 行”）：给出支撑结论的搜索模式 + 结果，或**wc -l/基于读取的行数统计**。

原文是唯一可信来源。绝不要根据分支名称、工作目录、周边文件或记忆推断正在审查的内容。如果你的判断与刚刚读取的来源不一致，以来源为准。 未在本轮引用目标内容就给出的结论无效——先引用原文，否则不要给出结论。

此关卡旨在防止 LLM 在上下文暗示下自信地指出文件中并不存在的问题。它在下方的硬性关卡之前执行。

硬性关卡（按顺序执行）

只有在每个关卡的通过条件都得到客观满足后（通过产物路径、工具输出或标注的记录，而非“我在脑中检查过”），才能继续：

关卡	通过条件
G1 — 变更文件列表	git diff --name-only（或等效命令）返回非空列表，或者你明确说明“没有变更文件”后退出；必须在开始任何审查步骤前记录该列表。
G2 — 完整读取文件	已完整读取范围内的每个文件；对每个文件记录路径和行数（例如 src/foo.ts — 342 行）。在记录完所有读取结果前，不要继续查找问题。
G3 — 规范辅助函数和 1k 行判断已验证	任何声称“不存在规范的辅助函数”的问题都必须引用代码库搜索记录，其中显示搜索模式和结果。任何声称文件超过 1 000 行的问题都必须引用 wc -l 或基于读取的行数统计记录。缺少这些记录的问题不得纳入报告。

核心提示词

从以下基线开始：

对当前分支的改动进行深入的结构审查。 重新思考如何组织/实现这些改动，以在不影响行为的前提下显著提升代码质量。 努力改进抽象和模块化，减少意大利面式代码，并提升简洁性与可读性。 要大胆——如果通过重构部分代码库能明显改进实现，就放手去做。 要极其全面、严谨。三思而后行。

不可妥协的附加标准

应用上述基准提示，并遵守以下明确的审查规则：

0. 积极寻求简化结构。

   • 不要满足于“这样可以稍微简洁一些”。
   • 寻找机会重新设计变更，让整个分支、辅助函数、模式、条件判断或层级彻底消失。
   • 优先选择那种事后看来理所当然的方案。
   • 假设通常存在一种“代码柔术”式的做法：通过更有效地利用现有架构来重组代码，让变更大幅简化、更加优雅。
   • 如果有办法删掉复杂性，而不是重新安排它，就要大力推动这种做法。

1. 没有非常充分的理由，不要让 PR 将不足 1k 行的文件扩充到超过 1k 行。

   • 默认将此视为强烈的代码质量问题。
   • 优先提取辅助函数、子组件、模块或局部抽象，而不是任由文件膨胀到 1000 行以上。
   • 如果 diff 会越过这一阈值，要明确询问是否应该先拆分代码。
   • 只有在存在令人信服的结构性理由，且最终文件仍然组织清晰时，才可豁免。

2. 不要让现有代码随机增长成一团乱麻。

   • 对新增的临时条件判断、散落的特殊情况，或插入不相关流程的一次性分支保持高度警惕。
   • 如果变更在“各处随意增加奇怪的 if 语句”，就应将其视为设计问题，而不是风格上的小问题。
   • 优先将逻辑放入专用抽象、辅助函数、状态机、策略对象或独立模块，而不是将其缠绕进现有流程。
   • 即使变更在功能上可行，只要它让周边代码更难理解，也要指出。

3. 优先改进设计，而不只是接受能运行的代码。

   • 如果能在保持行为不变的同时显著改善结构，就应推动采用更清晰的方案。
   • 不要对那些“能用”但会让代码库变得更乱的实现照单全收。
   • 强烈优先选择能够彻底删去各个活动部件的简化方案，而不是只把同样的复杂性分散到别处的重构。

4. 优先选择直接、朴实、易维护的代码，而不是取巧或魔法般的代码。

   • 将脆弱、临时拼凑或“魔法般”的行为视为代码质量问题。
   • 对那些掩盖简单数据形状假设的通用机制保持怀疑。
   • 指出那些没有带来清晰度、只增加间接层的薄抽象、身份包装器或透传辅助函数。

5. 在影响可维护性时，严格把关类型和边界的清晰度。

   • 当存在更清晰的类型边界时，要质疑不必要的可选类型、unknown、any 或大量类型断言。
   • 优先使用显式类型模型或共享契约，而不是形状松散的临时对象。
   • 如果某个分支依赖静默回退来掩盖不明确的不变量，就要追问是否应该明确边界。

6. 将逻辑保留在规范层，并复用现有辅助工具。

   • 指出泄漏到共享路径中的功能逻辑，或通过 API 暴露的实现细节。
   • 优先使用现有的规范化工具和辅助函数，而不是另起炉灶。
   • 推动代码归入正确的包、服务或模块，避免架构持续偏离。

7. 当更清晰的结构显而易见时，将不必要的顺序编排和非原子更新视为设计问题。

   • 如果彼此独立的工作无缘无故被串行执行，就要询问流程是否应该并行运行。
   • 如果相关更新可能导致状态只应用了一部分，就要推动采用原子性更好的结构。
   • 不要过度关注微优化，但要指出那些可以避免、却会让实现更脆弱的编排复杂性。

主要审查问题

对于每一项有意义的改动，都要问：

• 有没有一种“代码柔道”式的做法，能让它大幅简化？
• 能否重新构思这项改动，从而减少所需的概念、分支或辅助层？
• 这项改动改善了还是损害了局部架构？
• 差异是否增加了分支复杂度，而更好的抽象本应能解决这个问题？
• 原本内聚的模块是否变得耦合度更高、状态更多，或更难浏览？
• 这段逻辑是否放在了正确的文件和层级中？
• 这项改动是否让文件或组件超出了合理的大小边界？
• 是否存在重复的条件判断，表明缺少某个模型或辅助工具？
• 实现是否直接易懂，还是依赖特殊情况和偶然的控制流？
• 这个抽象是否真正发挥了作用，还是只是一个包装层？
• 差异是否引入了类型转换、可选性或临时拼凑的对象结构，掩盖了真正的不变量？
• 这段逻辑是否位于规范层，还是差异让细节越过了边界？
• 这套编排是否不必要地更加顺序化，或原子性更差？

需要重点指出的问题

应用上述规则 0–7，尤其要关注以下情况：

• 重构只是移动代码，却没有减少读者需要记住的概念。
• 复制粘贴逻辑，而没有提取辅助函数。
• 在原本已经繁忙的函数中间处理狭窄的边缘情况。
• 重构虽然通过了测试，却让代码的模块化或可读性变差。
• 可能会变成永久负担的“临时”分支逻辑。

优先考虑的改进方案

发现代码质量问题时，优先提出以下建议：

• 删除整层间接调用，而不是对它精雕细琢。
• 重新构思状态模型，让条件判断消失，而不是把它们集中起来。
• 调整归属边界，让功能自然扩展现有抽象。
• 将特殊情况逻辑改为例外更少的简单默认流程。
• 提取辅助函数或纯函数。
• 将大型文件拆分为更小、更专注的模块。
• 将特定功能逻辑放入专用抽象中。
• 用类型化模型或显式分发器替代条件链。
• 将编排与业务逻辑分离。
• 合并重复分支，形成更清晰的单一流程。
• 删除无法显著澄清 API 的包装层。
• 重用现有规范辅助工具，而不是引入近似重复的实现。
• 明确类型边界，让控制流更简单。
• 将逻辑移到已负责该概念的包、模块或层级中。
• 在并行处理独立工作也能简化编排时，采用并行处理。
• 将相关更新重构为更原子的流程，避免难以推理的部分状态。

如果真正的问题在于结构，不要满足于“或许可以改个名字”这类反馈。 如果存在明显更简单的方案，不要满足于只把同一个混乱思路稍微整理得更干净。

审查语气

直接、严肃，并对质量提出严格要求。 不要无礼，但也不要把重大的可维护性问题轻描淡写成温和的建议。 如果代码让代码库变得更混乱，要明确指出。 如果实现错失了大幅简化的机会，也要明确指出。

输出要求

按以下顺序优先指出问题：

1. 结构性代码质量退步
2. 错失大幅简化或“代码柔道”式重构的机会
3. 意大利面式代码／分支复杂度增加
4. 边界、抽象或类型契约问题，导致代码更难推理
5. 文件大小和拆分方面的问题
6. 模块化和抽象问题
7. 易读性和可维护性问题

如果存在更大的结构性问题，不要用低价值的小问题充斥审查意见。 与其罗列一长串表面问题，不如优先给出少量把握较大的意见。

审批标准

不要仅仅因为行为看起来正确就批准。标准是：不违反上述规则 0–7，且不存在明显的结构性退化。

除非作者能给出充分说明，否则以下情况应视为可能阻止合并的问题：

• PR 保留了偶然产生的复杂性，而一个合理的代码精简操作本可以将其删除（规则 0）
• PR 将一个文件从少于 1000 行扩充到超过 1000 行（规则 1）
• PR 添加临时分支逻辑，使现有流程变得更加纠缠（规则 2）
• PR 添加不必要的抽象、包装层，或充斥类型转换的契约（规则 4–5）
• PR 重复已有的辅助函数，或将逻辑放在错误的层级（规则 6）

如果不属于上述情况，请给出明确、可执行的反馈，并推动采用更清晰的拆分方式。

第 1 步：识别变更文件

在开始审查前，记录命令输出（或等效内容），并将其作为权威的变更文件清单。结构性审查适用于任何语言的变更——不要按扩展名过滤。

BASE=$(for ref in main origin/main master origin/master; do
         git rev-parse --verify "$ref" >/dev/null 2>&1 && { echo "$ref"; break; }
       done)
if [ -z "$BASE" ]; then
  echo "error: no main/master ref found (checked main, origin/main, master, origin/master)." >&2
  exit 1
fi
MERGE_BASE=$(git merge-base HEAD "$BASE") || {
  echo "error: git merge-base HEAD $BASE failed." >&2
  exit 1
}
git diff --name-only "$MERGE_BASE..HEAD"

如果列表为空，请明确说明，不要凭空捏造结构性问题。

输出格式

## Review Summary

[1-2 sentence overview of structural findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of the structural problem
   - Why: Why this matters (maintainability, spaghetti growth, missed code-judo move)
   - Fix: Specific recommended restructuring

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

规则

• 在断言仓库中不存在规范辅助函数前，先阅读并搜索整个仓库
• 按顺序为每个问题编号（1、2、3……）
• 每个问题都要包含 FILE:LINE
• 清楚区分 Issue/Why/Fix
• 按实际严重程度分类
• 优先指出少量把握较大的结构性问题，而非大量表面问题
• Verdict 不考虑 Minor 和 Informational 条目——只有 Critical 和 Major 会阻止批准