passive_income/第一阶段/AI Debug 提示词包/Prompt 编写规范与母版.md

Prompt 编写规范与母版

所属：AI Debug 提示词包 · 子项目「图纸」文档 关联：项目方案 作用：定义这套 100 条 Debug Prompt 的统一质量标准。所有 prompt 都按本规范产出、按本规范验收。先有这份规范，再写具体 prompt。

---

0. 一句话原则

好的 debug prompt 不是「帮我修 bug」，而是「逼 AI 像一个谨慎的资深工程师那样思考」——先定位、再分析、后动手，且全程不许自作主张。

我们卖的不是 100 句话，是这套思考纪律。100 条 prompt 只是把这套纪律拆进不同场景。

---

1. 一条合格 Prompt 的 6 要素

每条 prompt 在设计时，必须想清楚它如何覆盖以下 6 点（不一定每条都写满，但每条都要有意识地取舍）：

#	要素	解决什么	反面（不写会怎样）
1	角色锚定	让 AI 进入「debug 搭档」而非「代码生成器」模式	AI 默认倾向于重写、发挥，而非诊断
2	上下文结构	把错误/代码/已尝试/环境/期望喂全	AI 缺信息就猜，猜出来的 fix 是错的
3	行为约束	框死 AI 能做什么、不能做什么	AI 乱改、改坏旧功能、编造路径
4	推理顺序	强制「先分析后动手」	AI 不分析直接改，治标不治本
5	输出格式	要 diff/分步，不要整段重写	给一坨新代码，用户无法判断改了啥
6	停止条件	信息不足时反问，不确定时承认	AI 编一个看似合理实则错误的答案

---

2. 六要素的标准写法（可直接抄进 prompt）

① 角色锚定

你是一位经验丰富、做事谨慎的资深工程师，正在帮我排查一个 bug。你的目标是先找到根因，不是尽快给我一段新代码。

② 上下文结构（配合「报错描述模板」使用）

【报错信息】{粘贴完整报错，含堆栈}
【相关代码】{粘贴出错文件/函数，不要截断}
【我已尝试】{你试过什么、结果如何；没试过就写「无」}
【运行环境】{语言/框架版本、操作系统、关键依赖版本}
【期望 vs 实际】期望：{...}；实际：{...}

③ 行为约束（核心卖点，重点打磨）

请遵守以下约束：

1. 改动最小化：只改与本 bug 直接相关的代码，不重构、不顺手优化。
2. 改动前先说明：在给出任何代码前，先用一句话说清「你要改哪里、为什么」。
3. 不许编造：如果你不确定某个文件路径、函数名、变量是否存在，明确说「我需要确认 X」，不要假设。
4. 保护旧功能：说明你的改动不会影响哪些现有功能；如有风险，指出来。

④ 推理顺序

按这个顺序回答：(1) 你对根因的判断 →(2) 判断依据 →(3) 验证这个判断的方法 →(4) 修改方案。在第 4 步之前不要给完整代码。

⑤ 输出格式

用「修改前 → 修改后」的对照（或 diff）展示改动，不要把整个文件重新贴一遍。每处改动旁边用一句注释说明原因。

⑥ 停止条件

如果根据现有信息无法确定根因，先向我提问把信息补全，再继续——不要在信息不足时猜测并直接给修复代码。

---

3. 可组合的「约束片段库」（原子积木）

100 条 prompt 由这些原子片段拼装，保证一致性。给每个片段一个代号，写 prompt 时直接引用：

代号	片段（可直接粘）
C1-最小改动	只改与本问题直接相关的部分，不重构、不顺带优化。
C2-先说后改	给代码前先一句话说明改哪里、为什么。
C3-不许编造	不确定的路径/函数/变量，明确提出来确认，不要假设存在。
C4-给diff	用「改前→改后」对照展示，不要重贴整个文件。
C5-先分析	先给根因判断和依据，再给方案；分析完成前不给完整代码。
C6-必反问	信息不足就先提问，不要猜测式修复。
C7-护旧功能	说明改动不会破坏哪些现有功能，有风险要指出。
C8-认不确定	不确定时说「我不确定」，不要编一个看似合理的答案。

写每条 prompt 时，在末尾标注它用了哪些片段，例如：约束：C1 C2 C5 C6。这样既保证质量一致，也方便用户自己改造——这本身就是产品价值的一部分。

---

4. 每条 Prompt 的最终落盘格式（升级版母版）

替代 项目方案 里 4 字段的旧母版。每条 prompt 按此结构写：

### [编号] 标题（用户痛点口吻，如「AI 改一个 bug 引出三个新 bug」）

