Back to Details

refactoring-analysis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Refactoring Analysis

重构分析

Perform a systematic analysis of a codebase to identify refactoring opportunities based on Martin Fowler's "Refactoring: Improving the Design of Existing Code" (2nd Edition). Produce a prioritized report with actionable findings.
基于Martin Fowler的《重构：改善既有代码的设计（第二版）》对代码库进行系统性分析，识别可重构的机会，输出包含可落地发现项的优先级排序报告。

Procedures

操作流程

Step 1: Scope the Analysis
  1. Determine the analysis target — a specific directory, module, feature area, or the entire project. If the user did not specify, ask which area to focus on.
  2. Identify the project's language and paradigm (OOP, functional, mixed) to calibrate which smells and techniques are applicable.
  3. If the project follows domain-driven design (DDD) or hexagonal architecture, read 
    references/solid-ddd-context.md
    for additional SOLID-specific analysis criteria.
Step 2: Explore the Codebase
  1. Map the directory structure and identify key modules, entry points, and shared utilities.
  2. Read the most critical files (entry points, core business logic, shared modules).
  3. Identify the project's conventions: naming, file organization, test patterns, dependency injection approach.
Step 3: Detect Code Smells
Read 
references/code-smells-catalog.md
for the full catalog of detectable smells.
Systematically scan for the following smell categories, in priority order:
  1. Bloaters — Long Functions (>15 lines of logic), Large Classes/Modules (>300 lines), Long Parameter Lists (>3 params), Data Clumps, Primitive Obsession.
  2. Change Preventers — Divergent Change (one module changed for multiple unrelated reasons), Shotgun Surgery (one change touches 5+ files).
  3. Dispensables — Duplicated Code, Dead Code, Speculative Generality, Lazy Elements, Comments as Deodorant.
  4. Couplers — Feature Envy, Insider Trading (excessive data sharing between modules), Message Chains (>2 levels deep), Middle Man (>50% delegation).
  5. Conditional Complexity — Nested Conditionals (>2 levels), Repeated Switches, Missing Guard Clauses, Complex Boolean Expressions.
  6. DRY Violations — Near-identical code blocks, copy-pasted logic with minor variations, repeated parameter groups, duplicated constants or magic numbers.
For each detected smell:
  • Record the exact file path and line range
  • Classify the smell type (from the catalog)
  • Assess severity: 
    critical
    | 
    high
    | 
    medium
    | 
    low
  • Note the impact on maintainability, readability, or change cost
Step 4: Map Refactoring Opportunities
Read 
references/refactoring-techniques.md
for the full technique catalog.
For each detected smell, identify the recommended refactoring technique(s):
SmellPrimary Technique
Long FunctionExtract Function, Decompose Conditional
Duplicated CodeExtract Function, Pull Up Method
Long Parameter ListIntroduce Parameter Object, Preserve Whole Object
Feature EnvyMove Function
Data ClumpsExtract Class, Introduce Parameter Object
Primitive ObsessionReplace Primitive with Object
Large Class/ModuleExtract Class, Extract Module
Repeated SwitchesReplace Conditional with Polymorphism
Message ChainsHide Delegate, Extract Function
Nested ConditionalsReplace with Guard Clauses
Dead CodeRemove Dead Code
Magic Numbers/StringsExtract Constant
Mutable Shared StateEncapsulate Variable, Split Variable
Imperative LoopsReplace Loop with Pipeline (map/filter/reduce)
For each opportunity, draft a concrete before/after code sketch showing the transformation.
Step 5: Assess Coupling and Cohesion
  1. Identify modules with high afferent coupling (many dependents — risky to change).
  2. Identify modules with high efferent coupling (many dependencies — fragile).
  3. Flag circular dependencies between modules.
  4. Assess cohesion — modules that mix unrelated responsibilities are candidates for Extract Class or Split Phase.
Step 6: Evaluate DRY Opportunities
  1. Search for near-duplicate code blocks (>5 lines of similar structure).
  2. Identify repeated constant values (magic numbers, repeated string literals).
  3. Find repeated parameter patterns across function signatures.
  4. Look for copy-pasted logic with minor variations that could be parameterized.
  5. Propose extraction strategies: shared functions, constants files, parameter objects.
