code-refiner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Refiner

A structured, multi-pass code refinement skill that transforms complex, verbose, or tangled code into clean, idiomatic, maintainable implementations — without changing what the code does.

这是一个结构化的多轮代码优化技能，可将复杂、冗长或混乱的代码转换为简洁、符合语言规范、易于维护的实现——同时完全不改变代码的功能。

Philosophy

核心理念

The goal is not fewer lines. The goal is code that a tired engineer at 2am can read, understand, and safely modify. Every change must pass three tests:

Behavioral equivalence — identical inputs produce identical outputs, side effects, and errors
Cognitive load reduction — a reader unfamiliar with the code understands it faster after the change
Maintenance leverage — the change makes future modifications easier, not harder

When clarity and brevity conflict, clarity wins. When idiom and explicitness conflict, consider the team's experience level. When DRY and locality conflict, prefer locality for code read more than modified.

我们的目标不是减少代码行数，而是让凌晨2点疲惫的工程师也能轻松阅读、理解并安全修改代码。每一处修改都必须通过三项测试：

行为等价性——相同输入必须产生完全相同的输出、副作用和错误
认知负荷降低——不熟悉代码的人在修改后能更快理解其逻辑
维护便利性提升——修改需让未来的代码变更更简单，而非更困难

当清晰度与简洁性冲突时，优先选择清晰度。当语言规范与显式性冲突时，需考虑团队的经验水平。当DRY（Don't Repeat Yourself）原则与代码局部性冲突时，对于阅读频率高于修改频率的代码，优先选择局部性。

Prerequisites

前置条件

git — used in Phase 1 for scope detection (
```
git diff
```
) when the user doesn't specify target files
Python 3.10+ — required to run
```
scripts/complexity_report.py
```
for quantitative complexity metrics

git——在第一阶段用于范围检测（
```
git diff
```
），当用户未指定目标文件时使用
Python 3.10+——运行
```
scripts/complexity_report.py
```
以获取量化复杂度指标的必要环境

Workflow

工作流程

Follow this sequence. Each phase builds on the previous one. Do not skip phases, but adapt depth to the scope of the request (a single function gets a lighter pass than a full module).

请遵循以下步骤，每个阶段都建立在前一阶段的基础上。不要跳过阶段，但可根据请求的范围调整深度（单个函数的优化比整个模块更轻量化）。

Phase 1: Reconnaissance

阶段1：侦察分析

Before touching anything, build a mental model:

Identify scope — What files/functions are in play? If the user hasn't specified, check recent git modifications:
```
git diff --name-only HEAD~5
```
or
```
git diff --staged --name-only
```
Detect language and ecosystem — Read file extensions, imports, config files (package.json, pyproject.toml, go.mod, Cargo.toml). Load the appropriate language reference from
```
references/
```
if needed for idiom-specific guidance
Read project conventions — Check for CLAUDE.md, .editorconfig, linter configs (eslint, ruff, golangci-lint, clippy). These override generic idiom preferences
Understand test coverage — Locate test files. If tests exist, note the test runner so you can verify behavioral equivalence after changes
Baseline complexity snapshot — For each target function/method, mentally note:
- Nesting depth (max indentation levels)
- Number of branches (if/else/match/switch arms)
- Number of early returns vs single-exit
- Parameter count
- Lines of code
- Number of responsibilities (does it do more than one thing?)

在修改任何代码之前，先建立对代码的整体认知：

确定范围——涉及哪些文件/函数？如果用户未指定，检查最近的git修改：
```
git diff --name-only HEAD~5
```
或
```
git diff --staged --name-only
```
检测语言与生态——读取文件扩展名、导入语句、配置文件（package.json、pyproject.toml、go.mod、Cargo.toml）。如需特定语言规范的指导，可从
```
references/
```
目录加载对应的语言参考文档
了解项目约定——检查CLAUDE.md、.editorconfig、代码检查工具配置（eslint、ruff、golangci-lint、clippy）。这些配置会覆盖通用的语言规范偏好
理解测试覆盖情况——定位测试文件。如果存在测试，记录测试运行器，以便在修改后验证行为等价性
复杂度基线快照——为每个目标函数/方法记录以下信息：
- 嵌套深度（最大缩进层级）
- 分支数量（if/else/match/switch分支）
- 提前返回与单一出口的数量
- 参数数量
- 代码行数
- 职责数量（是否承担了超过一项功能？）

Phase 2: Structural Analysis

阶段2：结构分析

Identify what's actually wrong before reaching for solutions. Categorize issues by severity:

Critical (always fix):

Dead code (unreachable branches, unused variables/imports)
Redundant operations (double-checking the same condition, re-computing cached values)
Logic that can be replaced by a stdlib/language built-in
Mutation of shared state that could be avoided

High (fix unless there's a clear reason not to):

Functions with >3 levels of nesting
Functions with >5 parameters
God functions (>40 lines or >3 responsibilities)
Repeated code blocks (3+ occurrences of similar logic)
Inverted or confusing boolean logic
Stringly-typed enumerations

Medium (fix when it improves clarity without adding risk):

Unclear variable/function names
Missing or misleading type annotations
Unnecessary intermediate variables
Over-abstraction (wrappers that add no value)
Comments that restate the code instead of explaining why

Low (fix only in a dedicated cleanup pass):

Inconsistent formatting (defer to linter)
Import ordering
Trailing whitespace, line length

在寻找解决方案之前，先明确实际存在的问题。按严重程度对问题分类：

严重问题（必须修复）：

死代码（不可达分支、未使用的变量/导入）
冗余操作（重复检查同一条件、重新计算已缓存的值）
可被标准库/语言内置功能替代的逻辑
可避免的共享状态修改

高优先级问题（除非有明确理由否则必须修复）：

嵌套层级超过3层的函数
参数数量超过5个的函数
上帝函数（超过40行或承担3项以上职责）
重复代码块（相同逻辑出现3次及以上）
反转或易混淆的布尔逻辑
基于字符串的枚举类型

中优先级问题（当能提升清晰度且无风险时修复）：

不清晰的变量/函数名称
缺失或误导性的类型注解
不必要的中间变量
过度抽象（无实际价值的包装函数）
重复代码本身的注释（保留解释「为什么」的注释）

低优先级问题（仅在专门的清理任务中修复）：

不一致的格式（遵循代码检查工具的规则）
导入语句顺序
尾随空格、行长度问题

Phase 3: Refactoring Execution

阶段3：重构执行

Apply changes using these tactics, ordered by impact-to-risk ratio:

按影响-风险比从高到低的顺序应用以下重构策略：

3a. Eliminate Dead Weight

3a. 清除冗余代码

Remove before restructuring. Less code = less to think about.

Delete unused imports, variables, functions
Remove unreachable branches (but verify they're truly unreachable)
Strip comments that restate the obvious (keep comments that explain why)
Remove no-op wrapper functions that just forward calls

在重构前先移除冗余部分。代码越少，需要思考的内容越少。

删除未使用的导入、变量、函数
移除不可达分支（但需确认其确实不可达）
删除重复代码本身的注释（保留解释「为什么」的注释）
移除仅转发调用的无操作包装函数

3b. Flatten Structure

3b. 扁平化结构

Reduce nesting and cognitive load:

Guard clauses: Convert deep
```
if
```
nesting to early returns
Extract conditions: Name complex boolean expressions (
```
is_valid_order = ...
```
)
Decompose loops: If a loop does filter + transform + accumulate, break it apart (or use language-appropriate constructs: list comprehensions, iterators, streams)
Invert conditionals: When the
```
else
```
branch is the "happy path", flip it

减少嵌套层级与认知负荷：

守卫子句：将深层
```
if
```
嵌套转换为提前返回
提取条件：为复杂的布尔表达式命名（如
```
is_valid_order = ...
```
）
分解循环：如果一个循环同时完成过滤+转换+累加，将其拆分（或使用语言特定的结构：列表推导式、迭代器、流）
反转条件：当
```
else
```
分支是「正常路径」时，反转条件判断

3c. Consolidate and Name

3c. 整合与命名

Make the code's intent visible:

Extract functions for repeated logic or distinct responsibilities
- Name by what it accomplishes, not how it works
- Functions should do one thing at one level of abstraction
Replace magic values with named constants

Rename for intent:

data

→

user_records

process

→

validate_and_enqueue

Group related parameters into a config/options struct when count > 3

让代码的意图更清晰：

提取函数：针对重复逻辑或独立职责提取函数
- 按「实现的功能」而非「实现方式」命名
- 函数应只承担单一层级的单一职责
用命名常量替换魔法值
按意图重命名：
```
data
```
→
```
user_records
```
、
```
proc
```
→
```
process_batch
```
当参数数量超过3个时，将相关参数整合为配置/选项结构体

3d. Leverage Language Idioms

3d. 运用语言规范

Apply language-specific patterns (consult

references/<language>.md

for details):

Python: comprehensions, context managers, dataclasses, structural pattern matching
Go: table-driven tests, error wrapping, functional options, interface satisfaction
TypeScript: discriminated unions, branded types, const assertions, satisfies
Rust: iterator chains,
```
?
```
operator, From/Into, newtype pattern

应用特定语言的模式（详情参考

references/<language>.md

）：

Python：推导式、上下文管理器、dataclasses、结构模式匹配
Go：表驱动测试、错误包装、函数式选项、接口实现
TypeScript：可辨识联合、品牌类型、const断言、satisfies关键字
Rust：迭代器链、
```
?
```
操作符、From/Into trait、newtype模式

3e. Tighten Types

3e. 强化类型定义

Types are documentation that the compiler checks:

Add return type annotations to public functions
Replace stringly-typed parameters with enums/unions
Narrow
```
any
```
/
```
interface{}
```
to specific types where possible
Use branded/newtype patterns for identifiers that shouldn't be confused

类型是编译器可检查的文档：

为公共函数添加返回类型注解
用枚举/联合类型替换基于字符串的参数
尽可能将
```
any
```
/
```
interface{}
```
缩小为具体类型
对不应混淆的标识符使用品牌/newtype模式

Phase 4: Verification

阶段4：验证

Never skip this phase. Simplification that breaks behavior is not simplification.

Run existing tests — If a test suite exists, run it. Report pass/fail.
Run linter/type checker — If configured, run it. Fix new violations your changes introduced.
Manual trace — For each refactored function, mentally trace one happy-path and one error-path input through the old and new code. Confirm identical behavior.
Side effect audit — If the original code had side effects (I/O, mutation, logging), verify the new code preserves them in the same order and conditions.

If tests fail or behavior diverges: revert the specific change, don't try to fix the test.

绝不能跳过此阶段。破坏原有功能的简化毫无意义。

运行现有测试——如果存在测试套件，运行它并报告通过/失败情况
运行代码检查/类型检查工具——如果已配置，运行它并修复修改引入的新问题
手动跟踪——为每个重构后的函数，在新旧代码中分别跟踪一条正常路径和一条错误路径的输入，确认行为一致
副作用审计——如果原代码有副作用（I/O、状态修改、日志输出），验证新代码在相同条件下保留了相同的顺序和行为

如果测试失败或行为不一致：回滚具体的修改，不要尝试修改测试。

Phase 5: Report

阶段5：报告

Present changes as a structured summary. This is important — the developer needs to understand and trust what changed before committing.

For each file modified, provide:

text

undefined

以结构化摘要的形式呈现修改内容。这非常重要——开发者需要理解并信任修改内容后才会提交。

对于每个修改的文件，提供如下内容：

text

undefined

<filename>

Changes

修改内容

[Critical] Removed unreachable error branch in
```
parse_config
```
(dead code after L42 guard)
[High] Extracted
```
validate_credentials()
```
from 60-line
```
handle_login()
```
(was 3 responsibilities)
[Medium] Renamed
```
d
```
→
```
document
```
,
```
proc
```
→
```
process_batch
```

[严重] 移除
```
parse_config
```
中不可达的错误分支（L42守卫子句后的死代码）
[高优先级] 从60行的
```
handle_login()
```
中提取
```
validate_credentials()
```
（原函数承担3项职责）
[中优先级] 将
```
d
```
重命名为
```
document
```
、
```
proc
```
重命名为
```
process_batch
```

Complexity Delta

复杂度变化

```
handle_login
```
: 4 levels nesting → 2, 8 branches → 5
```
parse_config
```
: removed 12 lines of dead code

```
handle_login
```
：嵌套层级从4层→2层，分支数量从8→5
```
parse_config
```
：移除12行死代码

Risk Assessment

风险评估

Low risk: all changes are structural, no logic modifications
Tests: 47/47 passing


Adjust verbosity to scope. Single-function cleanup gets a one-liner. Multi-file refactor gets the full report.

低风险：所有修改均为结构性调整，未修改逻辑
测试结果：47/47通过


根据调整范围调整详细程度。单个函数的清理可使用单行说明，多文件重构则需完整报告。

Behavioral Constraints

行为约束

These are hard rules. Do not violate them regardless of how much cleaner the code would look:

Never change observable behavior — This includes error messages, log output, return values, side effect ordering, and exception types
Never remove error handling — Even if it looks redundant. Defensive code often exists for a reason you can't see from the code alone
Never introduce new dependencies — Simplification adds nothing to the dependency tree
Never refactor code outside the specified scope — Unless the user explicitly asks for a broader pass. Resist the urge to "fix one more thing"
Preserve public API surfaces — Function signatures, export names, and type definitions visible to consumers do not change without explicit user approval
Respect existing tests — If a test asserts specific behavior, that behavior is a requirement, even if it seems wrong. Flag it in the report, don't change it

以下是硬性规则，无论代码看起来能变得多简洁，都不得违反：

绝不改变可观察行为——包括错误信息、日志输出、返回值、副作用顺序和异常类型
绝不移除错误处理——即使看起来冗余。防御性代码的存在往往有你从代码中无法直接看到的原因
绝不引入新依赖——简化操作不得增加依赖树中的内容
绝不重构指定范围外的代码——除非用户明确要求更广泛的优化。克制「再修复一个问题」的冲动
保留公共API表面——函数签名、导出名称和对消费者可见的类型定义，未经用户明确批准不得修改
尊重现有测试——如果测试断言了特定行为，该行为就是需求，即使看起来不合理。在报告中标记它，不要修改

Configuring Scope and Aggressiveness

配置范围与优化力度

The user may specify different modes. If they don't, default to standard.

Mode	Scope	Severity Threshold	Test Requirement
`quick`	Single file or function	Critical + High only	Tests recommended
`standard`	Recent git changes	Critical + High + Medium	Tests required if they exist
`deep`	Entire module/package	All severities	Tests mandatory
`surgical`	User-specified lines/functions	All severities	Manual trace sufficient

The user can specify mode by saying things like "just do a quick pass" or "deep clean this module".

用户可能会指定不同的模式。如果未指定，默认使用**standard（标准）**模式。

模式	范围	严重程度阈值	测试要求
`quick`	单个文件或函数	仅严重+高优先级问题	建议运行测试
`standard`	最近的git变更	严重+高优先级+中优先级问题	若存在测试则必须运行
`deep`	整个模块/包	所有严重程度的问题	必须运行测试
`surgical`	用户指定的代码行/函数	所有严重程度的问题	手动跟踪即可

用户可通过类似「快速处理一下」或「深度清理这个模块」的表述指定模式。

When NOT to Refine

不适宜优化的场景

Push back (politely) if:

The code has no tests and the user wants a deep refactor → suggest writing tests first
The code is auto-generated (protobuf, OpenAPI, ORM models) → suggest modifying the generator
The request is really a feature change disguised as "cleanup" → clarify intent
The code is in a hot path and "simplification" would introduce allocation/copies → flag the tradeoff

在以下场景下，请礼貌地拒绝：

代码没有测试但用户要求深度重构 → 建议先编写测试
代码是自动生成的（protobuf、OpenAPI、ORM模型） → 建议修改生成器
请求实际上是伪装成「清理」的功能变更 → 明确用户意图
代码位于性能敏感路径，「简化」会引入内存分配/复制 → 标记此权衡

Language References

语言参考文档

For language-specific idiom guidance, read the appropriate reference file:

```
references/python.md
```
— Python-specific patterns, anti-patterns, and stdlib alternatives
```
references/go.md
```
— Go idioms, error handling patterns, and interface design
```
references/typescript.md
```
— TypeScript/JavaScript patterns, type narrowing, and module design
```
references/rust.md
```
— Rust idioms, ownership patterns, and iterator usage

Only load the reference file for the language(s) in the current scope. These provide detailed pattern catalogs that supplement the general methodology above.

如需特定语言规范的指导，请阅读对应的参考文件：

```
references/python.md
```
— Python特定模式、反模式及标准库替代方案
```
references/go.md
```
— Go语言规范、错误处理模式及接口设计
```
references/typescript.md
```
— TypeScript/JavaScript模式、类型缩小及模块设计
```
references/rust.md
```
— Rust语言规范、所有权模式及迭代器使用

仅加载当前范围内涉及的语言参考文档。这些文档提供了详细的模式目录，是对上述通用方法的补充。