企业官网建设流程全解析

claude-howto 重构计划模板实战：以结构化文档驱动安全、可追踪的代码重构

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto

本文以 claude-howto 仓库中 refactor 技能 的 重构计划模板 为骨架，系统讲解如何用一份可复制的 Markdown 文档，把一次"高风险的重构"拆解为"可批准、可回滚、可度量"的分阶段执行计划。读完本文，你将掌握模板中项目信息、执行摘要、异味清单、A/B/C 三阶段任务表、逐步操作与指标对比等全部模块的填写方法与实战要点，并能与仓库自带的异味检测脚本、复杂度分析脚本打通，形成"检测 → 计划 → 实施 → 度量"的完整闭环。

1. 模板定位：它是重构工作流中的"产品交付物"

在 claude-howto 的refactor技能中，重构被定义为：

"在不改变软件外部行为的前提下，改进其内部结构的过程。" — Martin Fowler

整套 skill 采用六阶段工作流：

阶段 1：研究与分析 → 阶段 2：测试覆盖评估 → 阶段 3：识别代码异味 → 阶段 4：创建重构计划 → 阶段 5：增量实施 → 阶段 6：评审与迭代

而阶段 4 的产物，就是本文要讲的这份refactoring-plan.md模板。它不是一个可有可无的"文档要求"，而是把前面研究分析、测试评估、异味识别阶段的全部结论沉淀下来，并规划出后续增量实施、评审度量的执行蓝图。

模板的设计遵循 skill 的五大核心原则：

1. 保持行为不变：外部行为必须保持一致；
2. 小步前进：每次只做很小、可测试的改动；
3. 测试驱动：测试是安全网；
4. 持续进行：重构是长期过程，不是一次性任务；
5. 协作确认：每个阶段都需要用户确认。

你会发现，模板中几乎每一个关键节点都设置了"需要用户批准"、"回滚方案"、"状态"等字段——这正是原则 2 与原则 5 在文档层面的落地。

2. 项目信息：为重构计划建立唯一身份

模板开篇用一张表记录重构工作的基本盘：

填写要点：

• 目标文件建议精确到文件路径，必要时标注关键行号（如src/order.js:45-120），与后面"已识别的代码异味"、"重构阶段"中的任务表形成可追踪的引用关系；
• 状态字段是一个五态生命周期：Draft（草稿）→In Review（评审中）→Approved（已批准）→In Progress（实施中）→Completed（已完成）。这五种状态与 SKILL.md 中"每个阶段都需要用户确认"的协作确认原则一一对应——只有拿到用户批准，状态才能从 Draft 推进到 In Progress。

3. 执行摘要：目标、约束与风险等级

执行摘要让所有读者（包括未来的自己）在 30 秒内理解"这次重构要做什么、不能碰什么、有多大风险"。

3.1 目标

模板给出三条目标槽位，并按优先级排列：

• [主要目标：例如，提升支付流程可读性]
• [次要目标：例如，减少重复代码]
• [第三目标：例如，提升可测试性]

注意目标的写法应遵循"行为不变"原则：目标描述的是内部质量的改善方向（可读性、可维护性、可测试性），而不是业务功能的变更。如果目标里出现了"增加新功能"或"修改接口返回格式"，那就不再是重构，而是特性开发——SKILL.md 的安全规则明确要求"不要把重构和新功能混在一起"。

3.2 约束

约束是重构的"红线"，常见示例：

• [约束 1：例如，不能改公共 API]
• [约束 2：例如，必须保持向后兼容]
• [约束 3：例如，不能改数据库 schema]

这些约束会直接影响后续阶段的回滚方案设计与代码异味的处置方式。例如"不能改公共 API"意味着Change Function Declaration这类会改动签名的手法只能走"迁移式"路线（旧函数保留、委托给新函数），而不是直接改名。

3.3 风险等级

• Low - 小改动，测试充分
• Medium - 中等改动，有一定风险
• High - 大改动，需要特别注意

风险等级不是拍脑袋填的，它的判断依据是：

• 改动波及的文件数与调用方数量；
• 测试覆盖是否充分（来自第 4 节的重构前检查清单）；
• 是否存在"不能改"的约束红线（来自 3.2）。

风险等级会进一步决定重构采用哪个阶段策略：Low 风险对应阶段 A，Medium 对应阶段 B，High 对应阶段 C。

4. 重构前检查清单：没有测试就不要重构

