diff --git a/第一阶段/AI Debug 提示词包/Prompt 编写规范与母版.md b/第一阶段/AI Debug 提示词包/Prompt 编写规范与母版.md new file mode 100644 index 0000000..b2d53d6 --- /dev/null +++ b/第一阶段/AI Debug 提示词包/Prompt 编写规范与母版.md @@ -0,0 +1,185 @@ +# 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 条 + 工具分版 + 双语。