--- name: refactor description: "Before refactoring, this process must be used. Through collaborative dialogue, we will explore user intent, requirements, and design solutions in depth." --- # 对项目或者文件进行重构 ## 概述 在进行详细的思考后，将一个指定的功能或者组件文件，进行重构。 从开始了解当前项目的上下文开始，然后一次询问一个问题来确认重构的方向和思路。 当你了解了你想要重构的步骤和范围后，将整个设计以一个小章节呈现，然后确认所有章节中的内容是否正确。 ## 过程 ### 了解重构的范围和步骤 - **前置检查**：首先检查当前项目的状态（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 种备选路径。 - **增量验证** —— 按部分展示设计，步步确认，确保方向不跑偏。 - **灵活响应** —— 只要逻辑不通，随时推倒重来或细化澄清。 - **子代理** —— 所有的任务，在不影响理解的情况下，尽量使用子代理任务进行。