Python Refactor 是一个专注于 Python 代码重构的技能，核心目标是把复杂、难以理解的代码转化为清晰、可维护的等价实现，同时严格保持原有行为不变。它采用分阶段工作流，强调安全优先与持续验证，适合需要系统性重构而非零散清理的场景。
用途
当用户明确要求“可读”“可维护”“干净”或“重构”的代码时，当代码评审指出理解或维护问题、需要遗留代码现代化、用于上手或教学场景，或复杂度指标超过阈值时，可以调用该技能。典型危险信号包括：文件超过 500 行且函数分散、存在全局状态、多个 global 语句、没有清晰的模块或类组织、配置与业务逻辑混杂。
不适用场景包括：代码属于性能关键路径且性能分析表明应优先做性能优化；代码计划被删除或替换；外部依赖需要向上游贡献而非本地重构；用户明确要求性能优化优先于可读性。
主要能力
技能围绕四条核心原则展开：对复杂代码优先采用结构化 OOP（共享状态、多重关注点、分散全局变量应重构为类或模块，但简单纯函数模块、click/argparse CLI 和函数式管道不必强行套类）；清晰优先于聪明；保持正确性；单一职责；自文档化结构；渐进式披露；性能合理（未经明确批准不得牺牲超过 2 倍性能）。
硬性约束包括：安全优先设计，破坏性改动必须使用迁移检查清单；静态分析先行，先跑 flake8 --select=F821,E0602 或 ruff check --select=F821 再跑测试；保持行为不变；无性能回退；无 API 变更；不过度工程；不使用魔法；持续验证。
回归预防是强制要求：每次会话前测试套件需 100% 通过、目标代码覆盖率不低于 80%、捕获关键边界用例的黄金输出、保存静态分析基线；每个微改动后都要跑静态分析与 pytest，任一检查失败即停止、回退、分析、修正方案后重试。任何回归都视为彻底失败。
使用方式
工作流分为四个阶段。第一阶段分析：通读代码，识别可读性问题（脚本式/全局状态、上帝对象、嵌套条件、长函数、魔法数字、晦涩命名），评估架构，测量复杂度指标，运行 lint，检查测试覆盖并补齐缺口，输出按影响与风险排序的问题清单。第二阶段规划：把改动分为非破坏性（重命名、文档、类型提示）与破坏性（移除全局、删除函数、替换 API），破坏性改动必须制定迁移计划，搜索所有使用点并记录，评估风险，绘制依赖图，制定测试策略与回滚计划，按从最安全到最高风险排序。第三阶段执行：非破坏性改动可随时进行；破坏性改动严格遵循 CREATE → SEARCH → MIGRATE → VERIFY → REMOVE，一次迁移一个使用点，每步后跑静态分析与测试，100% 迁移验证后才删除旧代码。第四阶段验证：先静态分析，再全量测试，验证架构，输出前后指标对比，对热路径做性能回归检查，生成总结报告；若性能下降超过 10%、公共 API 签名变化、测试覆盖率下降或架构重大变化，则标记人工评审。
技能提供重构模式目录，包括守卫子句、提取方法、字典分发、match 语句、命名布尔条件、封装全局状态、按职责分组函数、创建领域模型、依赖注入等。命名约定方面，变量要描述性，布尔用 is_active/has_permission/can_edit，集合用复数；函数用动词加对象；常量用大写加下划线；类用 PascalCase 名词。反模式按优先级修复：关键级为脚本式/过程式代码与全局状态、上帝对象；高级为超过 3 层的嵌套条件、超过 30 行的长函数、魔法数字、晦涩命名、缺少类型提示与文档字符串；中级为重复代码、基本类型偏执、超过 5 个参数的长参数列表；低级为命名不一致、冗余注释、未使用导入。
工具链方面，推荐 Ruff + Complexipy 作为主栈，安装命令为 uv tool install ruff complexipy radon wily，可用 ruff check src/ 做快速 lint，complexipy src/ --max-complexity-allowed 15 测认知复杂度，radon mi src/ -s 测可维护性指数。也支持 flake8 加精选插件。scripts/analyze_multi_metrics.py 可合并 complexipy、radon 与可维护性指数生成单一报告。指标目标：圈复杂度每函数小于 10（警告 15，错误 20），认知复杂度每函数小于 15（警告 20），函数长度小于 30 行（警告 50），嵌套深度不超过 3 层，公共函数文档字符串覆盖率大于 80%，公共 API 类型提示覆盖率大于 90%。可用 Wily 做历史趋势跟踪。
适用场景
适合遗留代码现代化、代码评审后的可读性整改、教学与上手、复杂度指标超标后的系统性重构。与 clean-code 相比，python-refactor 是 Python 专用的深度重构，涉及 OOP 转换、SOLID、复杂度指标、迁移检查清单与基准验证；升级路径为 clean-code → python-refactor。可与 python-tdd、python-performance-optimization、python-packaging、uv-package-manager、async-python-patterns 等技能集成。
限制
无法改进算法复杂度（那属于算法变更）；无法添加代码或注释中不存在的领域知识；没有测试就无法保证正确性；风格偏好因团队而异，需按团队约定调整。成功标准包括零回归、关键用例黄金主匹配、复杂度指标改善、性能回退不超过 10%、文档覆盖提升、代码更易理解、无新增安全漏洞、原子化且文档良好的 git 历史、Wily 趋势不劣于上一提交、静态分析显示改善。