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 的五大核心原则保持行为不变外部行为必须保持一致小步前进每次只做很小、可测试的改动测试驱动测试是安全网持续进行重构是长期过程不是一次性任务协作确认每个阶段都需要用户确认。你会发现模板中几乎每一个关键节点都设置了需要用户批准、回滚方案、状态等字段——这正是原则 2 与原则 5 在文档层面的落地。2. 项目信息为重构计划建立唯一身份模板开篇用一张表记录重构工作的基本盘字段值项目 / 模块[项目名称]目标文件[要重构的文件列表]创建日期[日期]作者[姓名]状态Draft / In Review / Approved / In Progress / Completed填写要点目标文件建议精确到文件路径必要时标注关键行号如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 风险对应阶段 AMedium 对应阶段 BHigh 对应阶段 C。4. 重构前检查清单没有测试就不要重构模板把测试覆盖评估放在重构开始之前这是整个方法论中最重要的一道安全闸门。SKILL.md 引用 Fowler 的话说没有测试的重构就像没有安全带就开车。4.1 测试覆盖评估表指标当前值目标值状态单元测试覆盖率__%≥80%集成测试Yes/NoYes所有测试通过Yes/NoYes这里的≥80%覆盖率目标是 skill 推荐的参考值实战中应根据模块的关键程度调整。评估方法在 SKILL.md 的阶段 2 中给出# 查找测试文件 find . -name *test* -o -name *spec* | head -20 # JavaScript / TypeScript npm test # Python pytest -v # 覆盖率检查Python pytest --cov.如果测试缺失或不完整模板不应被填为可以开始而是要先走 skill 给出的决策路径先写测试推荐在重构过程中逐步补测试不写测试直接继续有风险需要用户明确确认。如果测试失败则停止——先修复失败测试再重构。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 异味摘要表把检测与人工审查的结果汇总进模板的摘要表#异味位置严重性优先级1[例如Long Method][file:line]HighP12[例如Duplicate Code][file:line]MediumP23[例如Feature Envy][file:line]LowP3严重性的分级依据参考代码异味目录末尾的严重性指南严重性说明处理方式Critical阻塞开发导致 bug立刻修复High明显增加维护负担本迭代修复Medium有问题但还能接受近期计划修复Low小问题视情况顺手修优先级排序的建议来自 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将变量x重命名为userCountutils.js:15Rename Variable[ ]A2删除未使用的oldHandler()api.js:89Remove Dead Code[ ]A3提取重复的验证逻辑form.js:23,67Extract Method[ ]回滚方案回退 A1-A3 的提交阶段 A 的典型任务类型来自 SKILL.md重命名变量提升清晰度、提取明显重复的代码、删除死代码。这些改动通常不改变函数签名和数据结构测试覆盖充分时风险很低因此需要用户批准一般可以填 No或只需一次整体批准。6.2 阶段 B结构优化中风险目标改善代码组织和清晰度预计改动[X 个文件Y 个方法]需要用户批准Yes依赖必须先完成阶段 A#任务文件重构手法状态B1从长函数中提取calculatePrice()order.js:45Extract Method[ ]B2引入OrderDetails参数对象order.js:12Introduce Parameter Object[ ]B3将formatAddress()移动到 Address 类customer.js:78Move Method[ ]回滚方案回滚到阶段 A 完成后的提交阶段 B 的典型任务从长函数中提取方法、引入参数对象、把方法移动到更合适的类。这类改动会触及函数签名和类边界影响面比阶段 A 大因此需要用户批准固定为 Yes。注意模板中的依赖字段——阶段 B 强依赖阶段 A 先完成这是为了让每次回滚都回到一个已知的干净基线。6.3 阶段 C架构改动高风险目标处理更深层的结构问题预计改动[X 个文件Y 个方法]需要用户批准Yes依赖必须先完成阶段 A 和 B#任务文件重构手法状态C1用多态替换价格 switchpricing.js:30Replace Conditional with Polymorphism[ ]C2提取NotificationService类user.js:100Extract Class[ ]回滚方案回滚到阶段 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[描述]测试完成此步后运行测试预期所有测试通过步骤 2[描述]测试完成此步后运行测试预期所有测试通过步骤 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为例创建一个新方法名字应描述做什么而不是怎么做把代码片段复制到新方法里检查片段里用了哪些局部变量把局部变量作为参数传入或在方法内声明正确处理返回值用新方法调用替换原始片段测试。模板的步骤格式还内嵌了每步预期测试完成此步后运行测试预期所有测试通过。这呼应了 SKILL.md 阶段 5 的黄金法则修改 → 测试 → 通过→ 提交 → 下一步。如果某一步测试失败红色立即停止、撤销改动、分析原因如有疑问询问用户。7.3 提交信息原子化提交模板预置了refactor:前缀的提交信息规范SKILL.md 给出了示例refactor: 从 processOrder() 中提取 calculateTotal() refactor: 将 x 重命名为 customerCount 以提升清晰度 refactor: 删除未使用的 validateOldFormat() 方法提交策略要求原子性只包含一个逻辑改动、可回滚容易撤销、描述清楚提交信息明确。一条好的 refactor 提交信息应当能在未来回滚时让读者立刻知道这次提交动了什么、为什么。8. 进度跟踪让重构全程可视化8.1 阶段状态表阶段状态开始时间完成时间测试是否通过ANot Started / In Progress / DoneBNot Started / In Progress / DoneCNot Started / In Progress / Done每个阶段有四种可选状态Not Started未开始、In Progress进行中、Done完成。完成条件不是代码改完了而是测试通过 用户确认。skill 要求每个子阶段完成后向用户汇报做了哪些改动、测试是否仍通过、遇到了什么问题并询问继续下一批吗8.2 问题日志#问题解决方案状态1[描述][如何解决]Open / Resolved问题日志用于记录重构过程中遇到的意外如测试失败、依赖冲突、发现新的异味。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.js9.2 脚本度量的指标含义从脚本源码analyze-complexity.py可以看到它输出六类指标圈复杂度Cyclomatic Complexity基于 McCabe 方法统计代码中的决策点数量if、for、while、catch、、||等基准复杂度为 1认知复杂度Cognitive Complexity衡量代码的理解难度嵌套越深权重越大控制流中断break/return/throw额外加分可维护性指数Maintainability Index0-100 的综合评分由 Halstead 体积、圈复杂度和代码行数共同计算代码行数Lines of Code排除空行和注释后的有效代码行数函数数量Function Count平均函数长度Average Function Length与最大函数长度。脚本对可维护性指数的解读标准分值区间含义85-100高度可维护65-84中等可维护50-64难以维护0-49极难维护9.3 重构前 / 重构后对比表重构前指标文件 1文件 2总计代码行数圈复杂度可维护性指标方法数量平均方法长度重构后指标文件 1文件 2总计变化代码行数圈复杂度可维护性指标方法数量平均方法长度脚本的对比模式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 AuthorTechnical LeadProduct Owner批准表是整个模板协作性的收尾Plan Author计划作者确认计划完整Technical Lead技术负责人确认技术方案可行Product Owner产品负责人确认业务行为未受影响。三方签字后重构计划才真正关闭。12. 附录让模板成为自包含的知识库模板末尾预留了附录区用于存放相关文档与工具信息A. 相关文档[相关文档链接]B. 参考资料[代码异味目录]完整异味清单见 references/code-smells.md[重构目录]具体手法与步骤见 references/refactoring-catalog.mdC. 使用的工具[测试框架]如 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 的安全规则使用本模板时有几条纪律需要内化测试是前提不是可选项没有测试不要重构除非用户明确确认风险。模板的重构前检查清单未通过时不要进入已识别的代码异味环节小步是节奏不是风格每次只做一个可测试的改动测试失败就停止、撤销、分析绝不带病前进批准是契约不是形式每个阶段都要向用户展示计划与风险获得明确批准后再继续。模板中的需要用户批准、回滚方案、批准表正是这种协作契约的文档化表达。同时要避免几个常见误区来自 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考