reviewing-code-modularity-skill

审查代码模块化

目标

降低代码复杂度，避免为了架构而架构。

改进模块归属、公共接口、信息隐藏、依赖方向和可测试的接缝。优先采用深模块，保持公共接口小而稳定，依赖方向清晰。只做能让代码更易于理解、修改和测试的最小重构，绝不做多余的事。

不可妥协的原则

这些原则适用于所有模式，也是这项技能的核心，不要弱化。

1. 在提出结构建议前，先检查实际代码及其附近的约定。不了解实际代码就给建议，通常是错的。
2. 不要按行数拆分文件。按职责拆分，否则就不要拆。
3. 除非能解决当前代码库中的复杂性，否则不要引入整洁架构、DDD、六边形分层、重度 SOLID 分层、仓库、工厂、适配器、依赖注入、端口或接口。
4. 对于只有一种实现的情况，除非确实存在测试接缝或耦合方面的压力，否则不要引入接口、工厂或 DI。
5. 如果看似重复的代码所表达的概念可能独立演进，就不要合并。重复通常胜过错误的抽象。
6. 如果局部重构就能解决问题，不要提议大范围重写。
7. 除非用户明确要求改变行为，否则应保持行为不变。
8. 除非用户提出要求，否则不要创建架构或报告文档，也不要重写 ADR。经授权的代码更改影响到现有 API 或用法文档时，应确保其准确无误。

核心术语

术语很重要或需要生成报告时，请使用一致的分析视角：模块、公共接口、实现、职责、深度、浅模块、接缝、泄漏、局部性、变更放大、为了架构而架构、建议力度。定义见 references/language.md。如果代码库对某个概念已有自己的术语，请优先使用。

确定范围

1. 遵循适用的项目说明。检查代码、附近的约定、公共导出和相关测试。如果建议范围较广或会改变边界，请阅读架构决策，参见 references/decision-records.md。
2. 对于 PR 或 diff，先确定提供的比较范围或 base/head，并阅读实际 diff。确认该范围涵盖了请求的更改；diff 为空或不可用属于检查覆盖范围的限制，并不代表审查结果良好。区分新增或恶化的问题与既有技术债。扫描某个区域时，应说明检查的区域及重要的检查缺口。
3. 沿着疑似边界检查相关调用方和依赖。确认模块负责什么、隐藏什么、调用方必须了解哪些决策，以及测试需要什么。只在需要解答明确的不确定点时扩大检查范围，默认不要扫描整个代码库。
4. 除非用户要求修改，否则审查和设计工作应保持只读。仅在用户要求时生成报告文件；只有用户明确要求 HTML 或视觉报告时，才生成 HTML。范围广泛本身并不构成创建文档的许可。

根据证据判定发现

将代码异味视为线索，而不是定论。报告发现前：

• 找出受影响的操作、当前维护问题或具体计划中的更改。追踪导致成本的依赖关系或重复知识；引用已检查的代码和相关调用方。
• 检查最有力的合理反向解释：兼容性约定、有意重复、框架惯例或有据可查的决策。包装层可能是在保护真实边界，而非增加业务逻辑。
• 比较最小且有用的干预方案与保持代码不变的方案。计入新增间接层、迁移和测试成本；仅凭文件或导出项减少，并不能证明有所改进。
• 区分影响（后果）、证据（已证实 | 有依据 | 未解决）和范围（引入／加重 | 已存在）。缺少证据意味着尚未解决，而非已被证伪。不要将未解决的线索列为可执行发现；在有帮助时，指出重要的覆盖缺口。

不要将表面偏好或对假设性增长的担忧报告为缺陷。没有可执行发现也算成功结果。这些是推理检查，并非强制的报告模板。仅在有助于判断时，加载 references/red-flags.md 或 references/principles.md 的相关部分。

模式选择

模式	适用场景	输出
A — 快速审查	审查文件、差异、PR、模块、路由、组件或小范围代码。	按风险排序的发现。不提供候选项卡片。
B — 摩擦扫描	扫描代码库或某个区域以寻找重构候选项、改进结构、查找边界，或征求首选建议。	最多四个有依据的候选项，或建议不做更改。
C — 深入分析候选项	已选定候选项，或用户要求设计公共表面／接口。	负责什么／隐藏什么／暴露什么 + 设计比较。
D — 实施	用户要求 Agent 实际进行重构。	最小且保持行为的更改 + 验证。

默认选择满足需求的最小模式。用户要求开展相关工作时，按 B → C → D 递进；仅仅范围较广并不意味着可以直接实施。明确的重构请求可以直接进入 D，无需先报告或进行设计流程。

模式 A：模块化快速审查

应用证据检查，并按影响报告可执行发现。每项发现包括：

