claude-howto 重构计划模板解析：面向 Claude Code refactor Skill 的安全重构编排指南

claude-howto 重构计划模板解析：面向 Claude Code refactor Skill 的安全重构编排指南

【免费下载链接】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 技能中的 refactoring-plan.md 重构计划模板 为核心，逐节拆解一份完整重构计划应包含的项目信息、代码异味登记、三阶段分险推进、细粒度操作卡、指标对比与验收签署等结构，并结合仓库内 SKILL.md、code-smells.md、refactoring-catalog.md 及配套检测脚本，说明该模板如何在 Claude Code 的refactor技能六阶段工作流中被实际消费。读完本文，你将获得一套可直接复制使用、能够驱动 Claude 分阶段执行并逐项验证行为不变量（behavior preservation）的重构计划填写与落地方法。

一、模板在 refactor 技能中的定位

1.1 它服务于哪个工作流

claude-howto 的refactor技能基于 Martin Fowler《Refactoring: Improving the Design of Existing Code》（第 2 版）方法论，其 SKILL.md 定义了六阶段工作流：

Phase 1: Research & Analysis（调研分析） ↓ Phase 2: Test Coverage Assessment（测试覆盖评估） ↓ Phase 3: Code Smell Identification（代码异味识别） ↓ Phase 4: Refactoring Plan Creation（重构计划创建） ← 本模板在此被使用 ↓ Phase 5: Incremental Implementation（增量实现） ↓ Phase 6: Review & Iteration（评审与迭代）

本模板正是 Phase 4 的产物。SKILL.md 中明确要求：进入 Phase 5 之前，必须先用 templates/refactoring-plan.md 生成完整计划，向用户逐条说明每个阶段的改动内容与风险，并逐阶段取得显式批准（“Should I proceed with Phase A?”）。模板末尾的批准（承認）表与各阶段的「用户承认可否」字段，就是把这一协同原则落到纸面的机制。

仓库事实：该日语模板开头带<!-- i18n-source: 03-skills/refactor/templates/refactoring-plan.md -->与i18n-date: 2026-04-27标记，说明它是英文模板 refactoring-plan.md 的同步翻译件，两个版本结构完全一致，可直接对照阅读。

1.2 模板与配套资源的分工

二、计划头与项目信息

2.1 项目信息表

模板第一步要求填写项目元信息，避免一份计划在多模块、多人协作中丢失上下文：

状态机从左到右推进：草稿 → 评审中 → 已批准 → 进行中 → 已完成。对象文件应精确到文件名甚至行区间，这与第 4 节「异味登记表」的file:line定位方式保持一致，保证后续每一条任务都能落到具体代码上。

2.2 执行摘要（Executive Summary）

摘要部分用「目标 / 约束 / 风险级别」三角明确重构的边界：

目标（Goals）——模板建议按主次拆三条，例如：

• 主目标：提升支付处理逻辑的可读性
• 副目标：减少重复代码
• 第三目标：提升可测试性

约束（Constraints）——明确「不可改动域」，例如：

• 约束 1：公开 API 不可变更
• 约束 2：必须保持向后兼容
• 约束 3：不修改数据库 schema

SKILL.md 的「When to STOP and Ask」清单与约束一一呼应：业务逻辑不确定、改动可能影响外部 API、需要重大架构决策等场景都必须停下来征询用户。把约束写进计划，正是为了让 Claude 在 Phase 5 执行期遇到边界时有一个可回溯的判断依据。

**风险级别（Risk Level）**三选一：

• Low：小规模变更，代码已有充分测试
• Medium：中等规模变更，存在一定风险
• High：大范围变更，需谨慎处理

风险级别不是一次性定死，它会随阶段推进重新评估——模板第 5 节的阶段 C 任务即对应 High 风险。

三、重构前检查清单（Pre-Refactoring Checklist）

3.1 测试覆盖评估表

「≥80% 单测覆盖 + 存在集成测试 + 全绿」是安全起步的三条硬指标。SKILL.md Phase 2 给出的评估命令与本表配套：

# 查找既有测试 find . -name "*test*" -o -name "*spec*" | head -20 # Python pytest -v pytest --cov=. # JavaScript/TypeScript npm test npm run test:coverage # Java mvn test

3.2 开工前四项前提

• 全部测试通过
• 代码已经过评审且被理解
• 备份 / 版本管理就绪
• 已获得用户批准

SKILL.md 对此有更严格的口径：「没有测试的重构等于没系安全带的驾驶」（Martin Fowler）。若测试缺失或失败，工作流应停下——先补测试或先修复失败用例，而不是带着红灯进入 Phase 4/5。模板把这一前提写进「必须勾选项」，是防止 Claude 在测试失败状态下仍强行出计划的闸门。

