request-refactor-plan

request-refactor-plan skill 概览

request-refactor-plan 实际做什么

request-refactor-plan skill 的作用，是把一个模糊的重构想法整理成一份经过审视、边界清晰、可渐进执行的计划，并最终整理成可提交为 GitHub issue 的草案。它不会一上来就直接改代码，而是引导 agent 先完成用户访谈、仓库检查、方案比较、范围界定、测试问题梳理，以及按 commit 拆分的落地计划。

什么场景最适合这个 skill

request-refactor-plan 最适合这样一类开发者和团队：已经知道代码库的某个部分需要重整，但还没有一个足够稳妥的执行方案。尤其适用于你想要：

• 在正式开始实现前先准备好重构方案
• 撰写重构 RFC 或 issue
• 把高风险清理工作拆成一系列微小且可回退的 commit
• 在开工前把范围、约束和测试要求讲清楚

它真正解决的工作是什么

它真正的价值，不是“生成一份重构计划”这么简单，而是通过先提对问题、检查代码库、再产出一个足够小、可以安全执行的方案，来降低重构风险。相比通用 prompt，request-refactor-plan 更适合解决这类风险：范围不清、隐藏依赖多、变更目标过大。

request-refactor-plan 的差异化在哪里

它最大的特点是流程纪律性强。这个 skill 对执行顺序有明确偏好：

1. 先拿到详细的问题描述
2. 到仓库里验证假设
3. 比较可选方案
4. 继续访谈实现细节
5. 明确哪些在范围内、哪些不在
6. 核对测试覆盖和测试计划
7. 把工作拆成极小的 commits
8. 最后整理成 GitHub issue

这种结构，让 request-refactor-plan for Refactoring 比一句“一次性帮我写个计划”更有实际价值。

安装前用户需要知道什么

这个 skill 很轻量。从仓库可见信息来看，只有 SKILL.md，没有额外脚本、模板或辅助文件。这意味着接入门槛低，但输出质量会非常依赖你提供的仓库上下文，以及访谈过程中回答问题的质量。如果你想要一个自带大量自动化和配套资产的 planner，那它不是这类工具；如果你需要的是一套清晰、可复用的规划流程，那它会很合适。

如何使用 request-refactor-plan skill

request-refactor-plan 安装

在支持 skills 的环境中，可以用下面的命令安装 request-refactor-plan skill：

npx skills add mattpocock/skills --skill request-refactor-plan

如果你的环境里已经有这个来源，先读 request-refactor-plan/SKILL.md。因为这个文件本身就是完整的实现入口，你不需要再去额外的支持目录里翻找资料。

先看这个文件

从这里开始：

• SKILL.md

目前没有看到这个 skill 还暴露出配套的 README.md、metadata.json、rules/ 或 resources/ 文件，所以大多数接入和使用问题，都应该能从这一份工作流文档里找到答案。

这个 skill 需要你提供什么输入

想把 request-refactor-plan 用好，不要只给 agent 一句“please refactor X”。它最适合的输入，是你的首条消息里就包含这些信息：

• 受影响的区域或文件
• 当前问题，用开发者视角来描述
• 为什么是现在做
• 已知约束
• 初步的方案想法
• 是否有 deadline 或兼容性要求
• 是希望现在实现，还是先做规划

较弱的输入：

• “Help me refactor the auth module.”

较强的输入：

• “I want a refactor plan for our auth module. src/auth mixes token parsing, session validation, and HTTP concerns. The current pain is duplicated logic across middleware and handlers, which is slowing feature work and creating inconsistent error handling. I think we may need to separate parsing from policy checks, but I’m not sure whether that should be done by extraction or by introducing a service layer. We cannot break existing API responses, and we need a plan that can be shipped in small commits.”

request-refactor-plan 在实际使用中的流程

一个实用的 request-refactor-plan usage 流程通常是这样的：

1. 明确告诉 agent，你要的是重构请求或重构计划。
2. 提供详细的问题描述和粗略的方案想法。
3. 让 agent 检查仓库并验证你的判断。
4. 回答后续关于替代方案、约束和范围的问题。
5. 确认受影响代码的测试预期。
6. 要求最终输出整理成 GitHub issue 草案，并附上细粒度 commit 步骤。

这不是那种“发出去就等结果”的 skill。它天生就是基于访谈推进的。

