代码能跑，但结构需要改善时使用。目标是在不改变外部行为的前提下提升可读性、减少耦合、让 AI 后续操作更容易。
什么时候用
以下情况考虑重构：
– 函数超过 50 行，做了不止一件事
– 下次修改这块代码时，AI 需要理解太多隐式上下文
– 想对某个模块加功能，但现有结构让改动变得危险
不适合的场景：代码逻辑本身有错，那是 bug 修复，不是重构。
准备什么
- 目标代码：要重构的函数或模块全文，不是片段
- 重构目标：具体说明想改善什么。”更好”不够具体，要说”拆分成两个职责单一的函数”或”消除对全局变量 X 的依赖”
- 不能改动的部分：对外接口签名、已有测试依赖的行为、被其他模块直接调用的函数名
“不能改动的部分”最容易被忽略。没有明确说明时，AI 可能改了调用方依赖的接口，导致其他地方编译失败。
怎么触发
单次任务
先读 04-prompt/code/refactoring.md，
目标代码在 [文件路径]，
重构目标：[具体说明]，
不能改动：[列出接口名、函数名]。
请进行重构。
写入 CLAUDE.md
## 重构
重构代码时：
1. 要求输出重构后的完整代码，不是 diff
2. 要求列出每项改动和改动原因
3. 要求标出哪些行为变化需要人工核查
好的输出是什么样的
- 输出完整代码，不是只给出差异部分（diff 在真实项目里很难直接应用）
- 每项改动有对应的一句话说明：改了什么、为什么这样改
- 明确标出有哪些行为变化需要人工核查（即使是”无行为变化”也要明确说）
- 不引入新的运行时依赖
常见失败模式
- 改了不该改的接口：没有明确说明不能改动的部分。重构前先列清楚哪些是外部依赖
- 大泥球代码无从下手：一个函数混合了三层职责，AI 的拆分方向是错的。这种情况先人工确定边界，再让 AI 执行
- 只给 diff：AI 默认给差异描述，修改代码时难以直接用。明确要求”输出完整代码”
- 行为悄悄变了：重构后某个边界条件的处理方式改变了，但没有提示。要求 AI 列出所有潜在行为变化
版本历史
- v1.0：初始版本