重构计划实战指南用 claude-howto 的 refactoring-plan 模板把代码重构做成可跟踪的工程流程【免费下载链接】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 仓库中 03-skills/refactor 技能配套的 refactoring-plan 模板完整拆解项目信息 → 坏味道识别 → 分阶段重构 → 度量对比 → 复盘签核的整条重构管理链路。文章将以模板字段为主线结合仓库内的 坏味道目录、重构目录 以及 detect-smells.py、analyze-complexity.py 两个自动化脚本讲清每一步该填什么、为什么填、以及如何用数据验证重构效果。读完你可以直接把模板套用到自己的重构任务上形成一份可评审、可回滚、可量化的重构计划书。一、模板定位重构不是随手改代码而是一份可跟踪的工程计划refactoring-plan.md 的定位非常明确——它是 refactor SKILL 六阶段工作流中Phase 4重构计划创建的标准输出物。整个 SKILL 遵循 Martin Fowler 在Refactoring: Improving the Design of Existing Code第 2 版中提出的方法论核心信条是Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure.重构是在不改变代码外部行为的前提下改善其内部结构的过程。模板把这一原则落到实操层面先记录上下文再识别坏味道然后分风险等级排期最后用指标验证行为未变、结构更好。它本质上是一份贯穿重构前、中、后的唯一事实来源Single Source of Truth让团队评审、逐阶段批准、中途回滚和事后复盘都有据可依。模板的使用方式很简单复制03-skills/refactor/templates/refactoring-plan.md到你的项目里按章节填充。下文逐节展开每个区块的填写要点与背后的技术支撑。二、Project Information用一张表锁定重构范围模板开篇要求填写项目信息四个字段看似简单却是整个计划的坐标系FieldValue填写要点Project/Module[Project name]精确到模块名避免含糊的整个系统Target Files[List of files to refactor]列出全部目标文件建议带相对路径Date Created[Date]计划创建日期Author[Name]计划作者便于追溯StatusDraft / In Review / Approved / In Progress / Completed生命周期状态机随评审推进流转Status的五种取值对应了计划从草稿到落地的完整生命周期这也是模板可评审属性的体现只有状态流转到 Approved才允许进入实施阶段。与之呼应SKILL 的 Phase 1Research Analysis要求在此前先向用户澄清五个关键问题确保范围准确Scope哪些文件/模块/函数需要重构Goals要解决什么问题可读性、性能、可维护性Constraints哪些区域绝对不能动Timeline pressure是否阻塞其他工作Test status测试是否存在是否通过这些答案正是填充 Project Information 的信息来源。模板中 Target Files 之所以要精确列举是因为后续所有坏味道定位、阶段任务拆分和度量对比都依赖这个文件清单。三、Executive Summary目标、约束与风险分级执行摘要区由三组复选框构成是计划核心决策的浓缩Goals目标按优先级列出重构要达成的结果模板给出的范式是[Primary goal: e.g., Improve readability of payment processing]主要目标如提升支付处理代码的可读性[Secondary goal: e.g., Reduce code duplication]次要目标如减少代码重复[Tertiary goal: e.g., Improve testability]第三目标如提升可测试性Constraints约束明确重构的边界防止范围蔓延。模板提供了三个典型约束[Constraint 1: e.g., Cannot change public API]不能改公开 API[Constraint 2: e.g., Must maintain backward compatibility]必须保持向后兼容[Constraint 3: e.g., No changes to database schema]不改数据库 schemaRisk Level风险等级为整个重构工作定调Low - Minor changes, well-tested code低改动小、测试充分的代码Medium - Moderate changes, some risk中改动中等、有一定风险High - Significant changes, careful attention needed高改动显著、需高度谨慎风险等级不是拍脑袋它与后文的 Phase A/B/C 风险分层直接挂钩——低风险任务进 Quick Wins 阶段高风险任务进 Architectural Changes 阶段。SKILL 的 Safety Rules 也明确要求Never make big changes - break into tiny steps风险分级正是把大重构拆成小步提交的依据。四、Pre-Refactoring Checklist没有测试安全网一切重构都免谈重构前检查清单是 SKILL 中Phase 2Test Coverage Assessment的落地工具。SKILL 引用了一句重要论断Refactoring without tests is like driving without a seatbelt.没有测试的重构就像不系安全带开车。测试覆盖评估表MetricCurrentTargetStatusUnit Test Coverage__%≥80%Integration TestsYes/NoYesAll Tests PassingYes/NoYes模板把单元测试覆盖率 ≥80%和集成测试必须存在设为硬性目标且要求所有测试必须通过才能开工。SKILL Phase 2 给出的具体操作是检查现有测试find . -name *test* -o -name *spec* | head -20运行测试JavaScript/TypeScript 用npm testPython 用pytest -vJava 用mvn test检查覆盖率npm run test:coverage或pytest --cov.SKILL 还规定了三种情况的处理决策测试存在且通过→ 进入 Phase 3坏味道识别测试缺失或不完整→ 提供三个选项先补测试推荐、重构中增量补测试、无测试继续有风险需用户明确确认测试失败→ 立即 STOP先修测试再谈重构。开工前必备条件All tests passing所有测试通过Code reviewed and understood代码已评审且被理解Backup/version control in place备份/版本控制就绪User approval obtained已获得用户批准最后一项与 SKILL 的Collaborative原则用户须在每个阶段批准保持一致。如果测试缺口较大SKILL 建议对每个待重构函数至少覆盖三类场景happy path正常路径、edge cases空输入、null、边界、error scenarios非法输入、异常并遵循red-green-refactor红绿重构循环。五、Identified Code Smells坏味道登记表与逐项分析这一节对应 SKILL 的Phase 3Code Smell Identification是重构计划的诊断书。汇总表#SmellLocationSeverityPriority1[e.g., Long Method][file:line]HighP12[e.g., Duplicate Code][file:line]MediumP23[e.g., Feature Envy][file:line]LowP3Severity 建议按 Critical / High / Medium / Low 分级Priority 用 P1/P2/P3 排优先级。SKILL 建议优先处理三类坏味道阻塞当前开发的、导致 bug 或混淆的、影响改动最频繁的代码路径。逐项详细分析每个坏味道单独成段模板给出四个字段Location精确定位到path/to/file.js:45-120含行号范围Description详细描述问题Impact列出影响点可读性、可测试性、修改波及面等Proposed Solution初步修复方案概述。仓库配套的自动化检测工具仓库为此提供了开箱即用的坏味道扫描脚本 detect-smells.py支持 Python / JavaScript / TypeScript 文件python 03-skills/refactor/scripts/detect-smells.py file # 分析单个文件 python 03-skills/refactor/scripts/detect-smells.py --dir src/ # 分析整个目录 python 03-skills/refactor/scripts/detect-smells.py -v file # 详细模式带代码片段 python 03-skills/refactor/scripts/detect-smells.py -j file # JSON 输出便于程序化处理从脚本源码detect-smells.py可以看到其检测阈值设计THRESHOLDS { long_method_lines: 30, # 超过 30 行即视为 Long Method中等 very_long_method_lines: 50, # 超过 50 行升级为高严重度 max_parameters: 4, # 超过 4 个参数视为 Long Parameter List large_class_lines: 300, # 类超过 300 行 large_class_methods: 10, # 类方法超过 10 个 max_nesting_depth: 4, # 嵌套深度超过 4 层 long_chain_length: 3, # 消息链超过 3 次调用 duplicate_min_lines: 5, # 重复代码块的最小行数 }脚本内置 14 类坏味道检测SmellType 枚举覆盖模板汇总表中常见的 Long Method、Long Parameter List、Duplicate Code、Large Class、Dead Code、Magic Number、Feature Envy、Switch Statement 等并输出按严重度分级的可读报告。这意味着模板中Identified Code Smells表格的数据可以直接由脚本生成无需纯手工排查。完整的坏味道定义可查阅 code-smells.md 目录其中按 Bloaters臃肿类、Change Preventers阻碍变更类等分类收录了包括 Long Method、Large Class、Primitive Obsession、Long Parameter List、Data Clumps、Switch Statements、Feature Envy、Message Chains、Shotgun Surgery 等在内的 22 种坏味道每种都附带症状 → 危害 → 对应重构手法 → 前后代码示例。六、Refactoring PhasesA/B/C 三阶段风险递进模板的核心思想是把重构拆成三个风险递进的阶段这与 SKILL 中CRITICAL: Introduce refactoring gradually in phases的硬性要求一致。Phase A: Quick Wins低风险立竿见影Objective: Simple improvements with immediate value简单改进即时价值Estimated Changes: [X files, Y methods]User Approval Required: Yes / NoQuick Wins 通常可以更低门槛但模板仍保留审批开关#TaskFileRefactoringStatusA1Rename variablextouserCountutils.js:15Rename Variable[ ]A2Remove unusedoldHandler()api.js:89Remove Dead Code[ ]A3Extract duplicate validationform.js:23,67Extract Method[ ]Rollback Plan: Revert commits A1-A3回滚方案直接回退 A1–A3 的提交Quick Wins 的特点是改动小、语义直白重命名、删死代码、抽取明显重复即便出错也容易回滚因此回滚方案可以是整段 revert。Phase B: Structural Improvements中风险结构性改进Objective: Improve code organization and clarity改善代码组织与清晰度Estimated Changes: [X files, Y methods]User Approval Required: YesDependencies: Phase A must be complete依赖 Phase A 完成#TaskFileRefactoringStatusB1ExtractcalculatePrice()from long methodorder.js:45Extract Method[ ]B2IntroduceOrderDetailsparameter objectorder.js:12Introduce Parameter Object[ ]B3MoveformatAddress()to Address classcustomer.js:78Move Method[ ]Rollback Plan: Revert to post-Phase-A commit回滚方案回退到 Phase A 结束后的提交点这一阶段开始改变结构抽取方法、引入参数对象、移动方法因此必须显式要求用户批准且明确依赖 Phase A 完成——用前一阶段的稳定提交作为回滚锚点。Phase C: Architectural Changes高风险架构级调整Objective: Address deeper structural issues解决深层结构问题Estimated Changes: [X files, Y methods]User Approval Required: YesDependencies: Phases A and B must be complete依赖 Phase A 和 B 完成#TaskFileRefactoringStatusC1Replace price switch with polymorphismpricing.js:30Replace Conditional with Polymorphism[ ]C2ExtractNotificationServiceclassuser.js:100Extract Class[ ]Rollback Plan: Revert to post-Phase-B commit回滚方案回退到 Phase B 结束后的提交点Phase C 涉及设计层面的变更条件逻辑替换为多态、抽取新类风险最高模板要求 A、B 两阶段全部完成后才能启动每个任务的回滚点都建立在上一阶段的稳定提交之上——这正是小步前进、随时可退原则的工程化体现。坏味道与重构手法的对应关系SKILL 的 Phase 4 提供了一张臭名昭著的映射表填 Phase A/B/C 任务表时可直接对照使用Code SmellRecommended Refactoring(s)Long MethodExtract Method, Replace Temp with QueryDuplicated CodeExtract Method, Pull Up Method, Form Template MethodLarge ClassExtract Class, Extract SubclassFeature EnvyMove Method, Move FieldPrimitive ObsessionReplace Primitive with Object, Replace Type Code with ClassLong Parameter ListIntroduce Parameter Object, Preserve Whole ObjectData ClumpsExtract Class, Introduce Parameter ObjectSwitch StatementsReplace Conditional with PolymorphismSpeculative GeneralityCollapse Hierarchy, Inline Class, Remove Dead CodeDead CodeRemove Dead Code每种重构手法的完整动机 步骤机制 前后示例都在 refactoring-catalog.md 中例如 Phase B 示例用到的Introduce Parameter Object的机制是先为成组参数创建新类 → 用 Change Function Declaration 引入新对象 → 逐个移除原参数并测试Phase C 示例用到的Replace Conditional with Polymorphism的机制是创建类层次 → 用工厂函数创建对象 → 将条件逻辑下沉到各子类方法 → 删除原条件分支。七、Detailed Refactoring Steps每个任务的微步骤手册这是模板最可执行的部分把每个任务拆解成带验证点的微步骤。模板结构如下Task [ID]: [Task Name]Smell Addressed: [Smell name]解决哪个坏味道Refactoring Technique: [Technique name]用哪个重构手法对应 refactoring-catalog 中的条目Risk Level: Low / Medium / High单任务风险可与阶段风险不同Context上下文Before(Current State)// Paste current code hereAfter(Expected State)// Paste expected code here上下文区要求粘贴重构前后的真实代码这是评审与实施的关键依据——明确从什么变成什么。Step-by-Step Mechanics逐步机制模板给出了每步改动 立即测试的节奏范式Step 1: [Description]Test: Run tests after this step本步完成后运行测试Expected: All tests pass预期全部测试通过Step 2: [Description]Test: Run tests after this stepExpected: All tests passStep 3: [Description]Test: Run tests after this stepExpected: All tests pass这与 SKILL Phase 5Incremental Implementation的黄金法则完全一致Change → Test → Green? → Commit → Next stepSKILL 规定每步的完整节奏预检查测试绿、代码可编译→ 只做一个小改动 → 立即跑测试 → 绿则提交 → 红则立即停止并回退、分析原因、必要时询问用户。注意模板要求每个步骤都要跑测试而不是一个任务完成后才跑——这是行为保持原则的防线。Verification验证清单All tests passing所有测试通过Behavior unchanged行为未改变Code compiles代码可编译No new warnings无新增警告Commit Message提交信息refactor: [Describe the refactoring]提交信息统一使用refactor:前缀。SKILL 给出的范式示例refactor: Extract calculateTotal() from processOrder() refactor: Rename x to customerCount for clarity refactor: Remove unused validateOldFormat() methodSKILL 强调每个提交应满足三条标准Atomic一个逻辑变更一个提交、Reversible易回滚、Descriptive信息清晰。这保证了 Phase 表中每个任务的 Rollback Plan回退到特定阶段提交点是可执行的。八、Progress Tracking阶段状态与问题台账阶段状态表PhaseStatusStartedCompletedTests PassingANot Started / In Progress / DoneBNot Started / In Progress / DoneCNot Started / In Progress / Done每个阶段的状态在 Not Started / In Progress / Done 三态间流转同时记录开始/完成时间与测试是否通过——把质量门禁直接写进进度表。问题台账#IssueResolutionStatus1[Description][How resolved]Open / Resolved实施中遇到的任何问题都要登记包括如何解决以及当前是 Open 还是 Resolved。SKILL 还要求每个子阶段结束向用户汇报改了什么、测试是否仍通过、遇到哪些问题并询问是否继续下一批——进度表就是这些汇报的书面记录。九、Metrics Comparison用数据证明重构有效度量对比是重构计划的验收数据也是 SKILL Phase 6Review Iteration的标准动作。模板提供前后两套指标表Before RefactoringMetricFile 1File 2TotalLines of CodeCyclomatic ComplexityMaintainability IndexNumber of MethodsAvg Method LengthAfter RefactoringMetricFile 1File 2TotalChangeLines of CodeCyclomatic ComplexityMaintainability IndexNumber of MethodsAvg Method Length五类指标的含义可对照仓库配套脚本 analyze-complexity.py 的实现理解Lines of Code有效代码行数脚本会剔除空行与注释行见 count_lines 实现Cyclomatic Complexity圈复杂度基于 McCabe 方法CC E - N 2P简化实现为决策点数 1if/for/while/case 等每处 1衡量代码的分支复杂度calculate_cyclomatic_complexityMaintainability Index可维护性指数0–100 分综合 Halstead 量、圈复杂度和代码行数计算。解读标准为85–100 高度可维护、65–84 中等可维护、50–64 难以维护、0–49 极难维护calculate_maintainability_indexNumber of Methods / Avg Method Length方法数量与平均方法长度反映结构拆分程度。脚本提供了三种使用方式正好对应重构前 / 重构后 / 对比三种场景python 03-skills/refactor/scripts/analyze-complexity.py file # 分析单个文件 python 03-skills/refactor/scripts/analyze-complexity.py before.py after.py # 对比两个版本 python 03-skills/refactor/scripts/analyze-complexity.py --dir src/ # 分析整个目录 python 03-skills/refactor/scripts/analyze-complexity.py -v file # 详细输出每个函数指标 python 03-skills/refactor/scripts/analyze-complexity.py -j file # JSON 输出对比模式print_comparison会逐项输出 Before / After / Change并给出总体评估可维护性是否提升、复杂度是否下降、平均函数长度是否变小汇总为N 项改进、M 项回退。重构前先跑一次单文件模式填入 Before 表重构后再跑一次填入 After 表即可完成模板 Metrics Comparison 的数据化验收。注意圈复杂度、平均方法长度等指标越低越好可维护性指数越高越好若重构后指标不升反降模板的 Issues Encountered 表就是记录和分析这种回归的位置。十、Post-Refactoring Checklist 与 Lessons Learned收尾与复盘重构后检查清单All tests passing所有测试通过No new warnings or errors无新增警告或错误Code compiles successfully代码编译成功Manual verification completed人工验证完成Documentation updated (if needed)必要时更新文档Code reviewed代码已评审Metrics improved指标已改善User sign-off obtained用户签收确认这份清单对应 SKILL Phase 6 的收尾动作其中最后一项User sign-off与 SKILL 的提问一致Are you satisfied with these changes?你对这些改动满意吗。经验复盘What Went Well哪些环节做得好记录可复用的经验What Could Be Improved哪些环节可以改进Recommendations for Future对未来的建议。SKILL Phase 6 的 Next Steps 提供了三个复盘方向还有哪些坏味道要处理是否安排后续重构是否将相同手法应用到其他模块签核表ApprovalsRoleNameDateSignaturePlan AuthorTechnical LeadProduct Owner计划作者、技术负责人、产品负责人三方签核让重构计划获得组织层面的正式背书——这既是对范围的确认也是对风险的共同担责。附录AppendixA. Related Documentation相关文档链接B. Reference Materials链接到 坏味道目录 与 重构目录C. Tools Used测试框架、Lint 工具、复杂度分析工具清单可用 detect-smells.py 与 analyze-complexity.py 充当复杂度分析工具配合 pytest / npm test 等测试框架。十一、模板与 SKILL 工作流的位置关系最后把模板放回完整工作流中看它的坐标。整个 refactor SKILL 的工作流SKILL.md为Phase 1: Research Analysis → 研究目标代码、澄清范围与约束 ↓ Phase 2: Test Coverage Assessment → 评估测试覆盖构建安全网 ↓ Phase 3: Code Smell Identification → 识别坏味道并定优先级 ↓ Phase 4: Refactoring Plan Creation → ★ 产出本模板refactoring-plan.md ↓ Phase 5: Incremental Implementation → 小步实施每步测试、提交 ↓ Phase 6: Review Iteration → 度量对比、复盘、收尾签核模板的每个区块正好对应一个或多个阶段Project Information 与 Executive Summary 承接 Phase 1 的调研结论Pre-Refactoring Checklist 是 Phase 2 的质量门禁Identified Code Smells 是 Phase 3 的产物Refactoring Phases 与 Detailed Refactoring Steps 是 Phase 4 与 Phase 5 的交接物Progress Tracking、Metrics Comparison、Post-Refactoring Checklist、Lessons Learned 与 Approvals 则服务 Phase 6 的验收与复盘。使用模板时SKILL 还给出几条贯穿始终的安全红线Important Guidelines没有测试就不重构除非用户明确知晓风险绝不大改——拆成微小步骤每次改动后绝不跳过测试测试失败绝不继续——先修复或回滚绝不臆断——不确定就问不要把重构与功能新增混在一起不要在生产事故期间重构不要重构你不理解的代码不要过度设计。refactoring-plan.md 这份模板正是把这些原则表格化、可勾选、可跟踪的载体。把它与仓库自带的坏味道检测脚本、复杂度分析脚本和两份参考目录配合使用你就能从凭感觉改代码升级为有诊断、有计划、有数据、可回滚的工程化重构流程。【免费下载链接】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 的 refactoring-plan 模板把代码重构做成可跟踪的工程流程【免费下载链接】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 仓库中 03-skills/refactor 技能配套的 refactoring-plan 模板完整拆解项目信息 → 坏味道识别 → 分阶段重构 → 度量对比 → 复盘签核的整条重构管理链路。文章将以模板字段为主线结合仓库内的 坏味道目录、重构目录 以及 detect-smells.py、analyze-complexity.py 两个自动化脚本讲清每一步该填什么、为什么填、以及如何用数据验证重构效果。读完你可以直接把模板套用到自己的重构任务上形成一份可评审、可回滚、可量化的重构计划书。一、模板定位重构不是随手改代码而是一份可跟踪的工程计划refactoring-plan.md 的定位非常明确——它是 refactor SKILL 六阶段工作流中Phase 4重构计划创建的标准输出物。整个 SKILL 遵循 Martin Fowler 在Refactoring: Improving the Design of Existing Code第 2 版中提出的方法论核心信条是Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure.重构是在不改变代码外部行为的前提下改善其内部结构的过程。模板把这一原则落到实操层面先记录上下文再识别坏味道然后分风险等级排期最后用指标验证行为未变、结构更好。它本质上是一份贯穿重构前、中、后的唯一事实来源Single Source of Truth让团队评审、逐阶段批准、中途回滚和事后复盘都有据可依。模板的使用方式很简单复制03-skills/refactor/templates/refactoring-plan.md到你的项目里按章节填充。下文逐节展开每个区块的填写要点与背后的技术支撑。二、Project Information用一张表锁定重构范围模板开篇要求填写项目信息四个字段看似简单却是整个计划的坐标系FieldValue填写要点Project/Module[Project name]精确到模块名避免含糊的整个系统Target Files[List of files to refactor]列出全部目标文件建议带相对路径Date Created[Date]计划创建日期Author[Name]计划作者便于追溯StatusDraft / In Review / Approved / In Progress / Completed生命周期状态机随评审推进流转Status的五种取值对应了计划从草稿到落地的完整生命周期这也是模板可评审属性的体现只有状态流转到 Approved才允许进入实施阶段。与之呼应SKILL 的 Phase 1Research Analysis要求在此前先向用户澄清五个关键问题确保范围准确Scope哪些文件/模块/函数需要重构Goals要解决什么问题可读性、性能、可维护性Constraints哪些区域绝对不能动Timeline pressure是否阻塞其他工作Test status测试是否存在是否通过这些答案正是填充 Project Information 的信息来源。模板中 Target Files 之所以要精确列举是因为后续所有坏味道定位、阶段任务拆分和度量对比都依赖这个文件清单。三、Executive Summary目标、约束与风险分级执行摘要区由三组复选框构成是计划核心决策的浓缩Goals目标按优先级列出重构要达成的结果模板给出的范式是[Primary goal: e.g., Improve readability of payment processing]主要目标如提升支付处理代码的可读性[Secondary goal: e.g., Reduce code duplication]次要目标如减少代码重复[Tertiary goal: e.g., Improve testability]第三目标如提升可测试性Constraints约束明确重构的边界防止范围蔓延。模板提供了三个典型约束[Constraint 1: e.g., Cannot change public API]不能改公开 API[Constraint 2: e.g., Must maintain backward compatibility]必须保持向后兼容[Constraint 3: e.g., No changes to database schema]不改数据库 schemaRisk Level风险等级为整个重构工作定调Low - Minor changes, well-tested code低改动小、测试充分的代码Medium - Moderate changes, some risk中改动中等、有一定风险High - Significant changes, careful attention needed高改动显著、需高度谨慎风险等级不是拍脑袋它与后文的 Phase A/B/C 风险分层直接挂钩——低风险任务进 Quick Wins 阶段高风险任务进 Architectural Changes 阶段。SKILL 的 Safety Rules 也明确要求Never make big changes - break into tiny steps风险分级正是把大重构拆成小步提交的依据。四、Pre-Refactoring Checklist没有测试安全网一切重构都免谈重构前检查清单是 SKILL 中Phase 2Test Coverage Assessment的落地工具。SKILL 引用了一句重要论断Refactoring without tests is like driving without a seatbelt.没有测试的重构就像不系安全带开车。测试覆盖评估表MetricCurrentTargetStatusUnit Test Coverage__%≥80%Integration TestsYes/NoYesAll Tests PassingYes/NoYes模板把单元测试覆盖率 ≥80%和集成测试必须存在设为硬性目标且要求所有测试必须通过才能开工。SKILL Phase 2 给出的具体操作是检查现有测试find . -name *test* -o -name *spec* | head -20运行测试JavaScript/TypeScript 用npm testPython 用pytest -vJava 用mvn test检查覆盖率npm run test:coverage或pytest --cov.SKILL 还规定了三种情况的处理决策测试存在且通过→ 进入 Phase 3坏味道识别测试缺失或不完整→ 提供三个选项先补测试推荐、重构中增量补测试、无测试继续有风险需用户明确确认测试失败→ 立即 STOP先修测试再谈重构。开工前必备条件All tests passing所有测试通过Code reviewed and understood代码已评审且被理解Backup/version control in place备份/版本控制就绪User approval obtained已获得用户批准最后一项与 SKILL 的Collaborative原则用户须在每个阶段批准保持一致。如果测试缺口较大SKILL 建议对每个待重构函数至少覆盖三类场景happy path正常路径、edge cases空输入、null、边界、error scenarios非法输入、异常并遵循red-green-refactor红绿重构循环。五、Identified Code Smells坏味道登记表与逐项分析这一节对应 SKILL 的Phase 3Code Smell Identification是重构计划的诊断书。汇总表#SmellLocationSeverityPriority1[e.g., Long Method][file:line]HighP12[e.g., Duplicate Code][file:line]MediumP23[e.g., Feature Envy][file:line]LowP3Severity 建议按 Critical / High / Medium / Low 分级Priority 用 P1/P2/P3 排优先级。SKILL 建议优先处理三类坏味道阻塞当前开发的、导致 bug 或混淆的、影响改动最频繁的代码路径。逐项详细分析每个坏味道单独成段模板给出四个字段Location精确定位到path/to/file.js:45-120含行号范围Description详细描述问题Impact列出影响点可读性、可测试性、修改波及面等Proposed Solution初步修复方案概述。仓库配套的自动化检测工具仓库为此提供了开箱即用的坏味道扫描脚本 detect-smells.py支持 Python / JavaScript / TypeScript 文件python 03-skills/refactor/scripts/detect-smells.py file # 分析单个文件 python 03-skills/refactor/scripts/detect-smells.py --dir src/ # 分析整个目录 python 03-skills/refactor/scripts/detect-smells.py -v file # 详细模式带代码片段 python 03-skills/refactor/scripts/detect-smells.py -j file # JSON 输出便于程序化处理从脚本源码detect-smells.py可以看到其检测阈值设计THRESHOLDS { long_method_lines: 30, # 超过 30 行即视为 Long Method中等 very_long_method_lines: 50, # 超过 50 行升级为高严重度 max_parameters: 4, # 超过 4 个参数视为 Long Parameter List large_class_lines: 300, # 类超过 300 行 large_class_methods: 10, # 类方法超过 10 个 max_nesting_depth: 4, # 嵌套深度超过 4 层 long_chain_length: 3, # 消息链超过 3 次调用 duplicate_min_lines: 5, # 重复代码块的最小行数 }脚本内置 14 类坏味道检测SmellType 枚举覆盖模板汇总表中常见的 Long Method、Long Parameter List、Duplicate Code、Large Class、Dead Code、Magic Number、Feature Envy、Switch Statement 等并输出按严重度分级的可读报告。这意味着模板中Identified Code Smells表格的数据可以直接由脚本生成无需纯手工排查。完整的坏味道定义可查阅 code-smells.md 目录其中按 Bloaters臃肿类、Change Preventers阻碍变更类等分类收录了包括 Long Method、Large Class、Primitive Obsession、Long Parameter List、Data Clumps、Switch Statements、Feature Envy、Message Chains、Shotgun Surgery 等在内的 22 种坏味道每种都附带症状 → 危害 → 对应重构手法 → 前后代码示例。六、Refactoring PhasesA/B/C 三阶段风险递进模板的核心思想是把重构拆成三个风险递进的阶段这与 SKILL 中CRITICAL: Introduce refactoring gradually in phases的硬性要求一致。Phase A: Quick Wins低风险立竿见影Objective: Simple improvements with immediate value简单改进即时价值Estimated Changes: [X files, Y methods]User Approval Required: Yes / NoQuick Wins 通常可以更低门槛但模板仍保留审批开关#TaskFileRefactoringStatusA1Rename variablextouserCountutils.js:15Rename Variable[ ]A2Remove unusedoldHandler()api.js:89Remove Dead Code[ ]A3Extract duplicate validationform.js:23,67Extract Method[ ]Rollback Plan: Revert commits A1-A3回滚方案直接回退 A1–A3 的提交Quick Wins 的特点是改动小、语义直白重命名、删死代码、抽取明显重复即便出错也容易回滚因此回滚方案可以是整段 revert。Phase B: Structural Improvements中风险结构性改进Objective: Improve code organization and clarity改善代码组织与清晰度Estimated Changes: [X files, Y methods]User Approval Required: YesDependencies: Phase A must be complete依赖 Phase A 完成#TaskFileRefactoringStatusB1ExtractcalculatePrice()from long methodorder.js:45Extract Method[ ]B2IntroduceOrderDetailsparameter objectorder.js:12Introduce Parameter Object[ ]B3MoveformatAddress()to Address classcustomer.js:78Move Method[ ]Rollback Plan: Revert to post-Phase-A commit回滚方案回退到 Phase A 结束后的提交点这一阶段开始改变结构抽取方法、引入参数对象、移动方法因此必须显式要求用户批准且明确依赖 Phase A 完成——用前一阶段的稳定提交作为回滚锚点。Phase C: Architectural Changes高风险架构级调整Objective: Address deeper structural issues解决深层结构问题Estimated Changes: [X files, Y methods]User Approval Required: YesDependencies: Phases A and B must be complete依赖 Phase A 和 B 完成#TaskFileRefactoringStatusC1Replace price switch with polymorphismpricing.js:30Replace Conditional with Polymorphism[ ]C2ExtractNotificationServiceclassuser.js:100Extract Class[ ]Rollback Plan: Revert to post-Phase-B commit回滚方案回退到 Phase B 结束后的提交点Phase C 涉及设计层面的变更条件逻辑替换为多态、抽取新类风险最高模板要求 A、B 两阶段全部完成后才能启动每个任务的回滚点都建立在上一阶段的稳定提交之上——这正是小步前进、随时可退原则的工程化体现。坏味道与重构手法的对应关系SKILL 的 Phase 4 提供了一张臭名昭著的映射表填 Phase A/B/C 任务表时可直接对照使用Code SmellRecommended Refactoring(s)Long MethodExtract Method, Replace Temp with QueryDuplicated CodeExtract Method, Pull Up Method, Form Template MethodLarge ClassExtract Class, Extract SubclassFeature EnvyMove Method, Move FieldPrimitive ObsessionReplace Primitive with Object, Replace Type Code with ClassLong Parameter ListIntroduce Parameter Object, Preserve Whole ObjectData ClumpsExtract Class, Introduce Parameter ObjectSwitch StatementsReplace Conditional with PolymorphismSpeculative GeneralityCollapse Hierarchy, Inline Class, Remove Dead CodeDead CodeRemove Dead Code每种重构手法的完整动机 步骤机制 前后示例都在 refactoring-catalog.md 中例如 Phase B 示例用到的Introduce Parameter Object的机制是先为成组参数创建新类 → 用 Change Function Declaration 引入新对象 → 逐个移除原参数并测试Phase C 示例用到的Replace Conditional with Polymorphism的机制是创建类层次 → 用工厂函数创建对象 → 将条件逻辑下沉到各子类方法 → 删除原条件分支。七、Detailed Refactoring Steps每个任务的微步骤手册这是模板最可执行的部分把每个任务拆解成带验证点的微步骤。模板结构如下Task [ID]: [Task Name]Smell Addressed: [Smell name]解决哪个坏味道Refactoring Technique: [Technique name]用哪个重构手法对应 refactoring-catalog 中的条目Risk Level: Low / Medium / High单任务风险可与阶段风险不同Context上下文Before(Current State)// Paste current code hereAfter(Expected State)// Paste expected code here上下文区要求粘贴重构前后的真实代码这是评审与实施的关键依据——明确从什么变成什么。Step-by-Step Mechanics逐步机制模板给出了每步改动 立即测试的节奏范式Step 1: [Description]Test: Run tests after this step本步完成后运行测试Expected: All tests pass预期全部测试通过Step 2: [Description]Test: Run tests after this stepExpected: All tests passStep 3: [Description]Test: Run tests after this stepExpected: All tests pass这与 SKILL Phase 5Incremental Implementation的黄金法则完全一致Change → Test → Green? → Commit → Next stepSKILL 规定每步的完整节奏预检查测试绿、代码可编译→ 只做一个小改动 → 立即跑测试 → 绿则提交 → 红则立即停止并回退、分析原因、必要时询问用户。注意模板要求每个步骤都要跑测试而不是一个任务完成后才跑——这是行为保持原则的防线。Verification验证清单All tests passing所有测试通过Behavior unchanged行为未改变Code compiles代码可编译No new warnings无新增警告Commit Message提交信息refactor: [Describe the refactoring]提交信息统一使用refactor:前缀。SKILL 给出的范式示例refactor: Extract calculateTotal() from processOrder() refactor: Rename x to customerCount for clarity refactor: Remove unused validateOldFormat() methodSKILL 强调每个提交应满足三条标准Atomic一个逻辑变更一个提交、Reversible易回滚、Descriptive信息清晰。这保证了 Phase 表中每个任务的 Rollback Plan回退到特定阶段提交点是可执行的。八、Progress Tracking阶段状态与问题台账阶段状态表PhaseStatusStartedCompletedTests PassingANot Started / In Progress / DoneBNot Started / In Progress / DoneCNot Started / In Progress / Done每个阶段的状态在 Not Started / In Progress / Done 三态间流转同时记录开始/完成时间与测试是否通过——把质量门禁直接写进进度表。问题台账#IssueResolutionStatus1[Description][How resolved]Open / Resolved实施中遇到的任何问题都要登记包括如何解决以及当前是 Open 还是 Resolved。SKILL 还要求每个子阶段结束向用户汇报改了什么、测试是否仍通过、遇到哪些问题并询问是否继续下一批——进度表就是这些汇报的书面记录。九、Metrics Comparison用数据证明重构有效度量对比是重构计划的验收数据也是 SKILL Phase 6Review Iteration的标准动作。模板提供前后两套指标表Before RefactoringMetricFile 1File 2TotalLines of CodeCyclomatic ComplexityMaintainability IndexNumber of MethodsAvg Method LengthAfter RefactoringMetricFile 1File 2TotalChangeLines of CodeCyclomatic ComplexityMaintainability IndexNumber of MethodsAvg Method Length五类指标的含义可对照仓库配套脚本 analyze-complexity.py 的实现理解Lines of Code有效代码行数脚本会剔除空行与注释行见 count_lines 实现Cyclomatic Complexity圈复杂度基于 McCabe 方法CC E - N 2P简化实现为决策点数 1if/for/while/case 等每处 1衡量代码的分支复杂度calculate_cyclomatic_complexityMaintainability Index可维护性指数0–100 分综合 Halstead 量、圈复杂度和代码行数计算。解读标准为85–100 高度可维护、65–84 中等可维护、50–64 难以维护、0–49 极难维护calculate_maintainability_indexNumber of Methods / Avg Method Length方法数量与平均方法长度反映结构拆分程度。脚本提供了三种使用方式正好对应重构前 / 重构后 / 对比三种场景python 03-skills/refactor/scripts/analyze-complexity.py file # 分析单个文件 python 03-skills/refactor/scripts/analyze-complexity.py before.py after.py # 对比两个版本 python 03-skills/refactor/scripts/analyze-complexity.py --dir src/ # 分析整个目录 python 03-skills/refactor/scripts/analyze-complexity.py -v file # 详细输出每个函数指标 python 03-skills/refactor/scripts/analyze-complexity.py -j file # JSON 输出对比模式print_comparison会逐项输出 Before / After / Change并给出总体评估可维护性是否提升、复杂度是否下降、平均函数长度是否变小汇总为N 项改进、M 项回退。重构前先跑一次单文件模式填入 Before 表重构后再跑一次填入 After 表即可完成模板 Metrics Comparison 的数据化验收。注意圈复杂度、平均方法长度等指标越低越好可维护性指数越高越好若重构后指标不升反降模板的 Issues Encountered 表就是记录和分析这种回归的位置。十、Post-Refactoring Checklist 与 Lessons Learned收尾与复盘重构后检查清单All tests passing所有测试通过No new warnings or errors无新增警告或错误Code compiles successfully代码编译成功Manual verification completed人工验证完成Documentation updated (if needed)必要时更新文档Code reviewed代码已评审Metrics improved指标已改善User sign-off obtained用户签收确认这份清单对应 SKILL Phase 6 的收尾动作其中最后一项User sign-off与 SKILL 的提问一致Are you satisfied with these changes?你对这些改动满意吗。经验复盘What Went Well哪些环节做得好记录可复用的经验What Could Be Improved哪些环节可以改进Recommendations for Future对未来的建议。SKILL Phase 6 的 Next Steps 提供了三个复盘方向还有哪些坏味道要处理是否安排后续重构是否将相同手法应用到其他模块签核表ApprovalsRoleNameDateSignaturePlan AuthorTechnical LeadProduct Owner计划作者、技术负责人、产品负责人三方签核让重构计划获得组织层面的正式背书——这既是对范围的确认也是对风险的共同担责。附录AppendixA. Related Documentation相关文档链接B. Reference Materials链接到 坏味道目录 与 重构目录C. Tools Used测试框架、Lint 工具、复杂度分析工具清单可用 detect-smells.py 与 analyze-complexity.py 充当复杂度分析工具配合 pytest / npm test 等测试框架。十一、模板与 SKILL 工作流的位置关系最后把模板放回完整工作流中看它的坐标。整个 refactor SKILL 的工作流SKILL.md为Phase 1: Research Analysis → 研究目标代码、澄清范围与约束 ↓ Phase 2: Test Coverage Assessment → 评估测试覆盖构建安全网 ↓ Phase 3: Code Smell Identification → 识别坏味道并定优先级 ↓ Phase 4: Refactoring Plan Creation → ★ 产出本模板refactoring-plan.md ↓ Phase 5: Incremental Implementation → 小步实施每步测试、提交 ↓ Phase 6: Review Iteration → 度量对比、复盘、收尾签核模板的每个区块正好对应一个或多个阶段Project Information 与 Executive Summary 承接 Phase 1 的调研结论Pre-Refactoring Checklist 是 Phase 2 的质量门禁Identified Code Smells 是 Phase 3 的产物Refactoring Phases 与 Detailed Refactoring Steps 是 Phase 4 与 Phase 5 的交接物Progress Tracking、Metrics Comparison、Post-Refactoring Checklist、Lessons Learned 与 Approvals 则服务 Phase 6 的验收与复盘。使用模板时SKILL 还给出几条贯穿始终的安全红线Important Guidelines没有测试就不重构除非用户明确知晓风险绝不大改——拆成微小步骤每次改动后绝不跳过测试测试失败绝不继续——先修复或回滚绝不臆断——不确定就问不要把重构与功能新增混在一起不要在生产事故期间重构不要重构你不理解的代码不要过度设计。refactoring-plan.md 这份模板正是把这些原则表格化、可勾选、可跟踪的载体。把它与仓库自带的坏味道检测脚本、复杂度分析脚本和两份参考目录配合使用你就能从凭感觉改代码升级为有诊断、有计划、有数据、可回滚的工程化重构流程。【免费下载链接】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），仅供参考
