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 模板与配套资源的分工资源相对路径在重构过程中的作用技能说明03-skills/refactor/SKILL.md六阶段方法论与安全规则、何时停下征询用户异味目录code-smells.md判定「发现了什么异味、严重度如何」技法目录refactoring-catalog.md给出「针对该异味采用什么技法及其操作步骤」计划模板templates/refactoring-plan.md英文/ ja 版本把前两者的结论固化成带风险分级、分阶段、可回滚的执行清单自动化脚本detect-smells.py、analyze-complexity.py产出模板「代码异味」与「指标对比」两节需要的数据二、计划头与项目信息2.1 项目信息表模板第一步要求填写项目元信息避免一份计划在多模块、多人协作中丢失上下文项目值项目/模块[项目名]对象文件[重构目标文件列表]作成日[日期]作成者[姓名]状态Draft / In Review / Approved / In Progress / Completed状态机从左到右推进草稿 → 评审中 → 已批准 → 进行中 → 已完成。对象文件应精确到文件名甚至行区间这与第 4 节「异味登记表」的file:line定位方式保持一致保证后续每一条任务都能落到具体代码上。2.2 执行摘要Executive Summary摘要部分用「目标 / 约束 / 风险级别」三角明确重构的边界目标Goals——模板建议按主次拆三条例如主目标提升支付处理逻辑的可读性副目标减少重复代码第三目标提升可测试性约束Constraints——明确「不可改动域」例如约束 1公开 API 不可变更约束 2必须保持向后兼容约束 3不修改数据库 schemaSKILL.md 的「When to STOP and Ask」清单与约束一一呼应业务逻辑不确定、改动可能影响外部 API、需要重大架构决策等场景都必须停下来征询用户。把约束写进计划正是为了让 Claude 在 Phase 5 执行期遇到边界时有一个可回溯的判断依据。**风险级别Risk Level**三选一Low小规模变更代码已有充分测试Medium中等规模变更存在一定风险High大范围变更需谨慎处理风险级别不是一次性定死它会随阶段推进重新评估——模板第 5 节的阶段 C 任务即对应 High 风险。三、重构前检查清单Pre-Refactoring Checklist3.1 测试覆盖评估表指标现状目标状态单元测试覆盖率__%≥80%集成测试Yes/NoYes全部测试通过Yes/NoYes「≥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 test3.2 开工前四项前提全部测试通过代码已经过评审且被理解备份 / 版本管理就绪已获得用户批准SKILL.md 对此有更严格的口径「没有测试的重构等于没系安全带的驾驶」Martin Fowler。若测试缺失或失败工作流应停下——先补测试或先修复失败用例而不是带着红灯进入 Phase 4/5。模板把这一前提写进「必须勾选项」是防止 Claude 在测试失败状态下仍强行出计划的闸门。四、已识别的代码异味Code Smells4.1 异味总表#异味位置严重度优先级1[例Long Method过长函数][file:line]HighP12[例Duplicate Code重复代码][file:line]MediumP23[例Feature Envy依恋情结][file:line]LowP3严重度与优先级是两套正交坐标严重度来自对代码影响的客观评估优先级P1→P3用于排定执行顺序。异味的权威判定口径参考 references/code-smells.md该目录按「臃肿体Bloaters/ 面向对象滥用 / 变更阻碍者 / 冗余物 / 耦合者」分类并给出统一严重度分级严重度描述行动建议Critical阻塞开发、引发 bug立即修复High显著维护负担当前迭代修复Medium可见但可管理近期规划修复Low轻微不便顺手修复4.1.1 借助脚本自动采集异味表不是纯手工活。仓库提供了 scripts/detect-smells.py支持 Python / JavaScript / TypeScript 三类文件内置与模板一致的可调阈值检测项默认阈值见源码THRESHOLDS字典过长函数30 行50 行判 High过长参数列表4 个参数6 个判 High巨大类300 行或 10 个方法深层嵌套4 层缩进/花括号长调用链≥3 次连续点调用重复代码相同有效行出现 ≥3 次用法示例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 的「段階的アプローチ」阶段定位典型动作风险A快速取胜 Quick Wins低风险高价值立即可做变量改名、清除死代码、抽出明显重复LowB结构改善中期优化长函数抽方法、引入参数对象、方法搬家MediumC架构级变更深层结构问题条件逻辑改多态、抽类、引入设计模式High5.1 阶段 A快速取胜低风险目的: 即效性高、简单的改善 变更预估: [X 文件, Y 方法] 用户批准: Yes / No | # | 任务 | 文件 | 重构技法 | 状态 | |----|-------------------------------|---------------|-------------------|------| | A1 | 变量 x 更名为 userCount | utils.js:15 | 变量重命名 | [ ] | | A2 | 删除未使用的 oldHandler() | api.js:89 | 死代码删除 | [ ] | | A3 | 抽取重复的校验逻辑 | form.js:23,67 | 方法抽取 | [ ] | 回滚计划: revert 提交 A1A3模板内置的 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 依赖 AB。这套设计让重构退化为一系列可逆的小提交符合 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: [说明]测试: 本步完成后运行测试预期结果: 全部测试通过步骤 2: [说明] ...步骤 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 的可维护性指数其解释分档为区间含义85–100高度可维护65–84中等可维护50–64维护困难0–49极难维护对比模式会输出逐指标「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 附录AppendixA. 相关文档链接到涉及的设计文档、需求说明B. 参考资料链接到代码异味目录、重构技法目录仓库内即 code-smells.md 与 refactoring-catalog.mdC. 使用工具测试框架、Lint 工具、复杂度分析工具十一、模板最佳实践与避坑建议综合模板结构与仓库配套资源总结填写与使用该模板时的实践要点异味表先跑脚本、再人工复核用detect-smells.py拿到客观的file:line与严重度再用人工评审确认哪些是「真异味」避免把脚本的启发式误报写进计划。阶段 A 宁多勿少低风险改动先行一方面尽早释放价值另一方面为 B/C 阶段提供干净的测试基线与回滚锚点。任务卡逐条对抄技法目录Before/After 与微步骤必须与 refactoring-catalog.md 中该技法的 mechanics 一致禁止自由发挥式重构。指标表留空到收尾再填重构前数据在 Phase 4 采集重构后数据在 Phase 6 采集两者由analyze-complexity.py统一口径保证可比。不做三件事不把重构与功能开发混在同一次提交里不在生产事故处理期间重构不重构自己尚未理解的代码对应 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 模板与配套资源的分工资源相对路径在重构过程中的作用技能说明03-skills/refactor/SKILL.md六阶段方法论与安全规则、何时停下征询用户异味目录code-smells.md判定「发现了什么异味、严重度如何」技法目录refactoring-catalog.md给出「针对该异味采用什么技法及其操作步骤」计划模板templates/refactoring-plan.md英文/ ja 版本把前两者的结论固化成带风险分级、分阶段、可回滚的执行清单自动化脚本detect-smells.py、analyze-complexity.py产出模板「代码异味」与「指标对比」两节需要的数据二、计划头与项目信息2.1 项目信息表模板第一步要求填写项目元信息避免一份计划在多模块、多人协作中丢失上下文项目值项目/模块[项目名]对象文件[重构目标文件列表]作成日[日期]作成者[姓名]状态Draft / In Review / Approved / In Progress / Completed状态机从左到右推进草稿 → 评审中 → 已批准 → 进行中 → 已完成。对象文件应精确到文件名甚至行区间这与第 4 节「异味登记表」的file:line定位方式保持一致保证后续每一条任务都能落到具体代码上。2.2 执行摘要Executive Summary摘要部分用「目标 / 约束 / 风险级别」三角明确重构的边界目标Goals——模板建议按主次拆三条例如主目标提升支付处理逻辑的可读性副目标减少重复代码第三目标提升可测试性约束Constraints——明确「不可改动域」例如约束 1公开 API 不可变更约束 2必须保持向后兼容约束 3不修改数据库 schemaSKILL.md 的「When to STOP and Ask」清单与约束一一呼应业务逻辑不确定、改动可能影响外部 API、需要重大架构决策等场景都必须停下来征询用户。把约束写进计划正是为了让 Claude 在 Phase 5 执行期遇到边界时有一个可回溯的判断依据。**风险级别Risk Level**三选一Low小规模变更代码已有充分测试Medium中等规模变更存在一定风险High大范围变更需谨慎处理风险级别不是一次性定死它会随阶段推进重新评估——模板第 5 节的阶段 C 任务即对应 High 风险。三、重构前检查清单Pre-Refactoring Checklist3.1 测试覆盖评估表指标现状目标状态单元测试覆盖率__%≥80%集成测试Yes/NoYes全部测试通过Yes/NoYes「≥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 test3.2 开工前四项前提全部测试通过代码已经过评审且被理解备份 / 版本管理就绪已获得用户批准SKILL.md 对此有更严格的口径「没有测试的重构等于没系安全带的驾驶」Martin Fowler。若测试缺失或失败工作流应停下——先补测试或先修复失败用例而不是带着红灯进入 Phase 4/5。模板把这一前提写进「必须勾选项」是防止 Claude 在测试失败状态下仍强行出计划的闸门。四、已识别的代码异味Code Smells4.1 异味总表#异味位置严重度优先级1[例Long Method过长函数][file:line]HighP12[例Duplicate Code重复代码][file:line]MediumP23[例Feature Envy依恋情结][file:line]LowP3严重度与优先级是两套正交坐标严重度来自对代码影响的客观评估优先级P1→P3用于排定执行顺序。异味的权威判定口径参考 references/code-smells.md该目录按「臃肿体Bloaters/ 面向对象滥用 / 变更阻碍者 / 冗余物 / 耦合者」分类并给出统一严重度分级严重度描述行动建议Critical阻塞开发、引发 bug立即修复High显著维护负担当前迭代修复Medium可见但可管理近期规划修复Low轻微不便顺手修复4.1.1 借助脚本自动采集异味表不是纯手工活。仓库提供了 scripts/detect-smells.py支持 Python / JavaScript / TypeScript 三类文件内置与模板一致的可调阈值检测项默认阈值见源码THRESHOLDS字典过长函数30 行50 行判 High过长参数列表4 个参数6 个判 High巨大类300 行或 10 个方法深层嵌套4 层缩进/花括号长调用链≥3 次连续点调用重复代码相同有效行出现 ≥3 次用法示例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 的「段階的アプローチ」阶段定位典型动作风险A快速取胜 Quick Wins低风险高价值立即可做变量改名、清除死代码、抽出明显重复LowB结构改善中期优化长函数抽方法、引入参数对象、方法搬家MediumC架构级变更深层结构问题条件逻辑改多态、抽类、引入设计模式High5.1 阶段 A快速取胜低风险目的: 即效性高、简单的改善 变更预估: [X 文件, Y 方法] 用户批准: Yes / No | # | 任务 | 文件 | 重构技法 | 状态 | |----|-------------------------------|---------------|-------------------|------| | A1 | 变量 x 更名为 userCount | utils.js:15 | 变量重命名 | [ ] | | A2 | 删除未使用的 oldHandler() | api.js:89 | 死代码删除 | [ ] | | A3 | 抽取重复的校验逻辑 | form.js:23,67 | 方法抽取 | [ ] | 回滚计划: revert 提交 A1A3模板内置的 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 依赖 AB。这套设计让重构退化为一系列可逆的小提交符合 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: [说明]测试: 本步完成后运行测试预期结果: 全部测试通过步骤 2: [说明] ...步骤 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 的可维护性指数其解释分档为区间含义85–100高度可维护65–84中等可维护50–64维护困难0–49极难维护对比模式会输出逐指标「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 附录AppendixA. 相关文档链接到涉及的设计文档、需求说明B. 参考资料链接到代码异味目录、重构技法目录仓库内即 code-smells.md 与 refactoring-catalog.mdC. 使用工具测试框架、Lint 工具、复杂度分析工具十一、模板最佳实践与避坑建议综合模板结构与仓库配套资源总结填写与使用该模板时的实践要点异味表先跑脚本、再人工复核用detect-smells.py拿到客观的file:line与严重度再用人工评审确认哪些是「真异味」避免把脚本的启发式误报写进计划。阶段 A 宁多勿少低风险改动先行一方面尽早释放价值另一方面为 B/C 阶段提供干净的测试基线与回滚锚点。任务卡逐条对抄技法目录Before/After 与微步骤必须与 refactoring-catalog.md 中该技法的 mechanics 一致禁止自由发挥式重构。指标表留空到收尾再填重构前数据在 Phase 4 采集重构后数据在 Phase 6 采集两者由analyze-complexity.py统一口径保证可比。不做三件事不把重构与功能开发混在同一次提交里不在生产事故处理期间重构不重构自己尚未理解的代码对应 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考