如何把一个模糊目标变成高质量 prompt

可以按下面的结构来组织 prompt：

• Problem: 今天到底卡在哪里
• Current area: 涉及哪些模块、服务或文件
• Suspected causes: 耦合、重复、不清晰的 ownership、不稳定的测试、命名漂移
• Constraints: 向后兼容、deadline、团队约定
• Non-goals: 明确哪些东西不能改
• Testing state: 当前测试情况、缺口或不确定点
• Desired output: GitHub issue、RFC，或按 commit 拆分的计划

示例：

“Use request-refactor-plan to help me prepare a refactor issue. Problem: src/payments mixes provider adapters with domain rules, making it hard to add providers safely. Current area: src/payments/* and checkout integration tests. Constraints: no API contract changes, no schema changes this sprint. Non-goals: do not redesign billing. Testing state: good unit coverage on adapters, weak integration coverage. Desired output: a GitHub issue with tiny commits and clear scope boundaries.”

为什么仓库检查很重要

这个 skill 会明确要求 agent 去浏览仓库并核实你的说法。这一点很关键，因为很多重构计划失败，恰恰是因为它们只建立在提需求者脑中的模型上。正确使用 request-refactor-plan，意味着要让 agent 实际去确认：

• 痛点到底是局部问题，还是横切多个模块
• 真正发生耦合的是哪些模块
• 测试覆盖是否存在
• 某个“看起来很 obvious”的方案，会不会带来更大范围的连锁改动

如果你不允许它检查仓库，那最后拿到的计划通常会弱很多。

如何处理备选方案和范围

这个 skill 很有价值的一点在于：它不会默认你第一版方案就是对的。你应该预期 agent 会追问是否存在其他方案，也会主动提出替代路径。把这当作功能，而不是阻力。很多最好的重构计划，都是通过缩小任务得到的：

• 与其重做一个子系统，不如只抽出一个职责
• 先补测试，再移动代码
• 先切出稳定边界，再重构行为
• 对于当前痛点不必解决的架构改动，可以延后

最终输出应该长什么样

这个 request-refactor-plan guide 最终通常会指向一份 GitHub issue，至少包含这些部分：

• ## Problem Statement
• ## Solution
• 按 commit 拆分的实现步骤
• 测试预期
• 明确的范围边界

最有价值的产出，往往不是那段总结性文字，而是细粒度的 commit 拆分。因为真正把“很吓人的重构”变成“可以执行的工作”的，就是这部分。

什么时候应该用它，而不是通用 prompt

当你需要更严格的规划过程时，就该用 request-refactor-plan。通用 prompt 也许能写出一份“看起来合理”的计划，但在这些场景里，这个 skill 更强：

• 需要基于真实仓库做验证
• 需要明确谈判范围边界
• 需要在实现前先把替代方案摊开
• 需要讨论测试策略
• 需要的是一连串很小的 commits，而不是一次大改写

常见接入阻碍

最常见的阻碍，是问题定义得太含糊。如果团队没法清楚说明开发痛点、约束和非目标，这个 skill 依然会提出不错的问题，但最后的计划可能还是过于抽象，难以执行。实际经验上，最快见效的方式是：带着一个真实痛点和一个明确代码区域来，而不是一句很泛的“clean up the architecture”。

request-refactor-plan skill 常见问题

request-refactor-plan 只适合大型重构吗？

不是。它很多时候对中等规模的重构更有价值，尤其是那种“看起来不大、但其实容易失控”的整理工作。大型重构当然也能受益，但这个 skill 最出彩的地方，是避免把一个中等清理任务一路做成无边界的重设计。

它对新手友好吗？

友好，前提是新手至少能说明问题，并回答一些关于代码库的问题。这个 skill 提供了很多初级开发者通常缺少的结构化过程。但它不能替代对仓库本身的理解；如果回答太弱，计划质量也会被明显限制。

request-refactor-plan 和直接要求重构，有什么区别？

直接要求重构，会把 agent 推向“立刻开始实现”。request-refactor-plan 则是刻意把节奏放慢。它优先处理的是问题界定、方案比较、范围控制、测试以及渐进式交付，而不是马上改代码。

request-refactor-plan skill 会写代码吗？

它的核心目标是规划，不是实现。你当然可以把最终生成的 issue 或 commit 计划拿来指导后续编码，但这个 skill 本身聚焦的是产出一份安全、具体的重构请求。

什么情况下不该把 request-refactor-plan 用于 Refactoring？

以下情况可以跳过：

• 改动很小，而且方案很明确
• 你已经有一份完整且经过评审的实施计划
• 你当下更需要立即改代码，而不是先做规划
• 这项工作本质上是功能设计或架构提案，而不是重构

这些场景下，更直接的 prompt 往往更快。

它一定需要 GitHub 吗？

这个工作流的结尾是生成 GitHub issue，所以 GitHub 确实是最自然的承载方式。即使你们用的是别的跟踪系统，这套 issue 模板结构依然很适合作为规划产物，然后再复制到其他地方。

有没有隐藏文件或自动化辅助工具需要学习？

根据目前仓库中可见的信息，没有。这个 skill 看起来就是一个单文档工作流。它的好处是容易理解，但也意味着你不应期待它附带额外自动化、schema 或强制规则。

如何改进 request-refactor-plan skill 的使用效果

提供更锋利的问题描述

想让 request-refactor-plan 产出更好结果，最快的办法，是从开发流程痛点出发描述问题，而不是笼统地说“代码质量不好”。比起“the code is messy”，更有帮助的是讲清楚：

• 现在具体什么改动很难做
• 是什么重复或耦合导致了困难
• 什么因素让人缺乏信心
• 当前结构带来了什么成本

这样 agent 才有具体内容可去验证。

明确写出 non-goals

很多重构计划之所以越写越大，是因为缺少 non-goals。你要明确告诉 agent 哪些东西必须保持不变：

• public APIs
• database schema
• user-facing behavior
• performance profile
• release timing

这能帮助 request-refactor-plan 产出更小、更现实的执行序列。

提供文件和模块锚点

即使 agent 会自己检查仓库，你也最好指出几个高概率热点。有效的锚点包括：

• 目录
• service 名称
• entry points
• 失败中的测试
• 重复实现的位置

这能减少猜测，提高仓库验证这一步的质量。

如实说明测试覆盖情况

这个 skill 会专门检查代码库这部分有没有测试。如果覆盖薄弱，尽早说出来。好的输出往往取决于先做哪一种判断：

• 先补 characterization tests
• 扩大 integration coverage
• 在安全网不足时，先推迟高风险迁移

隐瞒测试缺口，最后通常只会得到一份过度自信的计划。

要求按 tiny commits 拆，而不只是按阶段

这个 skill 本身已经倾向于小步推进，但如果你明确要求“按 commit 粒度”输出，结果会更好。像“extract service layer”这种阶段描述，依然太大。更好的 commit 表达应该像这样：

• add characterization tests for current behavior
• extract helper without behavior change
• redirect one call site
• remove dead path after tests pass

真正降低重构风险的，恰恰就是这种粒度。

强制比较备选方案

一个常见失败模式，是过早锁死在第一版方案上。要提升 request-refactor-plan skill 的效果，可以明确要求 agent 至少比较两种做法，并解释为什么其中一种在你的仓库里更安全、更小、更容易回退。

评审后再收紧第一版草案

第一版计划出来后，最好再做一次有针对性的迭代反馈：

• 哪些步骤仍然太大
• 哪些地方范围还不清楚
• 哪些假设还需要验证
• 哪些测试步骤写得不够具体

和一味把第一条 prompt 写得更长相比，做一次简短的第二轮收敛，通常更能提升可执行性。

注意这些常见失败模式

重点要抓的质量问题包括：

• 范围悄悄膨胀成重设计
• commit 步骤仍然过大
• 缺少测试策略
• 假设没有建立在仓库检查基础上
• 方案文字听起来很好，但对不上真实文件或模块

如果出现这些问题，就要求 agent 基于已验证的代码区域和更小的改动单元重写计划。

最推荐的落地方式

当 request-refactor-plan 给出一份足够扎实的 issue 草案后，最好把它当作一份可持续更新的执行文档来用：

• 和团队一起 review
• 删减或拆分过大的 commits
• 给高风险步骤指定 owner
• 关联受影响的测试和模块
• 随着实际情况变化更新 issue

这才是这个 skill 价值最高的用法：不只是“生成一个计划”，而是让重构更容易启动、更安全执行，也更容易评审。