ilaandClaude Opus 4.8
2d0fa766c3
6 要素质量标准、约束片段库(C1-C8)、适配载体差异、QA 验收闭环 与一条完整 before/after 样例 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
186 lines
9.5 KiB
Markdown
186 lines
9.5 KiB
Markdown
# 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 条 + 工具分版 + 双语。
|