code-refactor-review

代码重构审查

深入审查代码变更，关注复用、组合、代码库一致性，以及任何显得冗余或敷衍的内容。

第一轮检查

1. 检查完整差异：
   • 使用 git diff 检查尚未暂存的变更。
   • 如果有已暂存的变更，则使用 git diff HEAD。
   • 如果提供的是 PR URL，请先检查变更文件并了解功能流程，再审查细节。
2. 必要时梳理调用栈／数据流。不要脱离功能的整体实现孤立地审查代码行。
3. 在评判新辅助函数、组件、钩子或模式之前，先搜索代码库。优先采用邻近代码和同类代码中的模式，而不是凭空设计抽象。

审查维度

1. 复用现有代码

• 在接受新编写的代码之前，先查找现有的工具函数、组件、钩子、服务端操作、路由模式、文案模式和样式基元。
• 标记重复逻辑、复制的辅助代码，或对代码库已有功能的自定义实现。
• 优先复用现有流程，即使需要稍作扩展。
• 如果新代码创建了共享辅助函数，请确认它确实能复用，而不是仅仅把私有逻辑提取出来并冠以含糊的名称。

2. 代码库一致性

• 文件位置应与所属领域及相邻功能保持一致。对随意堆放在顶层 lib 目录中的文件保持警惕。
• 命名应准确反映代码的实际用途，并遵循同类文件／函数的命名方式。
• 除非实现细节本身就是产品／API 的区分依据，否则应避免在名称中体现实现细节。
• 采用现有的结果／错误／加载模式。如果代码库已有标准模式，不要另行设计专属的成功／失败类型。
• 面向用户的文案应与现有文案及语气一致。

3. 组合与边界

• 函数应在恰当的抽象层级上专注于一件事。
• 避免职责混杂的模块，不要把标记、API 调用、转换、UI 状态、日志记录和调度等不相关的内容混在一起。
• 避免参数过多。如果一个函数需要许多可调参数，请检查它的边界是否划分不当。
• 优先采用简单组合，避免层层嵌套回调、包装器、记忆化辅助函数和属性传递。
• 当两个底层实体以一个产品概念呈现时，应在中间组件中将它们封装为统一的传输／视图模型。黑盒组件应接收统一的属性／回调，不应关心远程与预构建等差异；只有在持久化或负载格式有要求的根组件／适配器处，才应拆分回核心实体。
• 将领域专属逻辑放在所属领域附近，除非已证明确实能跨领域复用。

4. 冗余检测

标记以下问题，并在收到要求时予以移除：

• 注释冗余：显而易见的注释、为别扭代码辩护的注释、本应通过改进代码表达得更清楚的长篇注释，以及 PR 描述中过时的背景信息。
• 辅助代码冗余：没有增加任何意义的微型包装器、仅为缩短单个函数表面长度而创建的辅助文件，以及不必要的间接层。
• 类型冗余：仅用一次却被导出的类型、自定义结果结构、在类型推断更清晰时仍添加的类型标注，以及只为掩盖别扭代码而设的类型。
• 记忆化／回调冗余：没有经过衡量或结构性理由就添加的 useMemo／useCallback。
• 副作用冗余：用于同步属性／状态、重置派生状态，或事后处理事件的副作用。
• 兼容性包袱：为了保留偶然形成的架构而附加的行为，而不是构建连贯的最终架构。
• 差异噪音：无关的重命名、格式调整、注释或包装器，只让 PR 变得更大，却没有改善设计。

5. React / Next.js 质量

• 遵循“你可能不需要 Effect”：在渲染期间派生值，将由事件触发的工作移到事件处理函数中，并在适当时通过 key 重置状态。
• 避免冗余状态和同步用的 effect。
• 不要仅仅为了缓解性能焦虑而添加记忆化。记忆化应解决实际的渲染身份或昂贵计算问题。
• 优先采用清晰的组件边界，而不是绕来绕去地处理 props 和回调。
• 对于服务端和数据代码，避免不必要的瀑布式请求；如果代码库已有相应模式，就并发执行彼此独立的工作。

6. 精简

• 优先删除代码，而不是增加新结构。
• 优先使用一个清晰的函数，而不是拆成多个类似辅助函数的小片段，除非抽取能提高复用性或可读性。
• 让修复与问题的严重程度相称。
• 除非能消除未来读者的歧义，否则不要添加架构、文档或注释。

输出格式

以结论开头：

• clean — 没有值得关注的问题。
• mostly clean — 只需少量清理。
• needs cleanup — 存在重要的复用、组合或一致性问题。

然后按优先级列出发现。每项发现都应包括：

1. 文件路径和相关符号／区域。
2. 哪些内容显得冗余或不一致。
3. 如果找到，说明应复用的现有模式或代码。
4. 建议的最小修复。

如果用户只要求审查，不要修改文件。如果用户要求修复，直接进行修改并总结改动。

危险信号

• 没有通过搜索来回答“能否复用现有代码？”
• 新增名称含糊的顶层辅助程序，例如 utils、helpers、shared，或仅针对某种实现的名称。
• 函数名称掩盖了重要的副作用。
• 某个目录只包含 index.ts，且没有合理原因。
• 重新导出已经在其他地方导出的内容。
• 产品已有组件或模式，却新增自定义原语。
• 添加大段注释来解释别扭的 props 或标志存在的原因。
• 仅为支持一个局部函数而新增多个类型。
• 如果简化状态所有权就能去掉新加的回调、记忆化或 effect 代码。

规则

• 直接、简洁。避免额外的解释性赘述。
• 不要凭空设计架构。提出的观点应以代码库中的模式为依据。
• 在声称某段代码可复用或存在不一致之前先进行搜索。
• 提出代码修改建议时，遵循目标项目的本地风格。
• 如有疑问，优先选择从左到右读起来一目了然的代码。