从能跑到好用：怎么调 prompt、看错误、让 AI 帮你修 bug

前面五篇，我们把一个想法做成了一个能用的小东西。

第四篇做出了最小版博客选题助手：输入方向，输出选题，保存成文件。第五篇给它加了工具、记忆、文件读写和一个命令行菜单。它开始像一个项目了。

然后你大概率会遇到这一篇要讲的事。

第一次运行，一切顺利，你有点兴奋。第二天再跑，它开始推荐一个你上个月刚写过的题目；换一个短一点的输入，程序直接崩了；终端里刷出一屏英文，你只看懂最后一个词 Error；你把报错发给 AI，它回了一大段，改完之后原来能用的功能反而坏了。

这不是你做错了什么。这是每一个项目都会经过的阶段。

「能跑」和「好用」之间，隔着一整段路，那段路的名字叫调试。 这一篇就讲怎么走过去：先分清是哪里坏了，再把问题说清楚，然后让 AI 做最小修改，最后用几组真实样例把项目一点点调稳。

先别急着修，先分清是哪里坏了

新手最常见的反应是：出了问题，立刻把报错丢给 AI，说「帮我修一下」。

这个动作本身没错，但跳过了最重要的一步。AI 不知道你这次是「跑都跑不起来」还是「能跑但结果不好」，它只能猜。而它猜错方向时，常常会顺手改一堆本来没问题的地方。

先花一分钟分类，效率会高很多。项目里的问题基本就这四类：

分类不需要很精确，有个大概方向就够。判断起来可以用一个很简单的三步定位法：

1. 程序能跑起来吗？
   不能 -> 环境问题或代码问题，去看报错。
   能   -> 继续第 2 步。

2. 换一个更简单、更正常的输入，还出问题吗？
   换输入就好了 -> 输入问题，是刚才那个输入踩到了边界。
   还是有问题   -> 继续第 3 步。

3. 同一个输入连跑三次，结果一致吗？一致但不好，还是每次都不一样？
   每次都不一样，或者质量忽高忽低 -> Prompt 问题。
   每次都一样，但就是不对         -> 代码问题，逻辑写错了。

这三步问完，你基本已经知道该找谁了。

生活里的比喻是看病。跟医生说「我不舒服」，医生很难办；你说「从昨天开始，吃完饭上腹痛，空腹就没事」，他马上就有了方向。描述问题不是 AI 的活，是你作为项目主人的活。 好消息是，这份活不需要你会写代码。

环境类问题：先确认地基还在

有一类问题特别打击人，因为它跟你写的东西完全无关：昨天还好好的，今天一运行就报错。

常见的原因其实就那么几个：

• 依赖没装，或者装在了另一个环境里（系统 Python 和虚拟环境是两回事）；
• .env 文件没建、key 填错了，或者 key 里有多余空格；
• API Key 没额度了、过期了，或者换了模型名；
• 网络问题，请求超时；
• 在 Windows 上遇到路径分隔符或编码问题。

这一类问题的特点是：报错通常出现在程序刚启动的时候，而且跟你的输入无关——你什么都不输入它也会报。

可以这样让 AI 帮你体检：

我运行 python src/main.py 时报错，程序还没进入输入环节就退出了。
我怀疑是环境或配置问题。

我的系统：Windows 11
Python 版本：3.11
我执行的命令：python src/main.py
完整报错：
（把完整报错贴在这里）

请不要修改业务逻辑代码。
先帮我判断这是环境问题、依赖问题还是配置问题，
再告诉我应该分别检查什么、执行什么命令。

注意最后那句「先判断，再告诉我检查什么」。环境问题经常是改几个命令就能解决的，让 AI 一上来就改代码，容易把简单问题复杂化。

有一条经验值得记住：环境问题修好后，顺手把它写进 README。 比如「必须先创建虚拟环境」「必须用 Python 3.10 以上」「.env 里的变量名是 OPENAI_API_KEY 不是 API_KEY」。你今天踩的坑，两周后的自己会再踩一遍，除非它被写下来。

代码类问题：怎么把报错完整地贴给 AI

程序崩了，错误信息是你手上的全部线索。而新手最常做的事，是把这条线索砍掉一半。

来看一个反面例子：

我的程序报错了，显示 KeyError，怎么办？

AI 看到这句话，只能开始猜：哪个 key？在哪一行？前面发生了什么？它大概率会回一段很长的、覆盖各种可能性的文字，然后建议你改这儿改那儿。

再看一个正面例子：

这是报错信息：

Traceback (most recent call last):
  File "src/main.py", line 42, in generate_topics
    topics = result["choices"][0]["message"]["content"]
KeyError: 'choices'

我刚刚执行的命令是：python src/main.py
我输入的内容是：AI 工具入门
我期望发生的是：输出 5 个选题并保存到 outputs/
实际发生的是：程序在第 42 行崩溃，没有生成任何文件