模板把"测试覆盖评估"放在重构开始之前，这是整个方法论中最重要的一道安全闸门。SKILL.md 引用 Fowler 的话说："没有测试的重构，就像没有安全带就开车。"

4.1 测试覆盖评估表

这里的≥80%覆盖率目标是 skill 推荐的参考值，实战中应根据模块的关键程度调整。评估方法在 SKILL.md 的阶段 2 中给出：

# 查找测试文件 find . -name "*test*" -o -name "*spec*" | head -20 # JavaScript / TypeScript npm test # Python pytest -v # 覆盖率检查（Python） pytest --cov=.

如果测试缺失或不完整，模板不应被填为"可以开始"，而是要先走 skill 给出的决策路径：

1. 先写测试（推荐）；
2. 在重构过程中逐步补测试；
3. 不写测试直接继续（有风险，需要用户明确确认）。

如果测试失败，则停止——先修复失败测试再重构。

4.2 开始前必须满足

• 所有测试通过
• 已读懂并审查代码
• 已有备份 / 版本控制
• 已获得用户批准

这四项是硬性门槛，全部勾选后才允许进入"已识别的代码异味"环节。注意"已获得用户批准"对应 skill 阶段 1 的输出要求："向用户汇报代码结构总结、识别出的问题区域、初步建议，并请求继续执行的批准。"

5. 已识别的代码异味：让问题清单可排序、可追溯

在进入计划之前，必须先有完整的异味报告。claude-howto 仓库为此提供了两套配套资源：

• 代码异味目录：基于 Fowler《Refactoring》第 2 版的完整异味参考；
• detect-smells.py 脚本：自动检测 Python / JavaScript / TypeScript 文件中的常见异味。

5.1 用脚本快速定位异味

# 分析单个文件 python 03-skills/refactor/scripts/detect-smells.py src/order.js # 分析整个目录 python 03-skills/refactor/scripts/detect-smells.py --dir src/ # 详细模式（带代码片段） python 03-skills/refactor/scripts/detect-smells.py -v src/order.js

从脚本源码（detect-smells.py）可以看到，它的检测阈值定义清晰，可直接作为模板填表的量化依据：

