refactor-planning

name	refactor-planning
description	重构计划文档编写范式，从问题分析到最终交付的完整流程。 仅当用户明确说出"使用 refactor-planning"或"启动 refactor-planning"时触发。 不适用于任何隐式场景。

重构计划编写范式

编写高质量重构执行文档，确保 Agent 可执行、自包含、精简平衡。

触发约束

此 skill 仅通过显式调用触发。

⛔ 不触发的场景

• 用户提到"规划重构"、"写个计划"等但未提及 refactor-planning
• 用户直接说"帮我重构代码"（这是执行任务，不是编写文档）
• 用户未显式引用 @refactor-planning

✅ 触发条件

必须同时满足：

1. 用户明确说出"使用 refactor-planning"或"启动 refactor-planning"，或显式引用 @refactor-planning
2. 用户需要编写重构执行文档或规划重构批次

---

文件命名约定

格式：{YY}-{MM}-{DD}-{分类}-{任务名}.md

日期

创建日期，年份2位：25-05-13

分类

分类	含义	内容
issues	问题发现	痛点分析、现象描述、影响范围
plan	解决计划	步骤、改动清单、验证方式
resolved	解决记录	执行结果、实际改动、验证结果

状态流转：issues → plan → resolved

任务名

kebab-case，跨文档保持一致，用于自动关联：

25-05-13-issues-status-embedding.md   # 发现问题
25-05-13-plan-status-embedding.md     # 制定计划
25-05-14-resolved-status-embedding.md # 解决完成（跨天）

版本区分

同一天同任务多次迭代，用 -v2、-v3：

25-05-14-issues-refactor.md      # 第一次发现问题
25-05-14-issues-refactor-v2.md   # 同天深入分析
25-05-14-plan-refactor.md        # 第一次计划
25-05-14-plan-refactor-v2.md     # 同天调整计划

---

核心原则

原则一：问题驱动深入分析

不要表面总结。深入探查：

• 耦合问题（改一处要 grep 全项目）
• 模块边界（一个文件多种职责）
• 命名规范（私有函数是否导出）
• 注释质量（冗余删除、缺失补充）

统计具体数据（不是"代码质量不错"）。

原则二：敢于删除，但要精准定位

删除比保留好。 不留：

• 兼容层、过渡函数
• TODO、后续优化
• 备份注释、冗余代码

删除要精准定位，不能只靠路径。删除清单必须包含：

• 文件路径
• 内容特征（grep 具体内容）
• 删除条件（特征匹配才删除）

目的：精准删除目标文件，防止误删隔天新增文件。不是为了阻止删除。

原则三：先建后删

执行顺序：先建 → 改引用 → 验证 → 删除

绝不能先删再建。

原则四：文档自包含

文档必须自包含：

• 不引用外部文档
• 不依赖当前对话记忆
• 不假设行号（用 grep 定位）

原则五：精简平衡

文档不能膨胀：

• 代码示例只给关键片段（2-5行）
• 删除清单用表格 + grep 定位
• 目标：≤1000行

---

执行流程

Phase 1：问题驱动深入分析

痛点来源：

1. 用户描述的问题（如"改一处要改很多地方"）
2. 代码扫描发现的模式（分散定义、重复逻辑）
3. git history 中的反复修复（同一文件多次修改）
4. 日志/监控/用户报告的现象（必须验证是否真的是缺陷）

识别方法：

Step 1: 关键词定位
       从用户描述提取关键词，或扫描高频模式

Step 2: 统计分散程度
       grep -r "{关键词}" src/ | wc -l
       多处出现 → 可能是耦合问题

Step 3: 检查边界模糊
       一个文件导入多个模块 → 可能边界不清
       一个函数超过50行 → 可能职责混杂

Step 4: 检查命名一致性
       私有函数是否导出？
       同类功能命名风格是否统一？

Step 5: 现象追问（新增）
       看到 WARNING/ERROR → 问"为什么会这样？"
       统计数据异常 → 问"异常是否真的是问题？"
       例：thinking tokens < 1000 → 问"短输入是否正常？"
       例：超时 479s → 问"单次超时还是累计？根因是什么？"