四、已识别的代码异味（Code Smells）

4.1 异味总表

严重度与优先级是两套正交坐标：严重度来自对代码影响的客观评估，优先级（P1→P3）用于排定执行顺序。异味的权威判定口径参考 references/code-smells.md，该目录按「臃肿体（Bloaters）/ 面向对象滥用 / 变更阻碍者 / 冗余物 / 耦合者」分类，并给出统一严重度分级：

4.1.1 借助脚本自动采集

异味表不是纯手工活。仓库提供了 scripts/detect-smells.py，支持 Python / JavaScript / TypeScript 三类文件，内置与模板一致的可调阈值：

用法示例（SKILL.md Phase 3 同样引用）：

python scripts/detect-smells.py <file> # 分析单文件 python scripts/detect-smells.py --dir src/ # 扫描目录 python scripts/detect-smells.py -v <file> # 附带代码片段 python scripts/detect-smells.py -j <file> # JSON 输出

从源码结构看，脚本会为每条异味产出smell_type / severity / location(file:line) / description / suggestion五元组——这恰好是模板「异味总表 + 详细分析」两小节需要填写的字段。把脚本输出直接誊入计划，可保证定位精确到行号。

4.2 逐条详细分析

模板要求对每条异味单开小节，形成可评审、可追溯的档案：

异味 #1：[名称]

• 位置：path/to/file.js:45-120
• 说明：[问题的详细描述]
• 影响：
  • [影响 1]
  • [影响 2]
• 建议解决方案：[修复方法概要]

「说明 → 影响 → 方案」三段式的意义在于把 PR/评审会最关心的三件事讲清楚：这是什么问题、不修会付出什么代价、打算怎么修。技术选型上，模板附录 B 提示应链接到 code-smells.md（问题定义）与 refactoring-catalog.md（技法定义）两个目录。

五、三阶段重构计划（Refactoring Phases）

模板最核心的设计是把全部重构动作按风险递进拆成 A/B/C 三个阶段，阶段间有依赖与回滚锚点。这直接对应 SKILL.md Phase 4 的「段階的アプローチ」：

5.1 阶段 A：快速取胜（低风险）

目的: 即效性高、简单的改善 变更预估: [X 文件, Y 方法] 用户批准: Yes / No | # | 任务 | 文件 | 重构技法 | 状态 | |----|-------------------------------|---------------|-------------------|------| | A1 | 变量 x 更名为 userCount | utils.js:15 | 变量重命名 | [ ] | | A2 | 删除未使用的 oldHandler() | api.js:89 | 死代码删除 | [ ] | | A3 | 抽取重复的校验逻辑 | form.js:23,67 | 方法抽取 | [ ] | 回滚计划: revert 提交 A1～A3

模板内置的 A1/A2/A3 三例恰好是 SKILL.md 推荐的三个 Quick Win 起点：重命名、清除死代码、抽出重复。它们共同点是「行为面几乎不变、改动局部、测试立刻可验证」，适合作为让 Claude 与用户建立信任的第一批提交。

5.2 阶段 B：结构改善（中风险）

目的: 改善代码组织与清晰度 用户批准: Yes 依赖: 阶段 A 完成 | # | 任务 | 文件 | 重构技法 | 状态 | |----|---------------------------------------|---------------|------------------------------|------| | B1 | 从长函数中抽出 calculatePrice() | order.js:45 | 方法抽取 | [ ] | | B2 | 引入 OrderDetails 参数对象 | order.js:12 | 引入参数对象 | [ ] | | B3 | 把 formatAddress() 移入 Address 类 | customer.js:78 | 方法移动 | [ ] | 回滚计划: revert 到阶段 A 刚完成的那个提交

5.3 阶段 C：架构级变更（高风险）

目的: 解决更深层的结构问题 用户批准: Yes 依赖: 阶段 A 与 B 完成 | # | 任务 | 文件 | 重构技法 | 状态 | |----|---------------------------------------|---------------|-----------------------------------|------| | C1 | 用多态替换价格计算中的 switch | pricing.js:30 | 用多态替换条件逻辑 | [ ] | | C2 | 抽出 NotificationService 类 | user.js:100 | 类抽取 | [ ] | 回滚计划: revert 到阶段 B 刚完成的那个提交

三阶段的设计对应三条铁律：每阶段都声明「用户批准」（阶段 A 可 No、B/C 必须 Yes）；每阶段都有明确的回滚锚点（revert 到上一阶段结束时的提交）；后一阶段显式声明对前一阶段的依赖（B 依赖 A、C 依赖 A+B）。这套设计让重构退化为一系列可逆的小提交，符合 SKILL.md 的原子提交策略：