THRESHOLDS = { 'long_method_lines': 30, # 长函数：超过 30 行 'very_long_method_lines': 50, # 超长函数：超过 50 行（High 严重性） 'max_parameters': 4, # 长参数列表：超过 4 个参数 'large_class_lines': 300, # 大类：超过 300 行 'large_class_methods': 10, # 大类：超过 10 个方法 'max_nesting_depth': 4, # 嵌套过深：超过 4 层 'long_chain_length': 3, # 消息链：超过 3 次调用 'duplicate_min_lines': 5, # 重复代码：至少 5 行 }

该脚本共检测 14 类异味：长函数、长参数列表、重复代码、大类、死代码、复杂条件、魔法数字/字符串、Feature Envy、过多注释、深层嵌套、基础类型沉迷、数据泥团、switch 语句、消息链。

5.2 异味摘要表

把检测与人工审查的结果汇总进模板的摘要表：

严重性的分级依据参考代码异味目录末尾的严重性指南：

优先级排序的建议（来自 SKILL.md 阶段 3）：优先关注会阻塞当前开发、导致 bug 或混淆、以及影响最常变更代码路径的异味。

5.3 详细分析：为每个异味建立"病历"

摘要表之后，模板要求对每个异味做一段详细分析：

异味 #1：[名称]

位置：path/to/file.js:45-120

描述：[对问题的详细描述]

影响：

• [影响 1]
• [影响 2]

建议方案：[如何修复的简要说明]

这一节的价值在于把"症状"与"病因"区分开。以 code-smells.md 中的长函数为例：

• 描述：processOrder()共 150 行，包含重复验证逻辑、内联计算、通知逻辑三种职责；
• 影响：难以单独测试；改动容易波及其他逻辑；重复逻辑藏在里面难以发现；
• 建议方案：用Extract Method拆出validateOrder()、calculateOrderTotals()、sendOrderNotifications()三个方法。

"建议方案"应直接指向重构目录中的具体手法，因为后续阶段的任务表就是按"异味 → 手法"的映射关系来组织的。

6. 重构阶段：把大改动拆成可批准、可回滚的小步

模板的核心设计是三阶段渐进式重构。这与 skill 的"小步前进"原则直接对应——SKILL.md 明确指出："重构必须分阶段推进"，且每个阶段都必须单独获得用户批准。

6.1 阶段 A：快速收益（低风险）

目标：快速、低风险的改进，立刻产生价值

预计改动：[X 个文件，Y 个方法]

需要用户批准：Yes / No

回滚方案：回退 A1-A3 的提交

阶段 A 的典型任务类型（来自 SKILL.md）：重命名变量提升清晰度、提取明显重复的代码、删除死代码。这些改动通常不改变函数签名和数据结构，测试覆盖充分时风险很低，因此"需要用户批准"一般可以填 No，或只需一次整体批准。

6.2 阶段 B：结构优化（中风险）

目标：改善代码组织和清晰度

预计改动：[X 个文件，Y 个方法]

需要用户批准：Yes

依赖：必须先完成阶段 A

回滚方案：回滚到阶段 A 完成后的提交

阶段 B 的典型任务：从长函数中提取方法、引入参数对象、把方法移动到更合适的类。这类改动会触及函数签名和类边界，影响面比阶段 A 大，因此"需要用户批准"固定为 Yes。注意模板中的依赖字段——阶段 B 强依赖阶段 A 先完成，这是为了让每次回滚都回到一个已知的干净基线。

6.3 阶段 C：架构改动（高风险）

目标：处理更深层的结构问题

预计改动：[X 个文件，Y 个方法]

需要用户批准：Yes

依赖：必须先完成阶段 A 和 B

回滚方案：回滚到阶段 B 完成后的提交

阶段 C 的典型任务：用多态替代条件分支、提取类、引入设计模式。这是风险最高的一档，涉及类层次和对象模型的变更，例如把switch (employee.type)重构为HourlyEmployee/SalariedEmployee的继承体系（详见 refactoring-catalog.md 中Replace Conditional with Polymorphism一节）。

6.4 阶段间的回滚阶梯

三个阶段的回滚方案构成一条清晰的回滚阶梯：

• 阶段 A 失败 → 回退 A1-A3 的提交；
• 阶段 B 失败 → 回滚到阶段 A 完成后的提交；
• 阶段 C 失败 → 回滚到阶段 B 完成后的提交。

这个设计保证任何时候出问题，都能退回到一个测试全部通过的历史点，而不是"要么全做要么全不做"。这正是"小步前进 + 可回滚"原则的落地。

7. 详细重构步骤：把每个任务写成可执行的微型工作流

对于阶段任务表中的每一项，模板要求填写一张"任务卡"，这是整个模板中粒度最细、实操性最强的部分。

任务 [ID]：[任务名称]

对应异味：[异味名称]

重构手法：[手法名称]

风险等级：Low / Medium / High

上下文

重构前（当前状态）：

// 把当前代码贴在这里

重构后（期望状态）：

// 把期望代码贴在这里

逐步操作

1. 步骤 1：[描述]

   • 测试：完成此步后运行测试
   • 预期：所有测试通过

2. 步骤 2：[描述]

   • 测试：完成此步后运行测试
   • 预期：所有测试通过

3. 步骤 3：[描述]

   • 测试：完成此步后运行测试
   • 预期：所有测试通过

验证

• 所有测试通过
• 行为未改变
• 代码可编译
• 没有新的警告

提交信息

refactor: [描述这次重构]

7.1 "重构前 / 重构后"代码对

这一步是任务卡的核心。以 refactoring-catalog.md 中Extract Method的经典printOwing为例：

重构前：

function printOwing(invoice) { let outstanding = 0; console.log("***********************"); console.log("**** Customer Owes ****"); console.log("***********************"); // Calculate outstanding for (const order of invoice.orders) { outstanding += order.amount; } // Print details console.log(`name: ${invoice.customer}`); console.log(`amount: ${outstanding}`); }

重构后：

function printOwing(invoice) { printBanner(); const outstanding = calculateOutstanding(invoice); printDetails(invoice, outstanding); } function printBanner() { console.log("***********************"); console.log("**** Customer Owes ****"); console.log("***********************"); } function calculateOutstanding(invoice) { return invoice.orders.reduce((sum, order) => sum + order.amount, 0); } function printDetails(invoice, outstanding) { console.log(`name: ${invoice.customer}`); console.log(`amount: ${outstanding}`); }

代码对的作用是让"行为未改变"这个要求变得可验证：重构前后，同样的输入必须产生同样的输出。

7.2 逐步操作：每一步都必须是可测试的

refactoring-catalog.md 为每种手法都给出了明确的步骤序列，可以直接填入任务卡。以Extract Method为例：

1. 创建一个新方法，名字应描述"做什么"而不是"怎么做"；
2. 把代码片段复制到新方法里；
3. 检查片段里用了哪些局部变量；
4. 把局部变量作为参数传入，或在方法内声明；
5. 正确处理返回值；
6. 用新方法调用替换原始片段；
7. 测试。

模板的步骤格式还内嵌了"每步预期"：测试：完成此步后运行测试；预期：所有测试通过。这呼应了 SKILL.md 阶段 5 的黄金法则："修改 → 测试 → 通过？→ 提交 → 下一步"。如果某一步测试失败（红色），立即停止、撤销改动、分析原因，如有疑问询问用户。

7.3 提交信息：原子化提交

模板预置了refactor:前缀的提交信息规范，SKILL.md 给出了示例：

refactor: 从 processOrder() 中提取 calculateTotal() refactor: 将 'x' 重命名为 'customerCount' 以提升清晰度 refactor: 删除未使用的 validateOldFormat() 方法

提交策略要求：原子性（只包含一个逻辑改动）、可回滚（容易撤销）、描述清楚（提交信息明确）。一条好的 refactor 提交信息应当能在未来回滚时，让读者立刻知道这次提交动了什么、为什么。

8. 进度跟踪：让重构全程可视化

8.1 阶段状态表

每个阶段有四种可选状态：Not Started（未开始）、In Progress（进行中）、Done（完成）。完成条件不是"代码改完了"，而是"测试通过 + 用户确认"。skill 要求每个子阶段完成后向用户汇报：做了哪些改动、测试是否仍通过、遇到了什么问题，并询问"继续下一批吗？"

8.2 问题日志

问题日志用于记录重构过程中遇到的意外（如测试失败、依赖冲突、发现新的异味）。SKILL.md 的"何时暂停并询问"清单提示：遇到不确定业务逻辑、可能影响外部 API、测试覆盖不足、重大架构决策、风险上升、意外复杂性时，务必暂停并与用户确认。

9. 指标对比：用数据证明重构有效

模板用两张对比表来量化重构收益，这是阶段 6"评审与迭代"的核心证据。仓库为此提供了 analyze-complexity.py 脚本。

9.1 脚本用法

# 单文件分析 python 03-skills/refactor/scripts/analyze-complexity.py src/order.js # 前后对比模式（重构前文件、重构后文件） python 03-skills/refactor/scripts/analyze-complexity.py order.before.js order.after.js # 目录分析 python 03-skills/refactor/scripts/analyze-complexity.py --dir src/ # 详细模式（每个函数的指标） python 03-skills/refactor/scripts/analyze-complexity.py -v src/order.js # JSON 输出（便于脚本化处理） python 03-skills/refactor/scripts/analyze-complexity.py -j src/order.js

9.2 脚本度量的指标含义

从脚本源码（analyze-complexity.py）可以看到它输出六类指标：

• 圈复杂度（Cyclomatic Complexity）：基于 McCabe 方法，统计代码中的决策点数量（if、for、while、catch、&&、||等），基准复杂度为 1；
• 认知复杂度（Cognitive Complexity）：衡量代码的理解难度，嵌套越深权重越大，控制流中断（break/return/throw）额外加分；
• 可维护性指数（Maintainability Index）：0-100 的综合评分，由 Halstead 体积、圈复杂度和代码行数共同计算；
• 代码行数（Lines of Code）：排除空行和注释后的有效代码行数；
• 函数数量（Function Count）；
• 平均函数长度（Average Function Length）与最大函数长度。

脚本对可维护性指数的解读标准：

9.3 重构前 / 重构后对比表

重构前：

重构后：

脚本的对比模式（python analyze-complexity.py <before_file> <after_file>）会自动输出逐项指标的变化（✅ 改善 / ⚠️ 回退 / ➖ 持平），并给出总体评估。填写"变化"列时，可以据此整理出：

• 可维护性指数是否提升；
• 圈复杂度是否下降；
• 平均函数长度是否缩短。

需要说明的是：代码行数、函数数量的增减并不代表好坏——提取方法可能让函数数量增加、单函数行数下降，这是健康的；而总行数大幅增加则可能是过度设计，需要警惕。指标对比应当结合重构目标（第 3 节）综合解读，而不是单纯追求"数字越小越好"。

10. 重构后检查清单：守住"行为不变"的底线

• 所有测试通过
• 没有新的警告或错误
• 代码成功编译
• 已完成手工验证
• 文档已更新（如需要）
• 已完成代码审查
• 指标有改善
• 已获得用户签字确认

这份清单是阶段 6"评审与迭代"的完成门槛，与 SKILL.md 的重构后检查清单一致。其中两条值得特别强调：

• 已完成手工验证：测试之外，仍要人工确认关键业务路径行为未变（"行为没有变化"是重构的定义性要求）；
• 已获得用户签字确认：对应 skill 最后的问题"你对这些改动满意吗？"，以及模板末尾的批准表。

11. 经验总结与批准：沉淀下一次重构的方法论

11.1 经验总结

做得好的地方

• [Item 1]
• [Item 2]

可以改进的地方

• [Item 1]
• [Item 2]

未来建议

• [Item 1]
• [Item 2]

经验总结让每次重构都成为下一次重构的输入。可以记录的内容包括：哪些手法在目标代码库中效果最好、测试覆盖在哪个模块最薄弱、阶段划分是否合理等。这契合 skill 的"持续进行"原则——重构是长期过程，不是一次性任务。

11.2 批准表

批准表是整个模板协作性的收尾：Plan Author（计划作者）确认计划完整，Technical Lead（技术负责人）确认技术方案可行，Product Owner（产品负责人）确认业务行为未受影响。三方签字后，重构计划才真正"关闭"。

12. 附录：让模板成为自包含的知识库

模板末尾预留了附录区，用于存放相关文档与工具信息：

A. 相关文档

• [相关文档链接]

B. 参考资料

• [代码异味目录]：完整异味清单（见 references/code-smells.md）
• [重构目录]：具体手法与步骤（见 references/refactoring-catalog.md）

C. 使用的工具

• [测试框架]：如 pytest、Jest 等
• [Lint 工具]：如 ESLint、Flake8 等
• [复杂度分析工具]：仓库自带 analyze-complexity.py

参考资料区可以直接引用仓库内已有的两份权威目录：代码异味目录（按"过度膨胀类 / 面向对象滥用类 / 变更阻碍类 / 可舍弃类 / 耦合类"五大分组收录了长函数、大类、switch 语句、重复代码、Feature Envy、消息链等常见异味，并附快速检测清单）与重构目录（收录 Extract Method、Inline Method、Introduce Parameter Object、Replace Conditional with Polymorphism、Extract Class 等手法，每条都含动机、步骤、前后示例，末尾附"异味 → 重构"快速参考表）。工具区建议把检测/度量命令固化下来，例如：

# 异味检测 python 03-skills/refactor/scripts/detect-smells.py --dir src/ # 复杂度度量与前后对比 python 03-skills/refactor/scripts/analyze-complexity.py --dir src/

13. 模板使用的三条实战纪律

结合 SKILL.md 的安全规则，使用本模板时有几条纪律需要内化：

1. 测试是前提，不是可选项：没有测试不要重构（除非用户明确确认风险）。模板的"重构前检查清单"未通过时，不要进入"已识别的代码异味"环节；
2. 小步是节奏，不是风格：每次只做一个可测试的改动，测试失败就停止、撤销、分析，绝不带病前进；
3. 批准是契约，不是形式：每个阶段都要向用户展示计划与风险，获得明确批准后再继续。模板中的"需要用户批准"、"回滚方案"、"批准表"正是这种协作契约的文档化表达。

同时要避免几个常见误区（来自 SKILL.md 的"不要做什么"）：不要把重构和新功能混在一起、不要在生产事故期间做重构、不要重构看不懂的代码、不要过度设计、不要一次性重构所有内容。

小结

refactoring-plan.md重构计划模板是 claude-howtorefactor技能的方法论结晶：它以一张表记录项目信息，以执行摘要锁定目标与红线，以异味清单建立问题档案，以 A/B/C 三阶段把风险拆解成可批准、可回滚的小步，以任务卡细化到可执行的逐步操作，最后用指标对比与检查清单验证"行为未变、结构更优"。与仓库自带的 detect-smells.py、analyze-complexity.py 两个脚本配合，即可形成从自动检测、人工确认、分步实施到量化度量的完整闭环——这正是把 Fowler 重构方法论落地到日常开发的最佳实践。

【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto