跳到主要内容

调试提示词模板

使用结构化提示词更快修复bug

这些模板帮助你有效地向AI助手描述bug,从而获得更快、更准确的解决方案。

基础调试模板​

**问题**: [简要描述问题]

**错误信息**:
```
[完整的错误信息和堆栈跟踪]
```

**相关代码**:
```[语言]
[导致问题的代码]
```

**预期行为**: [期望的行为]

**实际发生的情况**: [实际的行为]

**复现步骤**:
1. [步骤1]
2. [步骤2]
3. [错误发生]

**环境**:
- 语言/框架: [例如: React 19, Python 3.12]
- 操作系统: [例如: macOS, Windows, Linux]
- 相关包: [例如: Next.js 15, FastAPI 0.104]

**我已尝试的方法**:
- [尝试1]
- [尝试2]

帮我识别根本原因并提供解决方案。

选代码：定位那行“万金油”通用错误​

面对 Failed to parse OpenAPI spec. Provide a valid OpenAPI or Swagger JSON document. Convert YAML to JSON before importing. 这条通用报错时，你的第一反应不该是“改提示词”，而是问自己：我交给 AI 的原始输入是什么？我选进了哪些代码片段？这两者是否足以锁定真实原因？

当你的诊断卡在同一条错误消息上打转时，关键不是堆砌更多错误日志，而是回到「提示词」与「调试」循环的起点：用真实、可复现的输入去碰触源码。针对本例——{"info":{"title":"Fixture","version":"1.0.0"},"paths":{}}——我们聚焦于三个最小片段：解析入口、校验逻辑、错误展示，以及触发故障的具体输入。

首先，打开 parseOpenAPISpec 的实现。注意第 84-92 行的两层 catch：第一层捕获 JSON.parse 或下游校验失败；无论何种错误，统一进入一个占位式的 YAML 解析钩子（实际未实现），随即在第二层被兜底为同一条通用消息。这就是你看到的“万金油”——它不告诉你何时失败，只告诉你失败了。

接着看 validateOpenAPISpec（第 107-120 行）。它检查 openapi/swagger、info.title、paths 等字段。对本例输入：

  • JSON 解析成功；
  • info.title 与 info.version 存在且非空；
  • paths 是空对象（truthy）且 typeof为 object；
  • 但顶层缺少 openapi 或 swagger，校验抛出异常。

再看 handleParseSpec 如何喂养解析器。第 65-94 行显示它接收字符串或 File.text() 内容，直接传入 parseOpenAPISpec——没有预清理、没有 schema 提示，完全依赖输入原样。

因此，诊断链条清晰：

  1. 相关代码：openapi.ts#L78-L121（解析与校验）、App.tsx#L65-L94（输入接收）；
  2. 原始输入：{"info":{"title":"Fixture","version":"1.0.0"},"paths":{}}（最小可复现样例）；
  3. 失败条件：顶层缺失 openapi/swagger，触发校验异常 → 落入第一层 catch → 被统一包装为通用错误。

注意：通用错误消息无法区分 YAML 输入、损坏 JSON 或字段缺失——源码的“万金油”处理往往掩盖了根源。真正的突破口是：将你能复现的实际代码片段与失败输入放进提示词，明确指出它们对应哪条校验规则；当前问题只需定位条件，无需调用代码生成器、添加样式或改动整个仓库。

快速调试提示词​

语法错误​

我遇到了这个语法错误:

[错误信息]

在这段代码中:
[代码]

请识别语法问题并显示修正后的版本。

运行时错误​

我的代码可以编译但在运行时崩溃,错误信息如下:

[错误信息]

代码如下:
[代码]

上下文: [代码应该做什么]

帮我理解为什么会失败以及如何修复。

逻辑错误​

我的代码运行没有错误,但输出结果不正确。

预期输出: [预期结果]
实际输出: [实际结果]

代码:
[代码]

测试用例:
[输入] -> 应该产生 [预期结果] 但实际产生 [实际结果]

帮我找出逻辑错误。

性能问题​

这段代码太慢了:

[代码]

上下文:
- 输入规模: [例如: 10,000个项目]
- 当前性能: [例如: 5秒]
- 目标性能: [例如: < 1秒]

分析代码并建议优化方案。

🎓 高级调试模板​

内存泄漏调查​

我怀疑这段代码存在内存泄漏:

[代码]