相关代码（src/main.py 第 35-45 行）：
（把这几行贴上来）

请先解释可能的原因，再给最小修改方案。

你不需要理解这段报错里的每个词，你只需要把它完整地交给 AI。

几条很具体的规矩：

贴文字，不要只发截图。 截图里的字 AI 经常认不全，行号和缩进也会丢。终端里选中、复制、粘贴，比截图快，也更准。

从第一行贴到最后一行。 尤其是 Python 的 Traceback，最关键的信息往往是最后一行（KeyError: 'choices'），但 AI 判断上下文需要看中间那几行它经过了哪些文件。

说清四件事。 这就是这篇计划里一直强调的那个模板，值得背下来：

这是报错信息：___
我刚刚执行的命令是：___
我期望发生的是：___
实际发生的是：___
请先解释可能原因，再给最小修改方案。

说清你改过什么。 如果你是加完菜单之后才报错的，一定要提一句「昨天还能用，今天加了命令行菜单之后就这样了」。这一句经常能直接把范围缩小到某一次改动上。

让 AI 修 bug 的几条规矩

贴完报错还不够，你还得管住 AI 的手。

coding agent 有个特点：它很想帮忙，而且帮得很大方。你说「这里报错了」，它可能顺手重构了三个文件、换了依赖、加了异常处理，还顺便改了你没让它动的格式。修好一个小问题，代价是你再也看不懂自己的项目了。

所以这几条规矩值得写进你的提问模板里。

第一，先解释，再动手。

请先解释可能的原因，再给修改方案。
不要直接改代码。

原因很简单：如果它的解释和你的判断明显不一致，说明它理解错了，这时候让它动手就是灾难。解释这一关过了，再放它改。

第二，只要最小修改。

请只修改能解决这个问题的最小范围。
不要重构，不要优化无关代码，不要改格式，不要升级依赖。

第三，限制它能碰的文件。

请只修改 src/tools.py 这一个文件。
不要修改 src/main.py、src/memory.py 和任何配置文件。

这一条特别有用。第五篇里我们把它拆成了 main.py / tools.py / memory.py，现在正是享受这个拆分红利的时候：出问题了，你能明确说出「只许动这一个文件」。

第四，改完要汇报。

修改完成后，请告诉我：
1. 你改了哪个文件的哪几行；
2. 为什么要这么改；
3. 我该怎么验证它确实修好了。

第 3 条尤其重要，你可以直接照着它给的步骤验收。

第五，留好退路。

在让 AI 改之前，先保证当前版本是提交过的或者至少备份过的。最省事的方式就是每次跑通一个小功能就 commit 一次。有了这个习惯，你随时可以说「不对，回到上一版」，而不会心疼。

一个完整的提问大概长这样：

程序能运行，但执行「查看历史记录」时报错。

这是报错信息：
（完整报错）

我刚刚执行的命令是：python src/main.py，然后输入 2
我期望发生的是：列出 data/memory.json 里的历史记录
实际发生的是：报错，程序退出

请只修改 src/memory.py，不要动其他文件。
请先解释可能原因，再给最小修改方案。
修改后告诉我改了哪几行、为什么改、我该怎么验证。

还有一个经验：如果同一个问题问了三轮还没解决，就别继续追问了。换个做法——新开一段对话、把整个文件内容贴给它、或者干脆自己读一遍报错最后那一行，去搜索引擎搜那个错误名。继续在原地打转，是新手最容易浪费时间的地方。

Prompt 类问题：程序没坏，但输出不好

这一类最容易被误判成 bug。程序跑得好好的，没报错，文件也保存了，但你看一眼输出就不想要。

比如选题助手给你这样的东西：

1. AI 工具入门：全面解析
2. AI 工具使用指南
3. 浅谈 AI 工具
4. AI 工具实战技巧
5. AI 工具未来展望

这五个标题都没有错，但也都没有用。它们只是同一个意思换了五种说法。

这不是代码问题，代码忠实执行了它该做的事。这是 prompt 问题：你没有把「什么叫好」说清楚。

调 prompt 有几个很实用的手法，按性价比排序：

把验收标准写进去。 「5 个选题」是数量要求，「角度不重复」才是质量要求。别让 AI 自己猜质量。

要求：
- 5 个选题必须来自不同角度，不能只是替换同义词。
- 至少包含一个偏概念解释、一个偏实战步骤、一个偏常见误区。
- 每个标题要具体到能立刻动笔，不要出现「浅谈」「解析」「展望」这类空词。

给它一个好例子。 说一百句要求，不如给一个你满意的输出样例。模型非常擅长模仿格式和语气。

这是一个我满意的选题示例：

