用途
duck-refactor 用于支持多文件代码重构，通过有界重构操作、显式引用追踪和验证来完成代码结构调整。它适用于用户要求重构、提取、跨文件重命名、移动代码、内联或转换模式时。
触发短语包括：
- "refactor this"
- "extract this function/class/method"
- "rename this across the codebase"
- "move this to another file"
- "inline this function"
- "convert this callback to promise"
主要能力
- 多文件重构，带引用追踪。
- 在编辑前追踪引用与依赖：定位目标代码的所有用法、映射导入/导出、识别调用方与被调用方、查找引用目标的测试文件、记录外部依赖。
- 在编辑前给出有界重构计划，包含操作类型、目标、目的地、目标阶段、受影响文件、变更列表和验证方式。
- 应用 Duck Ladder 原则：无需改动（YAGNI）、复用现有本地辅助函数/模式、替换为标准库/原生实现、使用已安装依赖、缩小到最小安全差异，最后才新增代码或抽象。
- 要求执行批准：在获得明确批准前不进行多文件重构。
- 执行重构：按定义先于用法、导入先于代码的顺序修改，更新导入/导出，保持格式一致，保留记录持久约束、不变量、契约或行为的准确注释和文档。
- 验证重构：运行验证计划，确认测试通过、无损坏导入、类型检查通过（如适用）、功能不变。
使用方式
该技能按以下方法执行：
-
澄清重构范围：当上下文不完整时提出 1-3 个有针对性的澄清问题；证据缺失时明确说明假设。范围问题包括：提取/重命名/移动/内联什么？目标位置（新文件、现有文件、新函数名）？范围边界（本模块、整个代码库）？
-
追踪引用与依赖：使用只读证据收集，输出类似 "Found N references across M files: [list]"。
-
呈现重构计划：在编辑前给出有界计划，格式包含操作、目标、目的地、目标阶段、受影响文件、变更列表和验证方式。如果超出阶段上限或触发审查疲劳，则询问是否拆分为更小的有界重构。
-
应用 Duck Ladder：在提出重构方案前，依次考虑无需改动、复用现有本地辅助函数/模式、替换为标准库/原生实现、使用已安装依赖、缩小到最小安全差异，最后才新增代码或抽象。
-
要求执行批准：在执行重构前，明确目标阶段、目标文件、预期结构变更和验证计划，等待用户回复 "approve" 后执行。
-
执行重构：获得批准后，按顺序修改，更新导入/导出，保持格式一致，保留准确的持久性注释和文档。
-
验证重构：运行验证计划，报告测试结果和变更文件数量。
当作为子代理运行且没有用户通道时（例如通过 duckling），不应用编辑或运行验证命令。执行步骤 1-5 作为分析；将步骤 6 "执行重构" 和步骤 7 "验证" 替换为批准包内容：推导出的逐文件变更计划（适用时包含差异块）和验证计划。按宿主包装器的契约输出（预检 + 差异 + 批准请求 + 状态页脚）。
适用场景
- 需要跨多个文件进行代码结构调整时。
- 需要提取函数、类或方法时。
- 需要在代码库中重命名标识符时。
- 需要将代码移动到另一个文件时。
- 需要内联函数时。
- 需要将回调转换为 Promise 等模式转换时。
限制
该技能明确区分于其他技能：
- 与 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。
- 如果某项变更会削弱信任边界验证、安全控制、数据丢失预防、无障碍要求或明确的用户要求，拒绝该变更，并仅提供保留该约束的安全替代方案。
注释和文档完整性要求：
- 记录持久约束、不变量、契约和行为。
- 不要在代码注释或普通文档中叙述开发历史。
- 移除或标记被拒绝的方法、"这曾经是" 历史、近期变更上下文，以及仅解释变更如何产生的评审、测试或会话引用。
- 不要在持久工件中保留仅会话决策、批准标志或临时标记。
- 仅在用于历史的持久工件（如 ADR 或变更日志）中保留历史上下文。
- 仅当测试或评审引用陈述持久约束或验证要求时才保留。
技能特定差异：多文件重构操作需要执行批准并带完整引用追踪。与单文件补丁和复杂度削减区分开。