Python 代码整理与重构

解决什么问题

很多 Python 项目一开始只是脚本或实验代码，但随着模块增多，很快出现 命名不一致、import 混乱、目录职责不清、注释和文档缺失等问题。直接“重构”又容易过度：给几行脚本加完整测试、配置系统甚至 DDD 分层，会让项目变得更难读。

这个技能把整理过程约束为 先评估、再确认、后执行，避免默认执行所有优化。它不是自动格式化工具，而是围绕项目类型和工程化目标，给出一套可批准的整理方案。

技能如何工作

• 第一轮：策略选择：扫描项目规模、类型和主要问题，给出四个可选级别：轻量清理、标准整理、深度重构、全面重构，并说明推荐理由。
• 第二轮：方案确认：列出目录调整、文件修改、删除项、新增配置和文档变更，等待明确批准。
• 执行阶段：按策略执行代码格式、命名规范、import 排序、类型标注、注释规范、死代码清理、配置参数化或测试补充。
• 文档生成：根据策略级别生成 README.md、CHANGELOG.md 和 NOTE.md，分别面向使用者、变更追踪和个人快速参考。

对 深度学习项目，它会优先处理 models/、data/、experiments/、超参数配置和日志机制；对 Web/API 项目，会关注路由、中间件和鉴权拆分；对 CLI/数据处理管道，会强调配置集中、日志与进度展示。

适用边界

该技能最适合 需要维护的 Python 项目，尤其是原型工具、数据处理脚本、小型服务或可发布库。它不适用于追求“看起来最规范”的盲目工程化：如果只是跑通实验，通常选择轻量或标准整理即可；只有项目需要团队协作、发布或长期维护时，才适合启用深度重构或全面重构。执行过程中仍依赖用户确认，不会未经批准删除文件或大幅调整结构。