duck-refactor

结构化重构 🦆。跟踪引用的多文件重组。

目的

通过范围明确的重构操作，并显式跟踪和验证引用，支持代码重组。

理念护栏（技能专属）

继承 references/GUARDRAILS.md 中的共享护栏。

注释和文档完整性

• 记录持久约束、不变量、契约和行为。
• 不要在代码注释或普通文档中叙述开发历史。
• 删除或标记已否决的方案、“过去曾经如此”的历史、近期变更背景，以及仅用于说明变更如何产生的评审、测试或会话引用。
• 不要在持久性产物中保留仅适用于当前会话的决策、审批标记或临时标记。
• 仅在专门用于记录历史的持久性产物（如 ADR 或变更日志）中保留历史背景。
• 仅当测试或评审引用说明持久约束或验证要求时，才予以保留。

技能专属补充规则：

• 多文件重构操作必须获得执行审批，并完整跟踪引用。
• 将多文件重构与单文件补丁及复杂度降低区分开来。

启用条件

用户要求重构、提取、跨文件重命名、移动代码、内联或转换模式时使用。

触发短语：

• “重构这个”
• “提取这个函数/类/方法”
• “在整个代码库中重命名这个”
• “把这个移到另一个文件”
• “内联这个函数”
• “将这个回调转换为 promise”

方法

子 Agent 执行模式

作为没有用户通道的子 Agent 运行时（例如通过 duckling）：不要应用编辑或运行验证命令。将步骤 1-5 作为分析执行；将步骤 6“执行重构”和步骤 7“验证”替换为审批材料：派生的逐文件变更计划（适用时提供 diff 块）和验证计划。按照宿主包装器的约定输出（预检 + diff + 审批请求 + 状态页脚）。

1. 明确重构范围

• 上下文不完整时，提出 1-3 个有针对性的澄清问题
• 缺少证据时，明确说明假设

任何细节不清楚时，提出一个范围界定问题：

• 要提取、重命名、移动或内联什么？
• 目标位置是什么（新文件、现有文件、新函数名）？
• 范围边界是什么（此模块、整个代码库）？

2. 跟踪引用和依赖项

使用只读证据收集方式（类似 duck-debug 跟踪模式）：

• 找出目标代码的所有用法
• 梳理导入/导出
• 找出调用方和被调用方
• 查找引用目标代码的测试文件
• 记录外部依赖项

输出：“在 M 个文件中找到 N 个引用：[列表]”

3. 提出重构计划

任何编辑之前，先提出范围明确的计划：

格式：

Refactoring plan:
- Operation: [extract function / rename / move / inline / convert]
- Target: [current name/location]
- Destination: [new name/location]
- Target phase: [Phase 1 stubs/interfaces | Phase 2 wiring/integration | Phase 3 concrete implementation]
- Files affected: [bounded list for selected phase]

Changes:
1. [file A]: [change description]
2. [file B]: [change description]

Verification: [tests to run, imports to check]

如果超出阶段上限或触发评审疲劳：“此重构超出当前阶段范围。是否拆分为更小、范围明确的重构？”

4. 应用 Duck Ladder

提出重构方案之前：

1. 无需更改（YAGNI）
2. 复用现有本地辅助函数/模式
3. 替换为标准库/原生功能
4. 使用已安装的依赖项
5. 缩小到最小安全 diff
6. 仅在此之后添加新代码/抽象

询问：“现有代码/模式是否已能解决问题？能否复用而不重组？”

5. 要求执行审批

执行重构之前：

• 目标阶段（Phase 1/2/3）
• 目标文件（限定在所选阶段范围内）
• 预期结构变更（哪些内容移动到哪里）
• 验证计划（测试、导入、类型检查）

使用执行审批流程：

• 回复 "approve" 以执行此重构。
• 等待明确审批
• 未经审批，不得继续多文件重构

6. 执行重构

获得批准后：

1. 按顺序进行更改（先定义，再使用；先导入，再编写代码）
2. 更新导入/导出
3. 保持格式一致
4. 保留准确记录持久约束、不变量、契约或行为的注释和文档。重构暴露出开发过程说明和仅适用于当前会话的决策引用时，应将其改写。

7. 验证重构

运行验证计划：

• 测试仍然通过
• 没有损坏的导入
• 类型检查器通过（如适用）
• 功能保持不变

报告：“重构完成。验证：[测试结果]。[N] 个文件已更改。”

边界

与其他技能的区别：

• 与 duck-patch 相比：duck-refactor 是多文件重构；duck-patch 是单文件错误修复
• 与 duck-simplify 相比：duck-refactor 是中立的重构；duck-simplify 是以特定目标为导向的复杂度降低
• 与 duck-design 相比：duck-refactor 负责实现；duck-design 负责决策/权衡分析
• 与 duck-debug 相比：duck-refactor 会更改代码；duck-debug 只追踪/调查

duck-refactor 不做的事：

• 不涉及重构的单文件编辑 -> 使用 duck-patch
• 以降低复杂度为主要目标 -> 使用 duck-simplify
• 架构决策 -> 使用 duck-design
• 仅移动文件而不更改代码 -> 使用 duck-patch

范围限制：

• 阶段上限（默认）：阶段 1 最多 6 个文件，阶段 2 最多 4 个文件，阶段 3 最多 2 个文件

• 如果超出阶段上限或触发审核疲劳条件，应拆分为更小且范围明确的审批

• 如果重构需要设计决策，请暂停并先转交给 duck-design

• 如果重构暴露出复杂度问题，请记录下来，以便后续交由 duck-simplify 处理

• 如果某项更改会削弱信任边界验证、安全控制、防止数据丢失的措施、无障碍要求或明确的用户要求，请拒绝该更改，并仅提供保留这些约束的安全替代方案。