Step 6: 根因验证（新增）
       提出根因假设后，必须验证：
       - grep 代码实现 → 确认代码行为
       - 查文档或测试 → 确认 API/框架行为
       - 对比预期 vs 实际 → 确认假设是否正确
       例：假设"API 默认启用 thinking" → 验证代码（参数传递逻辑）+ 日志（实际返回）
       例：假设"未传参数导致默认启用" → 验证代码逻辑是否真的"未传"

Step 7: 确认是否是缺陷（新增）
       现象是否异常？（不是看到 WARNING 就是缺陷）
       根因是否正确？（不是提出假设就认为正确）
       只有确认后才能输出痛点分析文档

输出痛点分析文档，包含具体数据和位置。

Phase 2：执行原则确立

文档开头写入执行原则：

• 敢于删除，但要精准定位（grep 内容特征）
• 改完验证，失败就修，不回退
• 不留尾巴

Phase 3：批次规划

确定批次顺序和依赖关系。

批次划分依据：

依据 1: 改动范围
       基础设施层（底层） → 业务逻辑层（上层） → 清理工作（最后）

依据 2: 依赖方向
       被依赖的先改 → 依赖者的后改
       （用导入关系判断：grep "from.*{模块}" 判断依赖链）

依据 3: 风险等级
       低风险（新建、删除） → 高风险（改引用、改接口）

依赖识别方法：

Step 1: 找被改模块
       grep -r "from.*{模块}" src/ → 谁依赖它？

Step 2: 找改动影响
       grep -r "{函数名}" src/ → 谁调用它？

Step 3: 确定批次顺序
       被依赖的模块 → 批次1
       依赖者 → 批次2
       清理工作 → 批次3

输出格式：

批次1 → 批次2 → 批次3...
(基础设施) (业务逻辑) (清理工作)

依赖关系：列出关键依赖

Phase 4：文档编写

每个批次包含：

• 目标（一句话）
• 步骤1：新建（关键函数签名，不给完整代码）
• 步骤2：改引用（改前改后对比，2-5行）
• 步骤3：验证（测试命令）
• 步骤4：删除（表格 + 精准定位）

删除清单格式：

| 序号 | 文件路径 | 内容特征 | 删除条件 |
|------|----------|---------|---------|
| 1 | path/to/file.py | grep "特征内容" $文件 | 匹配则删除 |

精准定位目的：确保删除的是目标文件（防止误删新增文件），不是为了阻止删除。

Phase 5：质量检查

格式检查：

• 是否引用外部文档？
• 是否依赖对话记忆？
• 是否假设行号？
• 是否膨胀超过1000行？

内容质量检查：

• 痛点是否量化？（不是"代码质量不错"，而是"分散定义 12 处"）
• 现象是否验证？（不是看到 WARNING 就判断为缺陷）
• 根因是否验证？（不是提出假设就认为正确，必须对比代码/API 行为）
• 批次划分是否有依据？（依赖关系、改动范围）
• 每个步骤是否有执行方法？（新建 → 改引用 → 验证 → 删除）

不符合时修正。

Phase 6：agent 视角检查（可选）

触发条件：重构涉及多个批次或复杂依赖链时执行。

模拟执行：

1. 模拟执行批次1
2. 检查：新建函数是否有签名说明？
3. 检查：改引用是否有改前改后对比？
4. 检查：删除是否有 grep 定位？
5. 发现问题时补充方法

不符合时修正，符合时跳过此环节。

Phase 7：用户纠正触发重新规划

用户纠正时，重新审视全文档，不是局部修补。

不辩解，直接重新规划。

Phase 8：最终交付

交付物：

• 自包含
• 精简（≤1000行）
• 执行顺序清晰
• 删除清单具体

---

反模式

反模式	正确做法
表面总结"代码不错"	统计具体数据（分散定义 X 处）
删除清单只给路径（无内容特征）	增加"内容特征"列，精准定位再删除
先删再建	先建 → 改引用 → 验证 → 删除
引用外部文档	改为自包含说明
假设行号	改为 grep 定位
文档膨胀	精简代码示例
用户纠正时辩解	直接重新规划
批次划分无依据	用依赖关系、改动范围确定顺序
步骤只有名称（如"新建"）	补充执行方法（函数签名、改前改后对比）
看到 WARNING 直接判断为缺陷	追问"为什么会这样？是否正常？" + 验证根因假设
提出根因假设后直接写方案	验证假设：对比代码/API 行为，确认后才写方案