Step 7: SOLID Analysis (Domain Projects Only)
<GATE> Only perform this step if the project uses domain-driven design (DDD), hexagonal/clean architecture, or explicitly models a complex business domain. SOLID principles have the most impact in domain-rich, object-oriented codebases. For simple CRUD apps, utility libraries, or purely functional codebases, skip this step and note in the report that SOLID analysis was not applicable. </GATE>
Read 
references/solid-ddd-context.md
for detailed guidance.
Evaluate against SOLID principles with domain-project focus:
  • SRP: Classes/modules with multiple reasons to change
  • OCP: Areas requiring modification (not extension) for new variants
  • LSP: Subclasses that override to throw or no-op (Refused Bequest smell)
  • ISP: Interfaces forcing implementers to stub unused methods
  • DIP: High-level modules importing low-level implementations directly
Step 8: Prioritize and Generate Report
  1. Read 
    assets/refactoring-report-template.md
    for the output template.
  2. Rank all findings by a priority score combining:
    • Impact: How much does this hurt readability, maintainability, or change cost?
    • Frequency: How often is this pattern encountered in the codebase?
    • Effort: How much work to refactor? (low effort + high impact = do first)
  3. Group findings into priority tiers:
    • P0 — Critical: Blocking future development, causing bugs, or high coupling
    • P1 — High: Significant maintenance burden, frequent pain point
    • P2 — Medium: Noticeable but manageable, worth addressing opportunistically
    • P3 — Low: Minor improvements, cosmetic, litter-pickup candidates
  4. Generate the report following the template and save to: 
    docs/_refacs/<YYYYMMDD>-<slug>.md
    where 
    <slug>
    is a lowercase-hyphenated summary (e.g., 
    auth-module-cleanup
    ).
  5. Create the 
    docs/_refacs/
    directory if it does not exist.
Step 9: Present Summary
  1. Present a brief executive summary to the user with:
    • Total findings count by severity
    • Top 3-5 highest-impact opportunities
    • Suggested refactoring order (quick wins first, then high-impact)
    • Estimated complexity tier for each (trivial / moderate / significant)
  2. Ask the user if they want to proceed with any specific refactoring.
步骤1：确定分析范围
  1. 明确分析目标：指定目录、模块、功能域或整个项目。如果用户未指定，询问需要聚焦的分析区域。
  2. 识别项目使用的语言和编程范式（OOP、函数式、混合范式），校准适用的代码异味和重构技术。
  3. 如果项目遵循领域驱动设计（DDD）或六边形架构，阅读
    references/solid-ddd-context.md
    获取额外的SOLID专属分析标准。
步骤2：探查代码库
  1. 梳理目录结构，识别核心模块、入口点和公共工具库。
  2. 阅读最高优先级文件：入口文件、核心业务逻辑、公共模块。
  3. 识别项目约定：命名规则、文件组织方式、测试模式、依赖注入实现方式。
步骤3：检测代码异味
阅读
references/code-smells-catalog.md
获取完整的可检测代码异味目录。
按优先级顺序系统性扫描以下代码异味类别：
  1. 膨胀类 — 过长函数（逻辑超过15行）、过大类/模块（超过300行）、过长参数列表（超过3个参数）、数据泥团、基本类型偏执。
  2. 变更阻碍类 — 发散式变化（一个模块会因多个不相关的原因被修改）、霰弹式修改（一个变更需要修改5个以上文件）。
  3. 冗余类 — 重复代码、死代码、投机性泛化、冗余元素、“除臭剂”式注释。
  4. 耦合类 — 依恋情结、内幕交易（模块间过度共享数据）、消息链（超过2层深度）、中间人（超过50%逻辑为委托调用）。
  5. 条件复杂度类 — 嵌套条件（超过2层）、重复Switch语句、缺失卫语句、复杂布尔表达式。
  6. DRY原则违反类 — 近乎完全相同的代码块、仅做了微小改动的复制粘贴逻辑、重复的参数组、重复的常量或魔法数字。
针对每个检测到的代码异味：
  • 记录准确的文件路径和行范围
  • 对异味类型进行分类（参考目录）
  • 评估严重程度：
    critical
    | 
    high
    | 
    medium
    | 
    low
  • 标注对可维护性、可读性或变更成本的影响
