Claude Code 重构 Skill 实战指南基于 Martin 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本文系统讲解 claude-howto 仓库中refactorSkillzh/03-skills/refactor/SKILL.md的完整使用方法。该 Skill 把 Martin Fowler《Refactoring: Improving the Design of Existing Code》第 2 版的重构方法论固化为一套可被 Agent 自动执行的六阶段工作流适用于重构代码、改进结构、降低技术债、清理旧代码、消除 code smell 或提升可维护性的场景。读完本文你将掌握如何让 Claude Code 在测试保障下以小步、可回滚的方式安全重构代码并学会使用仓库配套的复杂度分析与代码异味检测脚本。“重构是在不改变软件外部行为的前提下改进其内部结构的过程。” — Martin FowlerSkill 定位与触发机制refactorSkill 是标准的 Agent Skills 文件系统型能力其目录结构遵循 Skill 约定03-skills/refactor/ ├── SKILL.md # 主指令六阶段工作流 ├── references/ │ ├── code-smells.md # 代码异味完整目录按类别组织 │ └── refactoring-catalog.md # 重构手法目录含机械步骤 ├── templates/ │ └── refactoring-plan.md # 重构计划模板 └── scripts/ ├── analyze-complexity.py # 复杂度指标分析器 └── detect-smells.py # 代码异味自动检测器SKILL.md 的 YAML frontmatter 通过description字段声明触发条件当用户请求重构代码、改进代码结构、减少技术债、清理旧代码、消除 code smell 或提升可维护性时Claude 会自动匹配并激活该 Skill。这是渐进式披露Progressive Disclosure架构的典型实践——metadata 常驻上下文约 100 tokenSKILL.md 正文在触发时加载约 5k token 以内而 references、templates、scripts 等资源按需加载。核心原则安全重构的五个基石Skill 定义了五条不可动摇的核心原则贯穿整个工作流保持行为不变Behavior Preservation外部行为必须保持一致这是重构区别于重写的根本边界小步前进Small Steps每次只做很小、可测试的改动测试驱动Test-Driven测试是安全网没有测试的重构风险极高持续进行Continuous重构是长期过程不是一次性任务协作确认Collaborative每个阶段都需要用户确认Claude 不得擅自推进。工作流总览六阶段流水线Skill 将整个重构过程编排为六个递进阶段阶段 1研究与分析 ↓ 阶段 2测试覆盖评估 ↓ 阶段 3识别代码异味 ↓ 阶段 4创建重构计划 ↓ 阶段 5增量实施 ↓ 阶段 6评审与迭代下面逐一展开每个阶段的执行要点。阶段 1研究与分析目标理解代码库结构和用途、确定重构范围、收集业务需求背景。开始前先向用户确认五个问题范围哪些文件/模块/函数需要重构、目标解决可读性、性能还是可维护性问题、约束哪些区域不能改、时间压力是否阻塞其他工作、测试状态是否已有测试、是否通过。行动清单阅读并理解目标代码识别依赖和集成点记录当前架构标记已有技术债迹象TODO、FIXME阶段输出向用户汇报代码结构总结、识别出的问题区域、初步建议并请求继续执行的批准。阶段 2测试覆盖评估“没有测试的重构就像没有安全带就开车。” — Martin Fowler评估步骤查找现有测试find . -name *test* -o -name *spec* | head -20运行现有测试按语言选择# JavaScript / TypeScript npm test # Python pytest -v # Java mvn test检查覆盖率如果可用# JavaScript npm run test:coverage # Python pytest --cov.决策点测试存在且通过 → 进入阶段 3测试缺失或不完整 → 给出三个选项让用户选择先写测试推荐、重构过程中逐步补测试、不写测试直接继续有风险需用户确认测试失败 →停止先修复失败测试再重构。测试编写建议每个待重构函数应覆盖正常路径、边界情况空输入、null、边界值和错误场景非法输入、异常并遵循红-绿-重构循环先写失败测试红→ 让它通过绿→ 再重构。阶段 3识别代码异味什么是代码异味代码深层问题的表面症状。它们不一定是 bug但说明代码设计可能有问题。完整目录见 references/code-smells.md下表是快速参考异味迹象影响长函数函数超过 30-50 行难以理解、测试和维护重复代码多处出现相同逻辑修复需要改多处大类类承担了太多职责违反单一职责原则Feature Envy一个方法更多依赖别的类的数据封装性差基础类型沉迷过度使用基础类型而不是对象缺少领域概念长参数列表方法参数超过 4 个调用困难数据泥团一组数据总是一起出现缺少抽象switch 语句复杂的 switch / if-else 链难以扩展臆想泛化以防未来需要提前设计不必要的复杂度死代码未使用的代码造成困惑和维护负担分析步骤自动分析运行配套脚本python scripts/detect-smells.py file脚本位于 03-skills/refactor/scripts/detect-smells.py人工审查系统走读代码记录每个异味的位置和严重性按影响分类Critical / High / Medium / Low优先级排序优先关注阻塞当前开发、导致 bug 或混淆、影响最常变更代码路径的异味。输出向用户呈现识别出的异味及位置、每项的严重性评估、建议的优先级顺序并请求用户确认优先级。深度补充代码异味目录的五大家族代码异味目录 将常见异味归为五类理解分类有助于快速定位问题根源Bloaters臃肿者长得过大而难以有效处理的代码包括长函数、大类、基础类型沉迷、长参数列表、数据泥团。目录给出具体检测阈值如类代码行数 300、方法数 15、字段数 10可判定为大类Object-Orientation Abusers面向对象滥用者对 OOP 原则的不完整或不正确使用包括 switch 语句、临时字段Temporary Field、拒绝遗赠Refused Bequest违反 Liskov 替换原则、接口不同的相似类Change Preventers变更阻碍者改一处却要连带改多处包括发散式变更Divergent Change、霰弹式修改Shotgun Surgery增加一个字段需要改动超过 5 个文件、平行继承体系Dispensables可丢弃物应删除的无用之物包括过度注释区分解释what的坏注释与解释why的好注释、重复代码检测规则任何代码重复 3 次以上应提取、懒人 ClassLazy Class、死代码、臆想泛化YAGNICouplers耦合者类之间过度耦合包括 Feature Envy行为放错了位置、过度亲密Inappropriate Intimacy、消息链Message Chains违反迪米特法则、中间人Middle Man。目录还附带严重性分级指南Critical 立即修复 / High 当前迭代修复 / Medium 近期排期 / Low 顺手修复和快速检测清单例如是否存在超过 30 行的方法超过 300 行的类超过 4 个参数的方法基于类型码的 switch解释what而非why的注释阶段 4创建重构计划选择重构手法针对每个异味从 refactoring-catalog.md 中选择合适的重构手法。下面是异味到重构的映射表代码异味推荐重构长函数Extract Method、Replace Temp with Query重复代码Extract Method、Pull Up Method、Form Template Method大类Extract Class、Extract SubclassFeature EnvyMove Method、Move Field基础类型沉迷Replace Primitive with Object、Replace Type Code with Class长参数列表Introduce Parameter Object、Preserve Whole Object数据泥团Extract Class、Introduce Parameter Objectswitch 语句Replace Conditional with Polymorphism臆想泛化Collapse Hierarchy、Inline Class、Remove Dead Code死代码Remove Dead Code计划结构使用 templates/refactoring-plan.md 模板。每项重构都要写明Target改哪些代码、Smell解决什么问题、Refactoring采用哪种手法、Steps详细微步骤、Risks可能出什么问题、Rollback如何回退。分阶段方法关键——重构必须按风险递增分阶段推进阶段 A快速收益低风险高价值重命名变量提升清晰度、提取明显重复的代码、删除死代码阶段 B结构改进中风险从长函数中提取方法、引入参数对象、把方法移动到更合适的类阶段 C架构改动高风险用多态替代条件分支、提取类、引入设计模式。决策点实施前展示完整重构计划解释每个阶段及其风险获得每个阶段的明确批准并询问是否继续执行阶段 A深度补充重构计划模板的关键结构重构计划模板 是贯穿整个重构过程的追踪文档包含项目信息与风险等级Low/Medium/High、重构前测试覆盖评估单元覆盖率目标 ≥80%、识别出的异味汇总表含位置、严重性、优先级、按 A/B/C 三阶段组织的任务清单每阶段含回滚计划、每项任务的逐步机械步骤每步都要求运行测试并预期全绿、进度追踪、重构前后指标对比、事后检查清单、经验教训与审批记录。深度补充重构目录中的核心手法重构目录 遵循 Fowler 的定义——重构由它的机械步骤mechanics定义即你执行改动所遵循的精确步骤序列并给出黄金法则如果某一步骤超过 10 分钟就把它拆成更小的步骤。常用手法包括Extract Method提取函数把代码片段提取为以做什么命名的函数。机械步骤为创建新方法 → 复制代码片段 → 扫描局部变量 → 将局部变量转为参数 → 处理返回值 → 用调用替换原片段 → 测试Inline Method内联函数当方法体与其名字一样清晰或存在过度委托时用方法体替换每个调用点逐个替换并测试最后删除方法定义Extract Variable / Inline Variable为复杂表达式命名或消除不必要的间接层Rename Variable使用意图揭示型命名、避免缩写、采用领域术语Change Function Declaration修改函数名或参数复杂变更采用迁移式——创建新函数、旧函数委托新函数、逐个迁移调用者、删除旧函数Introduce Parameter Object把经常一起出现的参数如startDate/endDate组合成对象如DateRangeSplit Phase拆分阶段用中间数据结构隔离两个不同关注点如价格计算与运费计算Replace Primitive with Object为基础类型引入带行为的值对象如Priority类封装合法值校验与比较逻辑Replace Temp with Query把临时变量提取为查询方法Decompose Conditional / Consolidate Conditional Expression / Replace Nested Conditional with Guard Clauses分别用于拆分复杂条件、合并同结果条件、用卫语句提前返回简化深层嵌套Replace Conditional with Polymorphism为类型码分支建立类层级 工厂函数让对象自己处理行为Introduce Special Case (Null Object)用特例对象替代重复的 null 检查Separate Query from Modifier把有返回值且带副作用的函数拆成纯查询 纯修改Move Method / Move Field把函数和字段移到使用它们最多的类Pull Up Method / Push Down Method / Replace Subclass with Delegate处理继承体系中的重复或误用Extract Class拆分承担多职责的大类模板中的Person与TelephoneNumber拆分是典型示例。阶段 5增量实施黄金法则修改 → 测试 → 通过→ 提交 → 下一步实施节奏——对每一步重构预检查测试通过绿色、代码能编译只做一个小改动按目录中的具体操作进行保持改动最小化验证立刻运行测试、检查编译错误测试通过绿色用描述清晰的提交信息提交继续下一步测试失败红色立刻停止、撤销改动、分析原因如有疑问询问用户。提交策略每次提交都应满足——原子性只包含一个逻辑改动、可回滚容易撤销、描述清楚提交信息明确。示例refactor: 从 processOrder() 中提取 calculateTotal() refactor: 将 x 重命名为 customerCount 以提升清晰度 refactor: 删除未使用的 validateOldFormat() 方法进度汇报每个子阶段完成后向用户汇报做了哪些改动、测试是否仍通过、遇到什么问题并询问继续下一批吗阶段 6评审与迭代重构后检查清单所有测试通过没有新的警告 / 错误代码编译成功行为没有变化手动验证必要时已更新文档提交历史干净指标对比重构前后运行复杂度分析脚本展示改进python scripts/analyze-complexity.py file关注代码行数变化、圈复杂度变化、可维护性指标变化。用户评审展示所有变更摘要、重构前后代码对比、指标改善情况、剩余技术债并询问你对这些改动满意吗下一步与用户讨论还要处理哪些异味、是否安排下一次重构、是否把类似修改应用到其他地方。配套脚本的源码级用法detect-smells.py自动检测代码异味脚本入口位于 03-skills/refactor/scripts/detect-smells.py支持 Python、JavaScript、TypeScript。基本用法python scripts/detect-smells.py myfile.py # 分析单个文件 python scripts/detect-smells.py --dir src/ # 分析整个目录 python scripts/detect-smells.py -v myfile.py # 详细模式附带代码片段 python scripts/detect-smells.py -j myfile.py # JSON 输出便于程序化处理从源码可以看出检测阈值集中定义在THRESHOLDS字典中且可配置阈值默认值说明long_method_lines30超过即报告长方法Mediumvery_long_method_lines50超过升级为 Highmax_parameters4参数上限Python 自动排除 self/clslarge_class_lines300大类行数上限large_class_methods10大类方法数上限max_nesting_depth4最大嵌套深度long_chain_length3消息链长度阈值duplicate_min_lines5重复代码判定脚本共集成 11 个检测器detect_all()依次调用长方法、长参数列表、大类、复杂条件单行 3 个以上逻辑运算符、魔法数字排除 0/1/-1/2/100 等常见值、过度注释检测解释 what 的关键词、深层嵌套Python 按缩进、JS/TS 按花括号、switch 语句Python 检测连续 4 个以上if/elif 链、消息链、重复代码规范化后相同行出现 3 次以上、死代码TODO delete、if False等模式。每条发现都带严重级别Critical/High/Medium/Low、位置、描述与修复建议输出末尾给出按严重级排序的推荐行动。analyze-complexity.py量化重构收益脚本入口位于 03-skills/refactor/scripts/analyze-complexity.py支持三种模式python scripts/analyze-complexity.py myfile.py # 分析单个文件 python scripts/analyze-complexity.py before.py after.py # 对比模式重构前后 python scripts/analyze-complexity.py --dir src/ # 分析整个目录 python scripts/analyze-complexity.py -v myfile.py # 详细模式含函数级指标 python scripts/analyze-complexity.py -j myfile.py # JSON 输出从源码看核心指标包括圈复杂度Cyclomatic Complexity采用 McCabe 简化法基础值 1 加上各决策点if/elif/for/while/except/and/or/case/try等计数认知复杂度Cognitive Complexity追踪嵌套深度嵌套结构成本递增break/return/throw等线性流程中断在深层时加分可维护性指数Maintainability Index基于 Halstead 体积、圈复杂度和代码行数的近似计算取值范围 0-10085 高度可维护、65-84 中等、50-64 困难、0-49 极难代码行数 / 函数数 / 类数 / 平均函数长度 / 最长函数。对比模式特别适合阶段 6它会输出一个指标对照表Before / After / Change对可维护性提升、复杂度下降、平均函数长度缩小逐项打勾评估并汇总improvements / regressions结论为重构成效提供量化证据。重要指南何时停下与安全规则遇到以下情况务必暂停并和用户确认不确定业务逻辑、改动可能影响外部 API、测试覆盖不足、需要做重大架构决策、风险上升、遇到意外复杂性。安全规则五不没有测试不要重构除非用户明确确认风险不要做大改动拆成小步每次改动后都不要跳过测试测试失败就不要继续先修复或回滚不要臆测不确定就问。不要做什么不要把重构和新功能混在一起不要在生产事故期间做重构不要重构你看不懂的代码不要过度设计保持简单不要一次性重构所有内容。快速上手示例长函数 重复逻辑重构前function processOrder(order) { // 150 行代码包含 // - 重复验证逻辑 // - 内联计算 // - 多种职责混杂 }重构步骤确认测试存在覆盖processOrder()提取验证逻辑为validateOrder()测试- 应该通过提取计算逻辑为calculateOrderTotal()测试- 应该通过提取通知逻辑为notifyCustomer()测试- 应该通过评审-processOrder()现在只负责串联 3 个清晰函数重构后function processOrder(order) { validateOrder(order); const total calculateOrderTotal(order); notifyCustomer(order, total); return { order, total }; }这个最小闭环完整示范了小步前进 每步测试 最后评审的核心节奏是所有复杂重构的原子单元。与仓库其他模块的协作位置在 claude-howto 的 Skill 体系中refactorSkill 与 code-review-specialist评审定位问题和 doc-generator重构后文档更新可形成评审 → 重构 → 文档化的完整链路其 Skill 骨架结构SKILL.md references templates scripts也是 03-skills/README.md 中渐进式披露架构的参考实现之一。Skill 的脚本均为标准 Python 3无第三方依赖可直接在任意 Python 环境执行。参考资料代码异味目录 - 按五大家族分类的完整异味清单含检测阈值、示例与严重性指南重构目录 - 重构手法及其机械步骤含异味到重构的快速映射表重构计划模板 - 贯穿全程的计划与追踪文档analyze-complexity.py - 复杂度指标分析器含重构前后对比模式detect-smells.py - 自动代码异味检测器11 种检测器、可配置阈值Agent Skills 总览 - 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考