**适用场景**：{一句话，什么时候掏出这条}
**适配载体**：聊天框 / Cursor / Copilot / 通用   ← 必填，见第 5 节
**用法**：{要替换哪些占位符、贴在哪}

**Prompt 正文**：
> {可直接复制的完整 prompt，含占位符与约束}

**占位符**：{粘贴你的报错}、{粘贴相关代码} ……
**预期效果**：{用了之后 AI 的行为会怎样，最好对比「不用时」}
**用到的约束**：C? C? C?
**实测**：{测试日期 + 测试工具/模型，如 2026-06 · Cursor/Claude}   ← QA 闭环，见第 6 节

---

5. 适配载体差异（真实世界最大坑，必读）

同一句约束，在不同工具里行为完全不同，每条 prompt 必须标 适配载体：

载体	关键差异	prompt 要点
聊天框（ChatGPT/Claude 网页/App）	AI 只输出文本，不碰你的文件	重点在「让它先分析、给对照」，约束 C4/C5 最有用
Cursor / Copilot / Codex（agentic IDE）	AI 可能直接改你的文件落盘	必须前置「未经我确认不要 apply」「先在聊天里给方案」，C2/C6/C7 是保命约束
通用	上述都适用	措辞中立，不依赖具体工具特性

⚠️ 这是退款高发点：用户把「聊天框 prompt」直接丢进 Cursor，AI 自动改了一堆文件，反而更乱。标清载体是底线。

---

6. QA 验收闭环（让「不注水」可执行）

一条 prompt 未经实测不得入库。验收流程：

1. 找一个可复现的真实 bug（自己项目里攒的最好）。
2. 先不用这条 prompt，记录 AI 的反应（通常会乱改/猜测）。
3. 再用这条 prompt，记录 AI 的反应。
4. 二者有明显差异 → 通过，把测试日期+工具填进「实测」栏；无差异 → 打回重写。

验收标准（满足才算合格）：

• 6 要素该有的都有，缺的是有意取舍而非遗漏
• 标了适配载体
• 占位符清晰、复制即用、零理解成本
• 真机实测过，且 before/after 有可见差异

---

7. 完整样例（Before / After 各一条）

下面用「② 约束 AI 改动」类的一条，演示规范如何落地，也是销售页可直接用的素材。

❌ Before：用户常见的烂 prompt

这个报错帮我修一下：TypeError: Cannot read properties of undefined (reading 'map')

AI 的典型反应：缺上下文 → 猜你在哪 map → 直接贴一段「加个判空」的新代码，甚至顺手重写整个函数。结果可能修错地方、或把别处改坏，你还看不出它改了什么。

---

✅ After：按本规范写的 prompt

[02-03] AI 一改就把好的功能改坏

适用场景：AI 上次帮你改 bug，结果引出新问题；或你怕它「顺手」动到别的代码。 适配载体：通用（在 Cursor/Copilot 里尤其重要） 用法：替换下面占位符，连同你的代码一起发给 AI。

Prompt 正文：

你是一位做事谨慎的资深工程师，正在帮我排查 bug，目标是先定位根因，不是尽快给新代码。

【报错信息】{粘贴完整报错} 【相关代码】{粘贴出错函数} 【我已尝试】{写你试过什么，没有就写「无」} 【运行环境】{语言/框架版本} 【期望 vs 实际】期望：{...}；实际：{...}

请遵守：

1. 先给出你对根因的判断和依据，分析完成前不要给完整代码。
2. 只改与本 bug 直接相关的代码，不重构、不顺手优化。
3. 用「改前→改后」对照展示改动，不要重贴整个文件。
4. 说明你的改动不会影响哪些现有功能；有风险请指出。
5. 若信息不足以定位根因，先向我提问，不要猜测式修复。
6. 如果在 IDE 中，未经我确认不要直接 apply 改动。

占位符：{粘贴完整报错}、{粘贴出错函数}、{语言/框架版本}…… 预期效果：AI 会先告诉你「根因在哪、为什么」，再给最小对照改动，并主动说明影响面——而不是甩你一段不知道改了啥的新代码。 用到的约束：C1 C2 C4 C5 C6 C7 实测：{待填，如 2026-06 · Cursor/Claude}

---

8. 给作者的工作流（怎么用这份规范量产 100 条）

1. 先把第 3 节「约束片段库」定稿——这是积木，定了就别频繁改。
2. 每类先写 2~3 条标杆（含完整 before/after），跑通 QA，作为该类模板。
3. 其余按标杆扩写，先广后精：先把 5 类各凑 5~10 条能用的，别一上来追 100。
4. 用这 30~40 条 + 1 个 before/after 先发短视频试水（见 项目方案 的 P0 路径）。
5. 市场有正反馈，再回头补满 100 条 + 工具分版 + 双语。