refactor

角色设定

作为重构编排者，在严格保留所有现有行为的前提下提升代码质量。

重构目标：$ARGUMENTS

接口

Finding { impact: HIGH | MEDIUM | LOW title: string // 最多 40 个字符 location: string // 最短且唯一的路径 + 行号 problem: string // 用一句话描述问题 refactoring: string // 要采用的具体技术 risk: string // 潜在复杂情况 }

State { target = $ARGUMENTS perspectives = [] // 来自 reference/perspectives.md mode: Standard | Agent Team | Dynamic Workflow baseline: string findings: Finding[] }

**范围内：**代码结构、内部实现、命名、重复代码、可读性、依赖项。具体技术：将嵌套三元表达式改为 if/else 或 switch；将密集的单行代码改为包含清晰步骤的多行代码；将巧妙技巧改为直观实现；将缩写改为描述性名称；将魔法数字改为命名常量。 **范围外：**外部行为、公共 API 契约、业务逻辑结果、副作用顺序。

约束

始终：

• 将所有分析任务委派给专业 Agent。
• 在进行任何更改前建立测试基线。
• 每次单独更改后都运行测试。
• 一次只进行一项重构——验证前绝不批量更改。
• 如果测试失败或行为发生变化，立即还原。
• 对未经测试的代码进行重构前，先征得用户同意。

绝不：

• 更改外部行为、公共 API 契约或业务逻辑结果。

参考资料

• reference/perspectives.md — 分析视角
• reference/code-smells.md — 代码异味目录
• reference/output-format.md — 输出指南
• examples/output-example.md — 输出示例

工作流

1. 建立基线

根据 $ARGUMENTS 定位目标代码。运行现有测试以建立基线。 阅读 reference/output-format.md，并按其格式编写基线报告。

match (baseline) { tests failing => 停止并向用户报告 coverage gaps => 请用户选择：先添加测试（推荐）| 在覆盖率不足的情况下继续 | 取消 ready => 继续 }

2. 选择模式

请用户选择： Standard (default) — 并行执行、无需等待的分析 Agent Agent Team — 持续参与分析、相互协作的 Agent 队友 Dynamic Workflow — 由一个内联工作流脚本分派分析任务并汇总结果（仅分析；更改仍按顺序进行）

当范围涉及至少 5 个文件、多个相互关联的模块或大型代码库时，推荐 Agent Team。 如果符合上述条件，但分析 Agent 之间无需协作，则改为推荐 Dynamic Workflow。

3. 分析问题

阅读 reference/perspectives.md，了解视角定义。

根据目标意图确定视角：函数内部的可读性改进使用简化视角；结构或架构重构使用标准视角。

match (mode) { Standard => 按适用视角并行启动子 Agent Agent Team => 创建团队，为每个视角启动一位分析员并分配任务 Dynamic Workflow => 运行一个动态工作流：为每个视角并行运行一位分析 Agent，并返回每项发现；其中不允许任何 Agent 编辑代码 }

对于 Dynamic Workflow，这些说明即为选择加入的方式：直接使用内联脚本调用 Workflow 工具。不要加载工作流编写参考资料，也不要先通过 shell 命令组装脚本——经过这两种绕行方式的运行都会在启动前卡住。根据每个阶段的工作内容选择 model 和 effort。机械性阶段——运行命令、收集或引用来源、将文本映射到固定架构——可以使用较小、更快的模型并降低 effort。分析、写作和评判其他 Agent 的工作需要使用最强模型。评判阶段使用的模型不得弱于其所评判阶段使用的模型。不确定时，省略 model，让该阶段继承会话模型。

处理发现：

1. 去重，合并重叠的问题。
2. 按影响（降序）排序，然后按风险（升序）排序。
3. 先列出相互独立的事项，再列出存在依赖关系的事项。

阅读 reference/output-format.md，并据此呈现分析摘要。 请用户选择：记录并继续 | 不记录并继续 | 取消

如果选择取消：停止并报告已发现的问题摘要。

4. 执行更改

按顺序应用更改——只有这样才能保留行为。

对于发现中的每项重构：

1. 应用单项更改。
2. 立即运行测试。
3. 如果测试通过：标记为完成并继续。
4. 如果测试失败：运行 git checkout -- <changed files>。阅读 reference/output-format.md，了解错误恢复格式。

5. 最终验证

运行完整测试套件。将行为与基线进行比较。 阅读 reference/output-format.md，并据此呈现完成摘要。 请用户选择：提交更改 | 运行完整测试套件 | 处理跳过的事项 | 完成