code-refactor-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Refactor Review

代码重构审查

Review code changes deeply for reuse, composition, codebase consistency, and anything that reads like slop.

深度审查代码变更，重点关注复用性、组合性、代码库一致性以及各类冗余问题。

First Pass

初步检查

Inspect the full diff:
- Use
```
git diff
```
  for unstaged changes.
- Use
```
git diff HEAD
```
  if there are staged changes.
- For a PR URL, inspect the changed files and understand the feature flow before reviewing details.
Build the call stack / data flow when useful. Do not review isolated lines without understanding how the feature is wired.
Search the codebase before judging new helpers, components, hooks, or patterns. Prefer nearby and sibling patterns over invented abstractions.

查看完整差异：
- 对于未暂存的变更，使用
```
git diff
```
  。
- 若存在已暂存的变更，使用
```
git diff HEAD
```
  。
- 对于PR链接，先查看变更文件并理解功能流程，再进行细节审查。
必要时梳理调用栈/数据流。切勿脱离功能的整体关联，孤立审查单行代码。
在评判新的辅助函数、组件、hooks或模式前，先搜索代码库。优先采用已有相近或同类模式，而非自行创造抽象。

Review Lenses

审查视角

1. Reuse Existing Code

1. 复用现有代码

Look for existing utilities, components, hooks, server actions, route patterns, copy patterns, and styling primitives before accepting newly written code.
Flag duplicated logic, copied helpers, or custom implementations of things the codebase already has.
Prefer reusing the existing flow even if it needs a small extension.
If the new code creates a shared helper, verify it has real reuse and is not just extracted private logic with a vague name.

在接受新编写的代码前，先查找是否存在可用的现有工具、组件、hooks、服务端操作、路由模式、文案模板和样式基础组件。
标记重复逻辑、复制的辅助函数，或代码库中已实现功能的自定义重复实现。
优先复用现有流程，即便需要少量扩展。
若新代码创建了共享辅助函数，需确认它确实有实际复用价值，而非仅仅提取了私有逻辑并使用模糊命名。

2. Codebase Consistency

2. 代码库一致性

File placement should match the domain and neighboring features. Be suspicious of random top-level
```
lib
```
dumps.
Naming should match what the code actually does and follow sibling file/function names.
Avoid implementation details in names unless they are the actual product/API distinction.
Use existing result/error/loading patterns. Do not invent bespoke success/failure types when the codebase has a standard one.
Match existing copy and tone for user-facing text.

文件存放位置应匹配业务领域及相邻功能。对随意放在顶级
```
lib
```
目录的文件保持警惕。
命名应准确反映代码实际功能，并遵循同类文件/函数的命名规则。
除非是产品/API的核心区别，否则避免在命名中体现实现细节。
使用现有的结果/错误/加载状态模式。当代码库已有标准实现时，不要自行定制成功/失败类型。
用户面向文本需匹配现有文案风格和语气。

3. Composition and Boundaries

3. 组合与边界

Functions should do one thing at the right level of abstraction.
Avoid grab-bag modules that mix unrelated concerns like flags, API calls, transformation, UI state, logging, and scheduling.
Avoid parameter sprawl. If a function needs many knobs, check whether the boundary is wrong.
Prefer simple composition over chains of callbacks, wrappers, memoized helpers, and prop plumbing.
When two backing entities are presented as one product concept, package them into one transport/view model across intermediate components. Black-box components should receive one unified prop/callback and should not care about distinctions like remote vs prebuilt; split back into core entities only at roots/adapters where persistence or payload formats require it.
Keep domain-specific logic close to its domain unless there is proven cross-domain reuse.

函数应单一职责，并处于合适的抽象层级。
避免混合无关关注点的“大杂烩”模块，比如同时包含标志位、API调用、数据转换、UI状态、日志和调度逻辑的模块。
避免参数过多。若函数需要大量参数，检查是否边界划分有误。
优先采用简单组合，而非回调链、包装器、记忆化辅助函数和属性传递的复杂结构。
当两个底层实体被作为一个产品概念呈现时，在中间组件层将它们打包为统一的传输/视图模型。黑盒组件应接收统一的属性/回调，无需关心远程 vs 预构建这类区分；仅在根/适配器层，当持久化或负载格式要求时，再拆分为核心实体。
领域特定逻辑应贴近其所属领域，除非已证明存在跨领域复用需求。

4. Slop Detection

4. 冗余检测

Flag and, when asked, remove:

Comment slop: obvious comments, comments defending awkward code, long comments that should become clearer code, stale context in PR descriptions.
Helper slop: tiny wrappers that add no meaning, helper files created only to make one function look shorter, unnecessary indirection.
Type slop: exported one-off types, custom result shapes, annotations where inference is clearer, types that only paper over awkward code.
Memo/callback slop:
```
useMemo
```
/
```
useCallback
```
added without a measured or structural reason.
Effect slop: effects that mirror props/state, reset derived state, or handle events after the fact.
Compatibility cruft: bolted-on behavior that preserves accidental architecture instead of building the coherent end state.
Diff churn: unrelated renames, formatting, comments, or wrappers that make the PR larger without improving the design.

标记并在要求时移除以下冗余：