refactor: Extract calculateTotal() from processOrder() refactor: Rename 'x' to 'customerCount' for clarity refactor: Remove unused validateOldFormat() method

每个提交需同时满足「原子性（单一逻辑变更）/ 可逆性（可轻松 revert）/ 描述性（清晰信息）」三个性质。

六、详细重构步骤卡（Detailed Refactoring Steps）

阶段表给出「做什么」，本节给出「怎么做」。模板为每个任务单开卡片，把技法手册的机械步骤压缩成可勾选的执行单：

### 任务 [ID]: [任务名] 针对异味: [异味名] 重构技法: [技法名] 风险级别: Low / Medium / High #### 上下文 Before（现状）: ```javascript // 在此粘贴现状代码

After（预期）:

// 在此粘贴预期代码

逐步操作

1. 步骤 1: [说明]
   • 测试: 本步完成后运行测试
   • 预期结果: 全部测试通过
2. 步骤 2: [说明] ...
3. 步骤 3: [说明] ...

验证

• 全部测试通过
• 行为没有变化
• 代码可编译
• 无新增警告

提交信息

refactor: [描述本次重构内容]

### 6.1 卡片如何与技法目录联动 Before/After 代码块与「逐步操作」并非凭空编写，而应忠实抄录自 [references/refactoring-catalog.md](https://link.gitcode.com/i/bd6c6cfc1c2da817867c654fcbdde2e3) 中对应技法的 mechanics。以「方法抽取（Extract Method）」为例，目录给出的机械步骤是： 1. 新建一个以「做什么」而非「怎么做」命名的方法 2. 把代码片段复制进新方法 3. 检查片段中引用的局部变量 4. 将局部变量作为参数传入（或在方法内声明） 5. 妥善处理返回值 6. 用对新方法的调用替换原片段 7. 测试 目录还给出了「每步超过 10 分钟就继续拆小」的金律。把这些步骤照搬到任务卡中、每步配一条「测试 + 预期全绿」的断言，就是模板「行为不变量」落地的执行单元。 ### 6.2 冒烟测试的节奏 任务卡每一步后都要求跑测试，与 SKILL.md Phase 5 的 Golden Rule 完全同构：

"Change → Test → Green? → Commit → Next step"

失败（red）时的处置规程同样来自 SKILL.md：**立即 STOP、撤销改动、分析原因、必要时询问用户**，绝不带着红灯进入下一步。 --- ## 七、进度管理（Progress Tracking） 重构跨多日、多人时，进度表让协作方一眼看清现状： ### 7.1 阶段状态总表 | 阶段 | 状态 | 开始日 | 完成日 | 测试通过 | |---|---|---|---|---| | A | Not Started / In Progress / Done | | | | | B | Not Started / In Progress / Done | | | | | C | Not Started / In Progress / Done | | | | 「测试通过」列独立于阶段状态列出，体现「完成 ≠ 测试通过」：只有测试保持绿色，阶段才能标记为 Done。 ### 7.2 已发生问题登记 | # | 问题 | 解决方案 | 状态 | |---|---|---|---| | 1 | [说明] | [解决方法] | Open / Resolved | 这是重构过程中真实偏差的记录册——例如某条技法在目标语言上有语法限制、某次抽取暴露了隐藏的重复逻辑等。保留 Open 项直至解决，保证收尾检查（第 9 节）时没有遗留的口头承诺。 --- ## 八、指标对比（Metrics Comparison） ### 8.1 模板规定的五项指标 **重构前：** | 指标 | File 1 | File 2 | 合计 | |---|---|---|---| | 代码行数 | | | | | 循环复杂度 | | | | | 可维护性指数 | | | | | 方法数 | | | | | 平均方法行数 | | | | **重构后**（追加「变化」列）： | 指标 | File 1 | File 2 | 合计 | 变化 | |---|---|---|---|---| | 代码行数 | | | | | | 循环复杂度 | | | | | | 可维护性指数 | | | | | | 方法数 | | | | | | 平均方法行数 | | | | | ### 8.2 用仓库脚本自动生成对比数据 表格中的数字可直接来自 [scripts/analyze-complexity.py](https://link.gitcode.com/i/a3ce3b4fccaf9c1f207a6a49bcfe5dc0)，其双文件模式专门用于重构前后对比： ```bash python scripts/analyze-complexity.py before.py after.py # 对比两个版本 python scripts/analyze-complexity.py <file> # 单文件分析 python scripts/analyze-complexity.py --dir src/ # 目录分析 python scripts/analyze-complexity.py -v <file> # 含函数明细