步骤4：映射重构机会
阅读
references/refactoring-techniques.md
获取完整的重构技术目录。
针对每个检测到的代码异味，匹配推荐的重构技术：
代码异味首选技术
过长函数提取函数、分解条件语句
重复代码提取函数、函数上移
过长参数列表引入参数对象、保持对象完整
依恋情结移动函数
数据泥团提取类、引入参数对象
基本类型偏执用对象替换基本类型
过大类/模块提取类、提取模块
重复Switch语句用多态替换条件语句
消息链隐藏委托关系、提取函数
嵌套条件替换为卫语句
死代码移除死代码
魔法数字/字符串提取常量
可变共享状态封装变量、拆分变量
命令式循环用管道（map/filter/reduce）替换循环
针对每个重构机会，草拟具体的代码前后对比示例，展示转换逻辑。
步骤5：评估耦合与内聚
  1. 识别高入向耦合的模块（有大量依赖方，变更风险高）。
  2. 识别高出向耦合的模块（依赖大量其他模块，稳定性差）。
  3. 标记模块间的循环依赖。
  4. 评估内聚性：混合了不相关职责的模块可作为提取类或阶段拆分的候选。
步骤6：评估DRY优化机会
  1. 搜索近乎重复的代码块（超过5行结构相似的代码）。
  2. 识别重复的常量值（魔法数字、重复的字符串字面量）。
  3. 查找跨函数签名的重复参数模式。
  4. 寻找仅做了微小改动、可通过参数化复用的复制粘贴逻辑。
  5. 提出提取策略：公共函数、常量文件、参数对象。
步骤7：SOLID分析（仅领域项目适用）
<GATE> 仅当项目使用领域驱动设计（DDD）、六边形/整洁架构，或明确对复杂业务域进行建模时才执行此步骤。SOLID原则在领域丰富的面向对象代码库中收益最高。对于简单的CRUD应用、工具库或纯函数式代码库，跳过此步骤，并在报告中注明SOLID分析不适用。 </GATE>
阅读
references/solid-ddd-context.md
获取详细指导。
针对领域项目的特点评估SOLID原则遵循情况：
  • SRP（单一职责原则）：存在多个变更理由的类/模块
  • OCP（开闭原则）：需要修改（而非扩展）来支持新变体的区域
  • LSP（里氏替换原则）：重写后抛出异常或无操作的子类（拒绝继承异味）
  • ISP（接口隔离原则）：强制实现类编写未使用方法存根的接口
  • DIP（依赖倒置原则）：直接导入低层实现的高层模块
步骤8：优先级排序与生成报告
  1. 阅读
    assets/refactoring-report-template.md
    获取输出模板。
  2. 结合以下维度计算优先级分数，对所有发现项排序：
    • 影响：该问题对可读性、可维护性或变更成本的负面影响程度？
    • 出现频率：该模式在代码库中出现的频次？
    • 改造成本：重构需要的工作量？（低工作量+高影响=优先处理）
  3. 将发现项归入不同优先级层级：
    • P0 — 严重：阻塞后续开发、导致bug或存在高耦合问题
    • P1 — 高：带来显著的维护负担，是高频痛点
    • P2 — 中：问题明显但可控，适合伺机处理
    • P3 — 低：小幅优化、表面化问题，属于随手清理的候选
  4. 遵循模板生成报告并保存至： 
    docs/_refacs/<YYYYMMDD>-<slug>.md
    其中
    <slug>
    为小写连字符分隔的概要（例如
    auth-module-cleanup
    ）。
  5. 如果
    docs/_refacs/
    目录不存在则创建。
步骤9：展示总结
  1. 向用户展示简要的执行摘要，包含：
    • 按严重程度划分的发现项总数
    • 优先级最高的3-5个重构机会
    • 建议的重构顺序（先快速赢，再高影响项）
    • 每个项的预估复杂度等级（简单/中等/高）
  2. 询问用户是否想要推进任何特定的重构工作。

Error Handling

错误处理

  • If the analysis target is too broad (>50 files), ask the user to narrow scope or confirm they want a high-level scan with sampling.
  • If the project has no tests, warn that refactoring without test coverage is risky and recommend adding tests for critical paths before refactoring.
  • If the project uses an unfamiliar framework or pattern, note this limitation in the report rather than guessing.
  • If a smell is ambiguous (could be intentional design), flag it as "potential" and note the context that might justify the current structure.
  • 如果分析目标范围过广（超过50个文件），请用户缩小范围，或确认是否需要采用抽样方式进行高层扫描。
  • 如果项目没有测试，警告用户无测试覆盖的重构存在风险，建议在重构前为核心路径补充测试。
  • 如果项目使用了不熟悉的框架或模式，在报告中注明该限制，不要做猜测性判断。
  • 如果某个异味存在歧义（可能是有意设计），将其标记为“潜在”问题，并注明可能支持当前结构的上下文理由。