让 AI 编程更可靠：把任务写成可验证的步骤

AI 编程助手可以快速产出实现，但速度并不等于可靠性。更稳定的协作方式，是把任务变成一个可以检查结果的小循环。

如果你想把这个小循环写成可直接使用的提示词，可以继续阅读 Agent Loop 使用指南，了解如何组合目标、验证标准和停止条件，让 AI 在明确的边界内迭代任务。 你可能经历过这种场景：跟 AI 说「帮我加个搜索功能」，它噼里啪啦生成了两百行代码，你兴冲冲运行一看——搜索框是有了，但它顺手改了你的路由逻辑，覆盖了原来的样式，还引入了一个你从没听说过的依赖。功能「好像」能用，但你不敢合并。这不是 AI 不行，而是任务描述太粗，AI 只能靠猜来填补空白，而猜中的概率从来不高。

AI 的「猜」，来自你没给的信息

AI 没有你的项目记忆。它看到「搜索功能」四个字时，脑子里同时浮现几十种实现方式：前端过滤还是后端接口？全文检索还是标题匹配？要不要高亮关键词？分页怎么做？你不给约束，它就选自己最顺手的那个——往往不是你要的那个。

所以可靠协作的第一原则，是把「我以为它懂」的东西写下来。你对项目越了解，越要警惕这种「以为」。人和人协作时还会多问一句「你说的搜索是指哪种」，AI 只会直接开工。

先定义结果，再描述做法

把「帮我加一个搜索功能」改写成具体的使用场景：

访客可以通过标题、标签和正文关键词搜索已发布文章。输入为空时显示初始状态，没有结果时显示空状态。草稿和未来文章不得出现在索引中。

对比一下两种描述。第一种只说了「做什么」，第二种说清了「做到什么程度算做完」。这些条件能帮助实现者理解什么叫完成，也能帮助你判断代码是否偏离目标。

如果你已经有技术约束，一并写清楚。例如「项目使用 Astro 静态输出，搜索在浏览器完成，不引入数据库」。约束不是限制 AI 的发挥，而是帮它排除错误选项——排除了九十九种错误答案，剩下的那个大概率是对的。

提供足够但相关的上下文

上下文包括现有目录、组件约定、数据结构和运行方式。优先让助手阅读相关文件，避免在没有了解项目的情况下复制一套全新架构。

一份好用的上下文清单通常长这样：

• 项目结构：入口文件在哪，搜索相关的代码现在在哪
• 相关代码：直接贴出来，或者明确告诉它去读哪几个文件
• 现状：哪些行为已经正常，最近出现了什么错误
• 禁区：明确说「不要动」的地方，比如已经调好的样式、正在用的依赖版本
• 期望：保留哪些交互，改完之后用户操作路径是什么

不要把凭据、真实用户记录或无关的公司资料放进提示词。提供经过处理的小型复现数据通常更方便排查。给上下文的原则是：够它做出正确判断，但不多到让它分心。

让 AI 先说方案，再写代码

这是一个能省下大量返工的小习惯：在动手之前加一句「先用几句话说说你打算怎么做，确认后再写代码」。

方案阶段发现方向错了，改的是一句话；代码写完再发现方向错了，改的是几百行。而且看方案比看代码轻松得多——你不需要逐行审查，只需要判断思路对不对：数据源选得对吗？改动范围合理吗？有没有引入不必要的依赖？

如果方案里有你不认同的部分，直接指出：「索引不要在构建时生成，改成页面加载时从 JSON 读」。等方案对了再让它动手，你会发现一次通过的概率明显变高。

每次只推进一个可核对的目标

一个搜索功能可以分成这些步骤：

1. 从已发布文章生成统一索引。
2. 实现查询与结果排序。
3. 接入输入框、结果列表和状态反馈。
4. 检查鼠标、键盘和移动端操作。

步骤不需要都拆成独立会话，但应该能够被分别理解和验证。一次同时改搜索、配色、路由和部署流程，会让问题来源更难判断——出 bug 时你甚至不知道是哪一步引入的。

小步推进还有一个好处：每一步的产出都是可以运行、可以检查的。AI 在第三步写错了，你回退的只是一步，而不是整个功能。

把验收条件写成行为

一个好的验收条件描述外部结果，而不是重复代码内部的写法。

行为	检查方式
搜索标题能找到文章	输入已有标题的一部分
草稿不出现在结果中	用草稿独有关键词查询
异常时仍可继续操作	模拟索引请求失败后重试
手机不会横向溢出	在窄屏检查最长标题
关闭弹窗恢复焦点	用键盘打开并按 Escape 关闭
输入特殊字符不报错	输入引号、空格、emoji 再搜索
大量结果时依然流畅	用最长的文章列表测试滚动

测试范围与风险相匹配。修改共享数据逻辑需要更完整的验证，修改一处间距则不必搭建庞大的测试工程。验收条件不需要一次写全，可以在开发过程中补充——关键是每个条件都能动手验证，而不是停留在「应该没问题」。

阅读改动，再决定接受

即使自动检查通过，也要看一次差异。重点关注这几类变化：

• 新依赖：有没有引入没必要的包？它多大？还在维护吗？
• 删除的逻辑：删掉的代码是不是真的没用了？有没有别的页面在用？
• 网络请求：新增的请求发到哪里？带了什么数据？
• 配置与权限：有没有改构建配置、环境变量、文件权限？

git diff --stat
git diff
npm run check
npm run build

先看 --stat 了解改动范围，再看具体 diff。遇到错误时，保留完整错误信息和最小复现步骤。描述「在哪个页面做了什么，预期是什么，实际发生什么」，比单纯说「不好用」更能缩短排查路径——这句话对 AI 和对人类协作者同样有效。

留下一份下一次能用的记录

完成任务后，用几句话记录实际修改、验证结果和已知限制。它可以是一条提交说明，也可以是 Pull Request 描述。

记录的价值在于「下一次」。三个月后你要改搜索排序规则，翻出这条记录就知道索引是怎么生成的、当时为什么这样选、有哪些已知限制不用重复踩坑。如果项目里用 AI 协作的频率高，可以维护一份简单的决策日志：日期、改了什么、为什么这样改。

AI 帮你减少输入代码的时间，你仍然需要理解问题边界、确认结果，并决定哪些变化值得进入项目。把任务写成可验证的步骤，本质上是把「碰运气」变成「走流程」——流程越清晰，AI 越可靠，你也越轻松。