让 AI 写代码前，先完成研究与计划

AI 生成代码的速度容易让开发流程从一句需求直接跳到一片改动。困难常常不在语法，而在它是否找到了正确的模块、是否理解已有约束，以及生成的代码到底改变了哪些行为。

这篇文章整理一套把研究、计划与实施分开的协作方法。它来自工作流程笔记的梳理，不是工具效率的测评，也不把笔记中的第一人称叙述当作已经验证的个人经历。

研究阶段要留下可检查的证据

要求 AI“理解整个项目”过于宽泛。研究范围应该围绕当前问题：哪些入口触发了行为，数据如何流动，权限在哪一层检查，失败后由谁处理，以及已有测试证明了什么。

以“列表需要支持游标分页”这个虚构任务为例，研究至少要覆盖接口参数、排序规则、数据库查询、客户端翻页状态与调用者。只看列表组件，无法判断排序相同的记录会不会重复，也无法确定其他调用者是否仍依赖页码。

研究结果可以保存在 research.md 中，让推断与证据靠在一起：

问题：现有列表在哪里计算下一页？
已确认：接口返回页码；客户端追加结果；排序由服务端决定。
证据：相关文件、调用关系、已有测试与观察结果。
未确认：并发新增记录时，当前翻页会不会遗漏。

这里的文档名是示例。重点是明确区分已经读到的事实、需要验证的推断和还缺少的信息。“没有看到重试代码”和“系统没有重试”是两个不同结论；消费者、网关或 SDK 都可能承担这项行为。

研究文档不是越长越好。能支持下一步决策的调用链、数据形状和未解问题，比一份逐文件复述更有用。对于很小的改动，也可以直接在任务记录中保留这些信息，不必机械地增加文件。

研究说明当前系统怎样工作，计划说明这次要让它怎样变化。

一份可审阅的计划需要把目标、改动范围和验证方式联系起来。仍以分页为例，它应说明游标由哪些排序字段构成、接口如何变化、哪些客户端需要同步修改、旧参数怎样处理，以及如何检查重复与遗漏。

可以按这样的顺序组织：

关键代码片段可以帮助讨论，但完整实现不必提前塞进计划。代码写得越多，越容易把“已经生成了很多内容”误当成“方案已经确定”。计划也不应该顺手包含整个模块的清理、依赖升级或未来功能，除非它们是当前目标的必要条件。

聊天适合快速反馈，文档批注适合处理会影响后续实现的约束。

例如，计划提出在客户端增加重试，可以在这一段旁边注明：“任务消费者已有重试和幂等处理，先确认失败如何传递，避免叠加新的重试。”这条批注既指出问题，也给出理由和需要补充的证据。

另一条计划可能把访问范围放在单条记录上，而业务实际按集合共享。此时应修改领域模型与数据流，再重新检查接口与页面；只让 AI 改一个字段名，无法修复模型层面的误解。

每轮更新后都要确认约束已经进入正文，而不是仅在结尾增加一句“已处理”。如果一个变化影响了其他章节，目标行为、文件清单和验证方式也应一起更新。反复批注的目的，是减少仍未确定的决定，不是累积提示词。

如果当前任务明确限定为研究或计划，就应该维持这一阶段的边界，等实施被授权后再修改代码。阶段边界必须来自真实的任务约定；它不应成为已经授权实施时反复等待确认的理由。

计划稳定后，可以拆成少量可验证的任务。每项任务连接一个结果，例如“服务端返回下一页游标，并用重复排序值验证稳定翻页”，而不是单纯“修改三个文件”。

实施中的反馈通常可以更短，因为前面已经建立共同上下文。“这段逻辑放在错误的应用入口”或“这里遗漏了调用者”都能指向具体修正。视觉问题则应尽量提供实际页面中的位置、尺寸、复现步骤或截图，避免只说“不好看”。

完成一项任务时，要记录它采用了什么验证。类型检查说明类型约束是否满足；行为测试说明指定场景是否符合预期；浏览器或真实环境验证说明另一层结果。它们有不同的证明范围，不能把一种检查的通过自动扩展到全部场景。

实现遇到新事实时，计划也可以改变。例如，研究遗漏了一个外部调用者，或实际数据不符合原假设。应先更新影响范围，再继续实施；不应为了维持最初清单而把不再正确的方案写完。

有了研究文档和计划，仍然可能出现一种危险的协作方式：把错误贴给 AI，接收补丁，看到检查通过，然后马上进入下一轮。

可以在关键改动后做一个简单的理解检查：不借助生成的说明，自己讲清楚输入如何变成输出、哪一层承担校验、失败怎样结束，以及测试为什么能发现原问题。如果讲不清楚，就继续读相关代码和文档，或用一个小例子验证。

不必把“完全不用 AI”设为唯一练习方式。也可以先自己读报错、写出可能原因，再让 AI 查找证据；让它给出解释后，自己设计一个会推翻解释的反例；或者手动完成一个很小的修改，再比较差异。

这种检查不是为了证明谁写得更快，而是为了让提交者继续有能力判断变更。计划文件记录了理由，测试记录了行为，代码仍然需要人理解。

比起不断加强语气，更有用的是把范围、阶段和输出说具体。例如：

目标：让订单列表支持稳定的游标分页。
当前阶段：研究与计划，暂不实施。
先阅读接口、查询、客户端状态和相关调用者。
记录已确认事实、证据和待验证问题，再提出改动范围与兼容方案。
计划需要说明关键取舍，并列出验证重复、遗漏和权限范围的方法。

这段描述不保证 AI 一定找全问题。它提供的是可以复核的工作路径：先检查事实，再确定改动，最后用实际结果检验方案。是否进入下一阶段，应以关键假设已经得到处理为依据，而不是以文档看起来足够完整为依据。