注释冗余：显而易见的注释、为糟糕代码辩护的注释、应通过清晰代码替代的长篇注释、PR描述中过时的上下文信息。
辅助函数冗余：无意义的微小包装器、仅为简化单个函数而创建的辅助文件、不必要的间接调用。
类型冗余：导出的一次性类型、自定义结果结构、可通过类型推断更清晰表达的注解、仅用于掩盖糟糕代码的类型。
记忆化/回调冗余：无实际测量或结构性理由而添加的
```
useMemo
```
/
```
useCallback
```
。
副作用冗余：镜像属性/状态、重置派生状态、事后处理事件的副作用。
兼容性冗余：为保留不合理架构而临时添加的行为，而非构建连贯的最终状态。
差异混乱：无关的重命名、格式化、注释或包装器，使PR体积增大却未改进设计。

5. React / Next.js Quality

5. React / Next.js 质量

Apply “You Might Not Need an Effect”: derive values during render, move event-caused work into event handlers, and reset state with keys when appropriate.
Avoid redundant state and synchronization effects.
Do not add memoization just to quiet performance anxiety. Memoization should solve a real render identity or expensive computation issue.
Prefer straightforward component boundaries over prop/callback gymnastics.
For server/data code, avoid unnecessary waterfalls and run independent work concurrently when the codebase has a pattern for it.

遵循“You Might Not Need an Effect”原则：在渲染时推导值，将事件触发的工作移至事件处理器，必要时通过key重置状态。
避免冗余状态和同步副作用。
不要仅因性能焦虑而添加记忆化。记忆化应解决实际的渲染标识或昂贵计算问题。
优先采用清晰的组件边界，而非复杂的属性/回调操作。
对于服务端/数据代码，避免不必要的请求瀑布流，若代码库有对应模式，可并发执行独立任务。

6. Minimality

6. 极简性

Prefer deleting code over adding new structure.
Prefer one clear function over several helper-y fragments unless extraction improves reuse or readability.
Keep the fix proportional to the problem.
Do not add architecture, docs, or comments unless they remove ambiguity for future readers.

优先删除代码，而非添加新结构。
优先采用单个清晰的函数，而非多个辅助片段，除非提取能提升复用性或可读性。
修复方案应与问题规模匹配。
除非能为未来读者消除歧义，否则不要添加架构、文档或注释。

Output Format

输出格式

Start with a verdict:

```
clean
```
— no meaningful concerns.
```
mostly clean
```
— minor cleanup only.
```
needs cleanup
```
— important reuse/composition/consistency issues.

Then list findings by priority. For each finding include:

File path and relevant symbol/area.
What reads as slop or inconsistency.
The existing pattern or code that should be reused, if found.
The minimal recommended fix.

If the user asked for review only, do not edit files. If the user asked to fix it, make the changes directly and summarize what changed.

先给出结论：

```
clean
```
— 无重大问题。
```
mostly clean
```
— 仅需少量清理。
```
needs cleanup
```
— 存在重要的复用/组合/一致性问题。

然后按优先级列出发现的问题。每个问题需包含：

文件路径及相关符号/区域。
被判定为冗余或不一致的内容。
若存在，应复用的现有模式或代码。
推荐的最小修复方案。

若用户仅要求审查，请勿编辑文件。若用户要求修复，直接进行修改并总结变更内容。

Red Flags

警示信号

“Can we reuse existing code?” was not answered with a search.
New top-level helpers with vague names like
```
utils
```
,
```
helpers
```
,
```
shared
```
, or implementation-specific names.
A function whose name hides important side effects.
A directory containing only
```
index.ts
```
without a reason.
Re-exporting something that is already exported elsewhere.
New custom primitives where the product already has a component or pattern.
Large comments explaining why awkward props or flags exist.
Multiple new types just to support one local function.
New callback/memo/effect code that disappears if state ownership is simplified.

未通过搜索就回答“是否可复用现有代码”的问题。
命名模糊的新顶级辅助函数，如
```
utils
```
、
```
helpers
```
、
```
shared
```
，或基于实现细节命名的函数。
名称隐藏重要副作用的函数。
仅包含
```
index.ts
```
且无合理理由的目录。
重新导出已在其他地方导出的内容。
在产品已有组件或模式的情况下，创建新的自定义基础组件。
用于解释糟糕属性或标志位存在原因的长篇注释。
仅为支持单个本地函数而创建的多个新类型。
若简化状态归属即可消除的新回调/记忆化/副作用代码。

Rules

规则

Be direct and concise. Avoid extra explanatory fluff.
Do not invent architecture. Ground claims in codebase patterns.
Search before claiming something is reusable or inconsistent.
If a pattern is not present in the codebase, say so and recommend the smallest clean alternative.
Follow the target project's local style when suggesting code changes.
When in doubt, optimize for code that reads obvious from left to right.

直接简洁。避免多余的解释性内容。
不要自行创造架构。所有结论需基于代码库现有模式。
在声称某内容可复用或不一致前，先进行搜索。
若代码库中不存在对应模式，需说明并推荐最简洁的替代方案。
建议代码变更时遵循目标项目的本地风格。
存疑时，优先优化为从左到右阅读清晰易懂的代码。