症状:
- 内存使用从 [X MB] 开始
- 执行 [Y] 次操作后: [Z MB]
- 内存从不减少

环境: [Node.js 版本 / 浏览器]

帮我识别潜在的内存泄漏并修复。

竞态条件调试​

我遇到了间歇性失败,疑似竞态条件:

[包含异步操作的代码]

症状:
- 随机失败,不是每次都发生
- 高负载时更容易失败
- 错误: [错误信息]

帮我识别并修复竞态条件。

网络请求调试​

这个API调用失败了:

端点: [URL]
方法: [GET/POST/等]
请求体: [JSON/表单数据]

错误: [错误信息或状态码]

代码:
[代码]

预期: [预期响应]
实际: [实际响应或错误]

帮我诊断API问题。

调试策略提示词​

根本原因分析​

帮我追踪这个问题的根本原因:

错误: [错误信息]
代码: [代码]

引导我完成:
1. 理解错误信息
2. 识别错误来源
3. 找到根本原因
4. 提供修复建议

橡皮鸭调试​

让我一步步向你解释我的代码:

[代码]

我认为发生的情况是:
1. [你对步骤1的理解]
2. [你对步骤2的理解]
3. [你认为哪里出错了]

我的理解正确吗?我的错误在哪里?

二分调试​

帮我缩小这个bug发生的范围:

完整代码: [代码]

bug在这个文件的某处。让我们进行二分查找:
1. 发生在前半部分还是后半部分?
2. [继续缩小范围]

错误: [错误信息]

🛠️ 框架特定模板​

React调试​

React组件渲染不正确:

组件: [组件代码]

问题:
- 预期: [预期渲染结果]
- 实际: [实际渲染结果]

React DevTools显示: [状态/属性信息]

控制台错误: [任何错误]

帮我调试这个React问题。

Python异常处理​

遇到了这个Python异常:

```python
[完整的错误回溯]

导致异常的代码:

[代码]

帮我:

  1. 理解这个异常
  2. 修复当前问题
  3. 添加适当的错误处理

### 数据库查询问题

这个SQL/数据库查询没有按预期工作:

查询:

[查询语句]

预期结果: [描述预期结果] 实际结果: [描述实际结果]

表结构: [相关表结构]

帮我修复这个查询。


---

## 何时使用各模板

| 情况 | 模板 | 最适用于 |
|-----------|----------|----------|
| 有明确错误信息 | 基础模板 | 大多数bug |
| 代码运行但输出错误 | 逻辑错误 | 算法bug |
| 间歇性失败 | 竞态条件 | 异步问题 |
| 性能慢 | 性能问题 | 优化 |
| 没有明确错误 | 橡皮鸭 | 理解问题 |
| 大型代码库 | 二分查找 | 缩小范围 |

---

## ✅ 调试前检查清单

使用任何模板前,先收集:
- [ ] 完整的错误信息和堆栈跟踪
- [ ] 能复现问题的最小代码
- [ ] 预期行为 vs 实际行为
- [ ] 环境详情(版本、操作系统)
- [ ] 你已经尝试过的方法

---

## 专业提示

1. **最小可复现示例**: 将代码精简到能展示bug的最小示例
2. **一次一个bug**: 不要在一个提示词中混合多个问题
3. **包含错误信息**: 总是粘贴完整的错误信息,而非仅描述
4. **版本信息**: 具体版本很重要(例如"React 19"而非"React")
5. **展示你的尝试**: 表明你已经做过努力;AI会提供更好的帮助

---

## 🔄 迭代调试

如果第一个解决方案不起作用:

我尝试了你的建议:

[你尝试的内容]

新的错误/问题: [新错误]

原始问题是: [原始问题]

接下来我应该尝试什么?


---

## 相关资源

- [重构模板](/docs/tools/prompt-engineering/templates/refactoring)
- [测试模板](/docs/tools/prompt-engineering/templates/testing)

---

## 🤝 贡献

有很好用的调试提示词?[分享给我们 →](https://github.com/IsaacZhaoo/ai-coding-club/discussions)

---

## FAQ

### 调试提示词应该包含哪些信息？

包含错误信息、相关代码、预期行为、实际行为以及环境信息。

### 如何避免提示词过长？

只提供最小可复现案例，并聚焦相关文件或函数。

### 怎么验证 AI 给出的修复？

复现问题、应用修复，并运行测试或最小脚本确认。