标题：第一次做 Agent 项目，应该从哪里开始
适合读者：想用 AI 做项目但还不会完整写代码的新手
切入角度：先做一个低风险、可验收的小工具，而不是一上来做全能助手
大纲：
1. 为什么不要一开始就做复杂 Agent
2. 如何定义输入、输出和验收标准
3. 如何用 Vibe Coding 迭代第一版
值得写的原因：它能降低读者的第一步心理门槛

请让其他选题保持同样的具体程度。

给它一个反例。 和正例一样管用，有时候更管用。

不要输出这种标题：
- AI 工具入门：全面解析
- 浅谈 AI 工具

这类标题太泛，读者看不出这篇文章具体讲什么。

约束长度和格式。 「每个选题控制在 150 字以内」「大纲固定 3 条」「用 Markdown 输出」这类要求看起来琐碎，但能明显提高稳定性。

如果输出格式经常乱，就让它先输出结构。 需要机器解析的内容（比如 JSON），可以明确说「只输出 JSON，不要任何解释文字，不要用 ``` 包裹」。这在加了工具和记忆之后尤其重要，因为格式一乱，后面的程序就解析失败了。

需要稳定的时候，把随机性调低。 大多数模型接口都有一个类似「温度」的参数，值越低，输出越稳定、越保守。如果你发现同样输入每次结果差别很大，可以让 coding agent 帮你把这个值调低一点，比如设成 0.2。这个参数不需要你现在就搞懂，只要知道它存在就够了。

调 prompt 有一条铁律：一次只改一处。

你一口气加了正例、反例、格式约束、角度要求，结果变好了——但你不知道是哪一条起的作用。下次换个方向，问题可能又回来。一次改一处，跑一遍，看效果，再决定要不要改下一处。

反馈的模板是这个：

这个输出不符合预期。

我的输入是：AI 工具入门
当前输出是：（贴一段你不满意的输出）
我的验收标准是：5 个选题角度不重复，每个标题具体到能立刻动笔
具体问题是：5 个标题只是替换同义词，没有不同角度

请只调整 prompt 或最小相关代码，不要重构整个项目。
改完后告诉我改了什么、我应该用哪几个输入来验证效果。

输入类问题：换个输入就崩

还有一类问题很隐蔽：你测的时候一直用「AI 工具入门」这种正常输入，一切正常。朋友来试一下，输入一个空的、一个超长的、或者带英文和符号的，程序就出状况了。

这些叫边界情况，值得专门整理一份：

处理方式很朴素：把这些情况一条一条试出来，然后让 AI 加上对应的检查。

可以这样一次性提要求：

我测试了几种边界输入，发现以下问题：

1. 直接回车（空输入）时，程序崩溃。应该提示"请输入一个写作方向"并重新显示输入框。
2. 输入只有一个词时，会生成 5 个空泛的选题。应该提示"方向太模糊，请再补充一点背景"。
3. data/published-topics.md 不存在时，程序报错退出。应该提示"还没有已发布记录"并继续运行。

请只修改输入校验和文件读取相关的部分，不要改生成逻辑。
改完后请列出我该怎么逐条验证。

这些检查加起来可能也就几十行代码，但它们决定了你的项目是「只有你会用」还是「别人也能用」。

建一组测试样例：从能跑到稳定

到了这一步，你可能会有点烦：每次改完都要手动输一遍，改来改去，也不知道到底是变好了还是只是这次运气好。

解法是建一组固定的测试样例。方法很土，但极其有效。

在项目里放一个 cases/ 目录：

cases/
  inputs.md      # 6-10 条固定输入，覆盖正常情况和边界情况
  failures.md    # 失败案例登记表

inputs.md 大概长这样：

1. AI 工具入门                          （正常输入）
2. 第一次做 Agent 项目该从哪里开始        （偏步骤）
3. 我用 AI 写了一个月代码，踩过的坑        （偏经验）
4. AI                                  （太短，测提示）
5. （留空）                              （空输入，测校验）
6. 上次已经生成过的方向                   （测去重）

每次改完 prompt 或代码，就把这六条从头跑一遍。这件事的价值在于：它让「变好了」变成一个可以观察到的结果，而不是一种感觉。

然后是最容易被跳过、但最值钱的一步：记录失败案例。

failures.md 可以很简单：

## 2026-09-01

输入：AI
期望：提示方向太模糊
实际：生成了 5 个空泛选题
原因：没有做输入长度校验
处理：在 main.py 加了最小长度判断
状态：已修复

## 2026-09-02

输入：AI 工具入门
期望：不和已写过的 3 个标题重复
实际：重复了 2 个
原因：read_published_topics 的返回值没有被注入 prompt
处理：修了 prompt 拼接的位置
状态：已修复，待回归测试

几条使用心得：

只记失败的。 成功的案例你不会回头看，失败的才会。

写清原因。 只写「修好了」，下次遇到类似的你还是不会。写清「为什么错」，你才会开始形成判断力。

定期回看。 攒到十几条的时候翻一遍，你大概率会发现某几类问题反复出现。那个反复出现的东西，就是你下一步真正该解决的系统性问题，而不是又一个零散修复。

判断稳定与否，可以给一个很简单的标准：

同一组样例连跑三次，结果都通过 -> 这一版可以提交了。
三次里有两次通过                 -> 还在概率上，继续调 prompt。
换了输入就有问题                 -> 输入校验还没做全。

把踩过的坑写回项目里

调试做了一半，成果别只留在聊天记录里。聊天记录会过期，项目文件不会。

值得沉淀的有三处：

README 的「已知问题」段落。 写下「目前还不行，以后再说」的东西。比如「长输入（超过 800 字）会变慢」「历史记录超过 50 条后 prompt 会变长」。这不是认输，是给未来的自己留线索。

README 的「排错清单」段落。 把你遇到过的环境问题和解法写进去，按报错关键词排列。下次再遇到，你搜一下自己的 README 就能解决，不用再问 AI。

cases/failures.md。 就是上一节那张表。

可以这样让 AI 帮你维护：

请更新 README，新增两个段落：

1. 已知问题：列出当前版本还没解决的 3 个问题（我会告诉你）。
2. 排错清单：把我们遇到过的报错和解决方式整理成「报错关键词 -> 可能原因 -> 怎么处理」的表格。

不要修改代码，只改 README。

项目会因为这些记录而变得「可交接」。哪天你想把它发给朋友，或者两个月后自己回来看，你都能很快接上。

这一阶段的自检清单

做到下面这些，你的项目就算真正脱离了「一次性的东西」：

• 出问题时会先分类，而不是立刻把报错丢给 AI；
• 知道怎么把完整报错、命令、期望和实际结果一起贴给 AI；
• 提问时会要求 AI 先解释、再做最小修改、并限制修改范围；
• 改完会自己跑一遍验收，而不是只看 AI 说「已修复」；
• 有一组固定测试样例，每次改动后都会跑一遍；
• 边界输入（空、太短、文件缺失）都有友好提示，不会崩；
• prompt 里写清了验收标准，还有正例或反例；
• 失败案例被记在文件里，写清了原因而不只是「修好了」；
• 每次跑通一个小功能就提交一次，随时能退回上一版；
• README 里有已知问题和排错清单。

如果这些大部分都做到了，那你已经不是「在跟着教程做一个项目」了。你在真正地维护一个项目。

结尾

这个系列从「AI、Agent、Prompt 到底是什么」讲到这里，一共六篇。

回头看，路线其实很简单：先听懂概念，再理解 Vibe Coding 的工作方式，然后准备环境，做出一个最小 Agent，把它补成一个像样的项目，最后学会在它不好用的时候自己修。

第六篇之所以放在最后，是因为它最容易被忽略，也最决定成败。前五篇给你的是一个能跑的东西，这一篇给你的是让它一直能跑的能力。工具会变，模型会变，框架会变，但「把问题说清楚、把范围限制好、用样例反复验证」这套动作，换到任何技术栈上都成立。

最后想说一件可能反直觉的事：调试不是失败，它就是 Vibe Coding 最主要的工作流。

你可能以为做项目的时间分配是「想清楚、写下去、完成」。真实情况是，大部分时间花在「跑一下、发现不对、说清问题、做最小修改、再跑一下」这个循环里。你的进度不是靠一次写对来推进的，是靠一圈一圈的迭代推出来的。

所以程序报错的时候，别慌，也别觉得自己不适合做这个。那只是循环转到了下一圈而已。

你现在手上有一个能跑、能记住偏好、能读写文件、有菜单的小助手，也知道它出问题的时候该怎么处理。剩下的事情，就是继续用它、继续改它、继续在每次失败里学到一点东西。

这比任何一篇教程的结尾都更有价值。

本系列目录

这是「AI / Vibe Coding 新手系列」的第 6 篇（收尾篇），全系列共六篇：

1. 先听懂：AI、LLM、Prompt、Agent、RAG、Tool、Memory 到底是什么
2. Vibe Coding 是什么：不会完整写代码，也能把想法变成项目
3. 做第一个 Agent 前，要准备哪些东西
4. 实战：用 Vibe Coding 做一个最小 Agent
5. 让 Agent 更像项目：工具、记忆、文件读写和简单界面
6. 从能跑到好用：怎么调 prompt、看错误、让 AI 帮你修 bug（当前篇）

延伸阅读（比本系列更偏工程化，建议跑通第一个 Agent 后再看）：从 Demo 到可交付：如何做一个 Agent 项目