对项目或者文件进行重构

概述

在进行详细的思考后，将一个指定的功能或者组件文件，进行重构。

从开始了解当前项目的上下文开始，然后一次询问一个问题来确认重构的方向和思路。

当你了解了你想要重构的步骤和范围后，将整个设计以一个小章节呈现，然后确认所有章节中的内容是否正确。

过程

了解重构的范围和步骤

• 前置检查：首先检查当前项目的状态（files, docs, recent, commits）。
• 单次提问：每次仅提问一个问题以细化思路。
• 选项优先：尽可能提供多选题，但也接受开放式回答。
• 循序渐进：如果一个话题需要深入探讨，请将其拆分为多个单次提问。
• 核心目标：明确目的、约束条件和成功指标。
• 副作用：询问用户是否有依赖于该组件的隐蔽逻辑，或者是否有现成的自动化测试覆盖。

探索方案

• 提供选项：提出2~3种具有不同优缺点的实现方案。
• 对话式建议：以对话方式呈现方案，给出你的推荐方案并解释原因。
• 逻辑支撑：优先展示推荐选项，并说明其合理性。
• 重构动机：明确重构的类型，动机不同，重构的方案也会完全不同：
  • A，代码坏味道修复。
  • B， 性能优化。
  • C，解耦/抽象化。
  • 等等。

展示设计

• 分段呈现： 确认理解需求后，开始展示设计方案。
• 字数限制： 每个部分尽量简洁明了，不要长篇大论。
• 分段确认： 每展示完一个部分，必须询问用户：“目前为止看起来还可以吗？”
• 覆盖范围： 架构设计、组件构成、数据流向、错误处理、测试策略。
• 灵活调整： 如果用户感到困惑，随时准备退回上一步进行澄清。

实现准备（如需继续）

• 询问用户：准备好进入实现阶段了吗？
• 环境隔离： 使用 Git Worktrees 创建独立的开发工作空间。
• 详细计划： 制定详细的执行步骤（Implementation Plan）。
• 快照/基准测试：在动代码之前，先运行一遍现有测试或建立基准，确保重构后的输出与重构前一致。

实现过程（如需继续）

• 隔离操作： 切换到Git Worktrees 创建独立的开发工作空间进行操作。
• 小步快走：每完成一小部分的重构，就应该执行一次小范围测试
  • 基准建立：在开始前运行现有测试，若无测试则优先补齐核心逻辑的单元测试。
  • 红绿循环： 采用类似 TDD 的节奏，修改一小步 -> 验证测试 -> 提交。
  • 兼容性检查：确保导出接口（API）在重构期间保持向下兼容，除非明确要求修改接口。
  • 记录更新： 在每一小步完成后，都应该更新任务方案中的任务清单。
• 重构记录：测试通过后，就应该将这一小步重构提交到git，使用格式<类型><(范围)>: 完成了哪些任务。
• 合并回归：当整个重构过程都完成后，进行一次全量测试，测试通过后，将这个独立的开发分支合并回去，具体合并到哪个分支，询问用户。
• 清理痕迹：当整个合并完成后，应该删除这次创建的独立开发空间。

设计完成后

文档化

• 创建进度文档： 将验证后的方案写入 docs/plans/YYYY-MM-DD-<主题>-refactor.md
• 结构化清单： 文档不仅包含设计方案，还必须包含一个任务分解清单 (Task Checklist)。
• 分级任务：
  • 大步骤 (Stages)： 核心重构阶段（如：抽象逻辑层、重构 UI 组件、迁移数据流）。
  • 原子任务 (Sub-tasks)： 具体的、可操作的小步骤（如：提取 useAuth hook、修改 Header.tsx 引用）。
• 状态追踪： 初始状态使用空复选框 - [ ]。
  • 每一个原子任务完成后，必须立即更新文档并打钩 - [x]。
• 实时记录： 在重构过程中发现的意外情况或临时决策，应及时追加到文档的“备注”或“变更记录”小节中。
• 遵循清晰、简洁的写作原则。
• 将设计文档提交（Commit）至 Git 仓库。

核心原则

• 一次一问 —— 绝不通过堆砌问题让用户感到压力。
• 多选优先 —— 选项比问答更易于快速决策。
• 无情 YAGNI —— 坚决从设计中剔除不必要的冗余功能（You Ain't Gonna Need It）。
• 多路对比 —— 在定稿前始终提供 2-3 种备选路径。
• 增量验证 —— 按部分展示设计，步步确认，确保方向不跑偏。
• 灵活响应 —— 只要逻辑不通，随时推倒重来或细化澄清。
• 子代理 —— 所有的任务，在不影响理解的情况下，尽量使用子代理任务进行。