口述背景与精确代码相结合的重构任务说明

让 AI 编程工具做重构时，背景解释和技术标识需要不同形式的准确。你可以用日常语言说明：为什么重复逻辑越来越难维护。文件名、导出函数和边界值，则更适合直接提供精确文字。

一份有用的任务说明会把两者结合起来：告诉工具要改什么、哪些行为必须保持不变，以及你希望拿到哪些内容来复核。解释部分可以口述，也可以把整份说明全部打出来。两种方式都不依赖某个特定应用。

把背景解释与精确文字分开准备

口述时，可以像向同事解释一样，说明重复逻辑从哪里来、它为什么不方便，以及为什么现在只想做一次小改动。对于决定具体工作对象的内容，则用键盘输入或粘贴。

粘贴的内容不必是整份代码仓库。给出最小的相关样例，再提供足够的位置信息，让工具能找到实际代码中的对应位置。粘贴前，移除密钥等机密信息和无关的客户数据。

复制一份空白重构任务说明

修改原因：
[现在什么地方不方便，为什么要在此时修改？]

当前行为：
[目前调用方得到什么，包括单位和边界条件。]

精确标识及位置：
- [路径] :: [标识] :: [作用]
- [路径] :: [标识] :: [作用]

请求的修改：
[一项具有明确最终状态的改动。]

允许修改的文件：
- [文件]

必须保持不变的行为：
- [不变量]

不在本次范围内：
- [附近存在、但此次应保持不动的改进项]

供复核的返回内容：
[差异、解释、拟进行的检查，以及实际执行过的检查。]

本次请求的动作：
[说明方案 / 准备补丁 / 执行限定范围内的修改。]

最后一行要有意识地填写。请求一个方案，不应悄悄变成允许编辑文件。如果工具找不到某个精确标识，应让它指出不一致的地方，而不是用一个名字相近的对象代替。

一个虚构的费用规则提取案例

下面的小型商店和代码专为这个练习虚构。它们不是 CueSpec 代码，也不是某次 AI 实际运行的记录。

假设 src/billing/totals.js 中有两个调用方使用相同的费用规则：

export function invoiceTotalCents(subtotalCents, deliveryCents) {
  const serviceCents = subtotalCents >= 5000 ? 0 : 300;
  return subtotalCents + deliveryCents + serviceCents;
}

export function checkoutTotalCents(subtotalCents, deliveryCents) {
  const serviceCents = subtotalCents >= 5000 ? 0 : 300;
  return subtotalCents + deliveryCents + serviceCents;
}

你口述的背景可能是：“这两处用的是同一条服务费规则。我想把它集中到一个地方维护，但不重新设计计费逻辑，也不改变向客户收取的金额。”这说明了原因，却仍让工具去猜具体边界和预期改动规模。

再补上一张标识对应表：

接着给出一份填写完整的请求：

把共用的服务费计算提取为 serviceFeeCents，放在
src/billing/service-fee.js 中，让 src/billing/totals.js
中的两个现有函数都调用它。

在这个练习中，输入都是以分为单位的非负整数金额。
保留当前规则：subtotalCents >= 5000 时，服务费为零；
小于这个阈值时，服务费为 300 分。配送费仍作为独立金额
加到总额中。不要改变现有函数名、参数顺序或返回值的单位。

允许修改的文件：
- src/billing/totals.js
- src/billing/service-fee.js（新增的内部模块）
- test/billing/totals.test.js（仅做针对性检查，前提是这个测试文件存在）

不要修改公共汇总导出入口（barrel exports）、校验策略、依赖、
货币换算或无关格式。如果测试文件不存在，先报告这一情况，
再选择其他测试位置。

准备一份供复核的补丁。返回差异、你打算检查的用例，
以及每项实际执行过的检查结果。指出哪些检查没有执行。

这个小辅助函数可能需要在其模块中导出，现有文件才能导入它。要求“公共汇总导出入口（barrel exports）保持不变”，比一边要求拆成独立模块、一边笼统地说“不新增任何导出”更准确。

看清请求本身发生了什么变化

下面比较的是两份指令，不是代码差异，也不是执行记录：

- 清理计费代码，让它可以复用。
+ 只把重复的服务费规则提取为 serviceFeeCents。
+ 保留 >= 5000、300 分服务费，以及两个现有调用函数的签名。
+ 只改动列出的文件；保留公共导出和校验策略。
+ 返回可复核的补丁，并区分拟进行的检查与实际执行过的检查。

第一条新增指令明确操作。第二条保护行为。第三条避免“清理”扩展成重新设计。第四条让返回的依据有用，而不把一段好听的解释当成证明。

先检查边界，再看实现是否漂亮

对于这条虚构规则，可以把下面的预期示例转成检查用例：

这些是根据示例推算的算术预期，不是已经通过测试的记录。复核实际补丁时，要检查两个调用方是否都使用了辅助函数、阈值是否被改成了 > 5000，以及差异中是否混入无关改动。对于已报告的检查结果和拟进行的用例，也要分别阅读。

任务说明清楚后，下一条指令就可以很短，因为精确的对象和范围已经留在会话中。如果你用 CueSpec 准备口述部分，可以查看结合语音与精确技术标识的指南，了解可编辑草稿的使用方式。直接把这份任务说明输入现有编程工具，同样可以使用。