name: request-refactor-plan description: "通过用户访谈创建由微小提交组成的详细重构计划，并发布为 GitHub issue。用户希望规划重构、编写重构 RFC 或拆为安全增量步骤时使用。"
第 46 课 / request-refactor-plan
历史对照：用小步保持重构可验证
它把重构的原因、边界、替代方案和测试约定整理成一系列小提交计划。
历史文件，不在当前目录
本课使用下方注明的历史提交原文，帮助理解旧文章和旧提示词。请勿据此认定当前版本仍能直接调用该名称。
还不清楚 Skill、Agent、安装和调用？先读 从零开始的6节入门课。
在关系图中查看 request-refactor-plan 与其他技能的关联 →
一 / 读这一课之前
先把必要的概念讲清楚
这份历史技能把重构想法变成由小提交组成的计划。它训练你先界定问题、范围和验证依据，再改善内部结构。
下面是老师补充的入门说明；原作者的要求保留在中英对照正文中。所有例子均为帮助理解而构造的教学情境。
refactoring｜重构
在保持约定外部行为的前提下改善内部结构，例如合并重复逻辑、调整职责归属。用户仍能完成同样操作，但代码更容易理解和修改。重构不等于顺便加新需求；测试帮助证明外部行为未被意外改变。
Git、commit、branch｜版本与分支
Git 记录项目随时间的变化；commit 是一次有标识的修改记录；branch 是一条可继续发展的工作线。你可在功能分支试做收藏能力，验证后再合入主分支。保存了文件不等于已提交，提交了也不等于已推到服务器或已上线。
spec / specification｜规格说明
把要解决的问题、预期行为、约束和验收依据写明确的文档。它比“做个好用的学习网站”具体：例如登录用户能收藏课程，刷新后仍保留，重复收藏不会多出记录。它不必规定每个内部函数怎么写，但应让实现者和验收者对同一结果达成一致。
seam｜测试接入点
作者在测试语境中指测试进入系统、触发行为并观察结果的公共边界。例如调用“收藏课程”接口，再通过“我的收藏”接口检查结果。入口可以是模块公开函数、服务接口或页面，并非一定是浏览器。选择高层稳定入口能覆盖内部多个步骤；入口少不等于测试场景少。
acceptance criteria｜验收条件
明确规定结果满足什么才算完成，应尽量可观察、可检验。例如“收藏后刷新页面仍可见，重复点击只保留一条”。“体验很好”“代码完善”没有明确边界，难以判断。验收条件关注结果，不是把实现步骤换个标题列出来。
二 / 中英全文对照与精讲
读原文，理解每一步为什么这样做
左右内容按小节对应；窄屏先中文、后英文。两种语言均完整展示，对应讲解紧接在小节之后。译文传达原文要求；老师讲解补充概念、原因、例子与适用边界。
中文译文English · 英文原文
name: request-refactor-plan description: Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
用户希望提出重构请求时，按以下步骤推进。认为不必要的步骤可以跳过。
-
请用户充分、详细地描述想要解决的问题，并说明自己已经想到的可能方案。
-
查看项目仓库，核实用户对现状的判断是否与代码一致，同时了解代码库目前的状态。
-
询问用户是否考虑过其他办法，并主动提出可以比较的替代方案。
-
围绕具体如何实现，与用户进行充分而细致的访谈。不要只停留在一句笼统的“准备重构”。
-
把本次实现的范围确定清楚：准备修改哪些内容，以及哪些内容明确不在本轮修改之内。
-
查看代码库中是否已有覆盖相关区域的测试。如果测试覆盖不足，就询问用户准备怎样安排测试。
-
将实现过程拆成由许多小提交组成的计划。记住 Martin Fowler 的建议：让每一步重构都尽可能小，使你始终能够看到程序仍在正常工作。
-
根据这份重构计划创建一张 GitHub issue，正文采用下面的模板。
<refactor-plan-template>
This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
-
Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
-
Explore the repo to verify their assertions and understand the current state of the codebase.
-
Ask whether they have considered other options, and present other options to them.
-
Interview the user about the implementation. Be extremely detailed and thorough.
-
Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
-
Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
-
Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
-
Create a GitHub issue with the refactor plan. Use the following template for the issue description:
<refactor-plan-template>
老师讲解 · 对应上方原文 · 含教学举例
用户的痛感需要用实际代码证据核对
“这个模块太乱”是调查起点，不是已经证明必须重写。先让用户描述困难，再检查哪些修改反复出问题、哪些规则散落、现有替代方案是什么。
例如每次新增课时状态都要改三处判断，可能适合集中规则；如果只是某目录名不喜欢，大重构的收益未必足够。探索用于验证说法，不是默认怀疑用户体验。
比较其他方案也很重要：局部提取、调整公开接口、补测试边界，可能比全量重写成本更低且更容易验证。
小提交让行为是否仍正常更容易看见
一次把目录、接口、数据结构全部改完，失败时难判断原因。小步先提取重复规则，再迁移一个调用者，再继续迁移，更容易定位哪步造成回归。
每步保持可工作，不是要求每个提交都能独立完成整个需求，而是避免长时间处于无法验证的破损状态。已有测试不足时，先明确怎样观察当前行为。
原文借用 Martin Fowler 的建议，是强调反馈频率，不是用提交数量当绩效。拆成几十个无意义改名提交，同样没有帮助。
怎样让“整理代码”变成一步一步可以核对的工作
假设三个页面重复解析出题结果，每次修格式都要改三处。重构目标可以是集中这段行为；范围明确不换模型、不改页面、不新增题型。
可以先记录正常和缺字段输入的行为检查，再引入共享模块，迁移一个页面并验证，然后逐个迁移其他页面，最后删除旧逻辑。每一步可运行，出问题更容易知道来自哪一步。
测试应检查用户相关结果，而不是要求内部函数永远保持原名。重构改的是结构，若测试绑死结构，会让它无法判断外部行为是否仍然正确。
明确不做什么，也是在告诉 AI 到哪里停。附近有其他改善机会可以记下来，不能顺手把一次小重构扩大成全站改写。
问题说明
从开发者角度说明当前困难。
Problem Statement
The problem that the developer is facing, from the developer's perspective.
解决方案
从开发者角度说明准备怎样解决。
Solution
The solution to the problem, from the developer's perspective.
提交安排
写充分详细的自然语言计划，拆成尽可能小的提交。每个提交都应让代码库继续工作。
Commits
A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
已确定的决定
列出已经确定的实现决定。可以包括：
- 准备创建或修改哪些模块。
- 这些模块的哪些对外接口需要改变。
- 开发者已经解释清楚的技术问题。
- 已经做出的架构决定。
- 保存数据的结构需要怎样变化。
- API 的请求、返回以及行为约定。
- 已经确定的具体交互方式。
不要写具体代码路径或片段，因为容易过时。
Decision Document
A list of implementation decisions that were made. This can include:
- The modules that will be built/modified
- The interfaces of those modules that will be modified
- Technical clarifications from the developer
- Architectural decisions
- Schema changes
- API contracts
- Specific interactions
Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
老师讲解 · 对应上方原文 · 含教学举例
计划必须交代为什么这样改，以及哪里不改
决定文档记录模块、接口、技术澄清、架构、schema 和 API 契约等必要取舍。避免易过期路径，是让计划围绕职责和行为，而不依赖瞬时文件布局。
例如“把完成规则集中到进度模块，页面只读取结果”，说明了边界；“改第 42 行”没有表达设计。测试决定则说明从哪里证明原行为仍正确。
Out of Scope 防止重构顺手加入新功能。计划 issue 已创建，表示重构请求已经可讨论，不代表变更已实施、评审或上线。
测试决定
列出已经确定的测试安排，其中包括：
- 什么样的测试才算好测试：只验证外部可观察的行为，不依赖内部实现细节。
- 准备对哪些模块进行测试。
- 已有做法中有哪些可供参考，例如代码库里已经存在的类似测试。
Testing Decisions
A list of testing decisions that were made. Include:
- A description of what makes a good test (only test external behavior, not implementation details)
- Which modules will be tested
- Prior art for the tests (i.e. similar types of tests in the codebase)
本次不做的内容
明确不属于本次重构的工作。
Out of Scope
A description of the things that are out of scope for this refactor.
补充说明（可选）
记录其他相关事项。
</refactor-plan-template>
Further Notes (optional)
Any further notes about the refactor.
</refactor-plan-template>
三 / 你问我答
先作答，再看参考思路
Q1 · 理解
用自己的话说明：它解决什么问题，完成后会留下什么？
请各用一句话回答。若它只做规划或解释，不要把“已开发”“已部署”写成产物。
Q2 · 判断
为什么重构前要验证用户对代码的描述？
我已思考，查看参考思路
症状可能真实但原因判断错误。先读代码能避免为并不存在的结构问题做大规模改动。
Q3 · 追问
原文中哪条要求在你的环境下可能不成立？
说出具体一句及其前提，例如工具不可用、资料缺失、已有项目约定冲突，或它只是作者偏好。把你的答案带回课堂，我们据此继续讨论。
课堂回传格式：第 46 课 / 我的理解 / Q2 回答 / 仍不理解的原句。这里是阅读教材；实时问答在我们的对话中进行。
四 / 应用场景讨论
把方法放进一个具体情境
教学案例：把散落在三个地方的来源校验集中起来，应先确认这些校验是否语义相同，再逐步替换调用。直接删掉旧实现可能改变一个调用方的特殊行为。
边界与容易误读的地方
这是历史规划技能，不会执行重构。没测试时不能用“应该没问题”替代计划中的验证安排。
讨论后再实践：先判断上述情境是否适用，再选择真实任务。现在无需安装、运行命令或修改现有项目。