如何将Cursor解释遗留代码逻辑的提示词改成新手模板

一段没人维护的旧代码堆在面前，想让Cursor绕开幻觉、精准拆解分支，光说一句“帮我解释一下这段代码”可不够。真正有效的做法，是构建一套能锁住上下文、限定输出颗粒度的提示词模板。

那么，究竟该怎么写提示词？

先把文件路径与函数边界锁死

在提示词开头，直接点明文件路径和函数名，比如【/src/utils/date-handler.ts 中的 formatRelativeTime() 函数】。这一点非常关键——Cursor默认会扫描整个工程，不加限定，它很可能把同名变量甚至测试用例都混杂进来解释，导致逻辑混乱。

另外，在粘贴代码前，顺手删掉所有 console.log、TODO 注释和调试用的临时赋值变量行。这些噪音会干扰Cursor对主干逻辑的判断，让它误以为这些调试代码也是业务核心。

强制按执行流分步还原

要让Cursor吐出来的解释条例清晰，最好的办法是用步骤序号来管控。可以要求它必须按以下顺序执行：

第一步：识别入口参数类型与初始校验逻辑

第二步：列出所有 if/else 或 switch 的判断条件，并说明每个分支的作用

第三步：对每个分支内调用的子函数，单独说明其输入来源与返回值用途

第四步：标出所有可能提前 return 的位置及触发条件

第五步：汇总最终返回值的组装路径（哪几个变量拼接？是否经过 transform？）

这五步的顺序不能颠倒。从实际测试来看，Cursor对“第一步”“第二步”这种显式序号的响应稳定度远高于“首先”“接着”，不容易跳跃或遗漏。

杜绝模糊表述，强制具象化

仅仅要求“解释”还不够，需要限制它的输出颗粒度。比如：

不说“处理时间”，而说“将 timestamp 转为毫秒后减去当前时间戳，再除以 60000 得到分钟差”
遇到三元表达式，要求拆成“当 isPast 为 true 时返回 X；为 false 时进入嵌套判断：若 hours < 1 返回 Y，否则返回 Z”
对正则 /(d{4})-(d{2})-(d{2})/，必须写出“捕获组1是年份，组2是月份，组3是日期，后续用 $1 替换为中文‘年’”

这一步千万不能省略。一旦漏掉，Cursor就会用“做日期格式转换”一笔带过，新手根本看不出哪段代码负责切分字符串、哪段负责补零。

设定“解释失败”的退出条件

最后，还需要给Cursor设置一个“防胡乱猜测”的兜底条款。在提示词末尾加上：“如果遇到无法确定用途的变量（如未声明的 globalConfig、无调用链的 _tempCache），必须原样写出变量名并标注【未知来源】，禁止猜测或跳过。”

这个做法能有效阻止它为了显得“懂行”而编造调用关系。很多遗留代码的全局变量确实来自 webpack definePlugin 注入，单看文件根本找不到定义，与其让它瞎猜，不如直接如实标注出来。