该脚本按 McCabe 方法计算循环复杂度（决策点 +1）、实现认知复杂度（考虑嵌套深度与控制流中断）、并基于 Halstead 体量估算 0–100 的可维护性指数，其解释分档为：

对比模式会输出逐指标「Before / After / Change」表，并给出定性评估（可维护性提升 ✅ / 复杂度下降 ✅ / 平均函数更小 ✅ 等），这些输出可直接誊回模板第 8 节的表格。SKILL.md Phase 6 也要求展示三组核心变化：代码行数、循环复杂度、可维护性指数。

需要说明的适用前提：上述脚本面向 Python / JS/TS 源文件（由文件扩展名自动判定语言），对 Java、Go、Ruby 等其他语言的统计结果可能不准确，属于工具自身的语言边界。

九、重构后检查清单（Post-Refactoring Checklist）

模板收尾的八条勾选项：

• 全部测试通过
• 无新增警告或错误
• 代码能正常编译
• 手动验证完成
• 文档已按需更新
• 已完成代码评审
• 指标得到改善
• 已获用户批准

与重构前的四前提对照可见设计意图：前测防患于未然，后测防功亏一篑。其中「手动验证完成」对应 SKILL.md 中「行为不变（manual verification）」要求——自动化测试通过不等于外部行为完全没变，涉及 I/O、UI、外部服务交互的场景需要人工复核。

十、经验教训与批准签署

10.1 经验教训（Lessons Learned）

• 做得好的方面：[项 1]、[项 2]
• 可改进之处：[项 1]、[项 2]
• 对未来项目的建议：[项 1]、[项 2]

这一节把重构本身当作一次可沉淀的知识资产：哪些技法在特定代码库上执行顺滑、哪些阈值（如 30 行函数）与团队实际不匹配、测试补得够不够快等，都可转化为下一轮重构的输入。SKILL.md Phase 6 的「Next Steps」正鼓励这种复盘循环（是否处理更多异味、是否排期后续重构、是否推广到其他模块）。

10.2 批准表（Approvals）

批准表与模板中每一处「用户批准」形成闭环：阶段级批准解决「该不该动这一步」，最终签署解决「整轮重构是否验收」。对 Claude Code 场景而言，这等同于将 SKILL.md 要求的「Are you satisfied with these changes?」显式固化为多角色会签，避免重构完成后责任归属不清。

10.3 附录（Appendix）

• A. 相关文档：链接到涉及的设计文档、需求说明
• B. 参考资料：链接到代码异味目录、重构技法目录（仓库内即 code-smells.md 与 refactoring-catalog.md）
• C. 使用工具：测试框架、Lint 工具、复杂度分析工具

十一、模板最佳实践与避坑建议

综合模板结构与仓库配套资源，总结填写与使用该模板时的实践要点：

1. 异味表先跑脚本、再人工复核：用detect-smells.py拿到客观的file:line与严重度，再用人工评审确认哪些是「真异味」，避免把脚本的启发式误报写进计划。
2. 阶段 A 宁多勿少：低风险改动先行，一方面尽早释放价值，另一方面为 B/C 阶段提供干净的测试基线与回滚锚点。
3. 任务卡逐条对抄技法目录：Before/After 与微步骤必须与 refactoring-catalog.md 中该技法的 mechanics 一致，禁止自由发挥式重构。
4. 指标表留空到收尾再填：重构前数据在 Phase 4 采集，重构后数据在 Phase 6 采集，两者由analyze-complexity.py统一口径，保证可比。
5. 不做三件事：不把重构与功能开发混在同一次提交里；不在生产事故处理期间重构；不重构自己尚未理解的代码（对应 SKILL.md「What NOT to Do」清单）。

结语：模板 + 技能 = 可治理的重构

ja 版 refactoring-plan.md 的价值不在于它是一张漂亮的表格，而在于它把 Fowler 式「测试保护的增量重构」固化成了机器可执行的治理协议：事前卡测试覆盖，事中按 Low/Medium/High 分阶段推进并为每阶段配备回滚锚点，每步微操作后断言测试全绿，事后用五项指标量化收益并走完会签验收。当把它作为指令模板交给 Claude Code 的refactor技能（SKILL.md 即该技能的落地文档）时，模板补全了「方法论文档 → 可评审执行计划」之间的空白，让 AI 驱动的重构从「让 AI 改代码」升级为「按批准过的计划、逐步可验证地改代码」。

【免费下载链接】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