• 影响 — 若有已证实的大量变更放大效应或有依据的正确性风险，则为高；若造成具体、反复出现的维护或测试负担，则为中；若问题真实但局部且成本低，则为低。解释后果；模式名称不能决定严重程度。
• 证据和位置 — 引用已检查代码中的文件／行号或准确符号，并区分已证实的行为与推断。说明 PR 是否引入或加重了问题；将既有技术债务单独列出。
• 为何增加复杂度 — 指出受影响的操作及其机制。
• 最小有效修复 — 保持行为不变。
• 不要更改的内容 — 仅在确实需要避免过度重构时说明。

若没有符合条件的发现，请简要说明，并附上覆盖范围说明。除非用户提出要求，否则不要使用候选项卡片。简洁的发现才是目标。

模式 B：架构摩擦扫描

探索相关区域中的摩擦点，然后使用 references/review-report.md 生成候选项报告：

• 首先给出一个首要建议，该建议也可以是保持现有结构不变。
• 提供 0–4 个符合证据检查要求的候选项；每项包括：当前摩擦点及其位置、影响／证据／范围、最小有效修复及其成本、有用的前后对比示意、测试影响、不要更改的内容，以及建议力度。不要为了凑数而添加候选项，也不要将未解决的线索提升为候选项。

默认在对话中以 Markdown 返回。若用户还要求进一步设计或实施，则在其要求的范围内继续；否则结束审查。只有在不同选项之间存在实质性取舍、需要用户判断时，才请用户选择。

模式 C：候选方案深化设计

在用户选定候选方案或要求设计公共接口时使用。输出：

1. 该模块负责什么。
2. 该模块隐藏什么。
3. 公共接口。
4. 调用方代码示例——最精简且符合实际的调用点。
5. 应保持不变的测试（行为契约）。
6. 不要重构的内容。
7. 2–4 种实质不同的设计，仅在决策并非显而易见时提供。
8. 一项建议，说明理由以及任何重要的不确定性。保留当前边界也可能是最佳选择。

对于非显而易见的比较，请加载 references/interface-design.md。如果只有一种明显的设计方案，只需提供这一种。对于成本较高的边界决策，其中的可选变更影响分析会对比在当前结构和拟议结构下，实际计划中的需求会产生什么影响。不要编造推测性的需求来证明重构的合理性。

模式 D：保持行为的实现

在用户要求实际重构时使用。编辑前：

• 根据调用方和测试，识别受影响的行为契约：输出、错误、公共签名，以及相关的副作用、顺序、事务或初始化行为。
• 使用聚焦的现有检查建立基线。记录已有失败。如果重要的受影响行为尚未覆盖，请添加一个小型特征化检查，其预期应基于现有契约；不要将已知 bug 固化为预期行为。
• 如果无法运行检查，请说明限制，并依据可用证据进行判断，不要声称已验证等价性。

然后：

• 进行能够实现所选设计的最小化且保持行为的变更。
• 保持公共 API 和调用方可见的语义不变，除非用户明确要求更改契约；对于此类更改，请更新受影响的调用方、测试和使用文档。不要凭空添加身份验证、审计、重试、校验或错误处理行为，来为新层赋予用途。将用户要求的行为变更与结构调整分开。
• 谨慎更新导入；移动代码前先检查调用方。
• 不要夹带无关清理。
• 遵循候选方案中的“不要更改”约束。
• 然后进行验证。

结束时说明：更改了什么、为什么结构更好、运行了哪些检查，以及剩余风险。对于微小更改，可将这些内容合并为简短段落。

验证

编辑后：

1. 重新运行基线检查和受影响的行为测试；如果边界发生变化，也要运行调用方测试。
2. 使用项目相关的类型检查、lint 和导入／依赖边界检查。只有存在具体的剩余风险或项目要求的门禁时才扩大验证范围，而不只是因为还有其他命令可用。
3. 检查最终差异，确认没有混入无关重构。
4. 如果无法运行验证，请明确说明。

参考资料加载

采用渐进式披露。相对于此技能所在目录解析这些路径，而不是相对于正在审查的项目解析。如果不确定应查阅哪个部分，请使用 rg '^## ' <skill-directory>/references/*.md（或等效的文件读取方式）列出参考资料的标题，然后阅读相关部分。应用参考资料的内容；不要复述它们。评测夹具和评分标准属于开发资料，不是运行时参考资料。

• references/principles.md — 设计权衡：深模块、信息隐藏、依赖方向、抽象纪律、文件拆分。
• references/red-flags.md — 可疑问题；只阅读相关的编号条目。
• references/examples.md — 当附近没有足够的项目模式可供参考时，查看具体的重组示例。
• references/language.md — 术语重要或需要撰写报告时使用的通用词汇。
• references/review-report.md — 候选方案报告格式（模式 B）；除非另有要求，不用于模式 A 快速审查。
• references/interface-design.md — 针对选定候选方案的设计探索（模式 C）。
• references/decision-records.md — 提出广泛建议前，了解项目背景和架构决策记录。