用 AI 稳定交付：五步流程与三条不能省的原则

一条指令为什么不够

给 Codex 或 Claude Code 发一句「给我做个笔记软件」，它确实能做出点东西。但作者一开始就点出了真正的问题：AI 交付的东西，和你想的是同一个吗？

常见的结果是：功能大方向对，细节处处不对；或者代码能跑，但一堆 bug，交互也不是想要的样子。原因不神秘——需求只存在于你的脑子里，而 AI 看不到你的脑子。

这一篇的做法是：把「让 AI 写代码」拆成一条可以复用的流水线，用文档和验证把脑子里的预期逐步外化成 AI 能读懂的约束。演示项目是一个电子书阅读器（取名「马克阅读」），从建文件夹一直做到能导入 TXT。

时间轴

第 0 步：选一个编程 Agent

主流选择是 Codex 和 Claude Code，此外还有 OpenCode、Pi、Cursor 等。作者的建议是：没有特殊要求就先用 Codex，功能比较完整、短板不明显；不方便订阅 ChatGPT 的话，也可以把 DeepSeek、GLM、Kimi 等模型接进来——Codex 并不和 GPT 强绑定。

演示虽然用 Codex，但作者刻意避免使用它独有的功能，因为核心操作逻辑（建项目、写文档、开会话、给插件）在别的 Agent 上同样成立。

第 1 步：环境搭建

这一步只做两件事，但两件事都很关键。

建文件夹并纳入 Git

先建一个专门放项目代码的文件夹，然后在 Codex 里创建项目并指向它，第一句指令是：

帮我把当前的目录初始化为一个 Git 仓库，然后提交

作者对 Git 的解释值得记住：它是一个版本管理工具，每完成一个功能就存一个版本；哪天代码被改乱了，可以一键退回上一个可用状态。AI 改代码时经常顺手把原本正常的功能改坏，没有版本管理，你连「退回哪里」都不知道。条件允许的话再推到 GitHub，本地丢代码也能拉回来。

验证方式：

cd 马克阅读
git status

能看到正常的仓库状态、没有报错，就说明目录已经被 Git 托管。

写 AGENTS.md

第二句指令是创建 AGENTS.md 并写入两条规则，然后提交。这个文件相当于给 Agent 的项目说明书：每轮新会话开始时它会优先读取，从而快速了解项目背景和开发规范。

两条规则是：

1. 每次改动之后都必须创建一个对应的 git commit。 让 Agent 每完成一个功能就顺手存一个快照，后面出问题可以精确回退。
2. 每次改动之后都必须编写或更新相关测试，并在交付前确保所有测试和验收全部通过。 这一条直接决定交付质量：Agent 不再写完就交差，而是自己先跑一遍、发现问题继续修，直到确认没问题才报告完成。

这两条规则会在后面的「产品实现」环节真正发挥作用——它们是把「自测」变成默认行为的最低成本手段。

第 2 步：产品设计

从 MVP 开始讨论，而不是直接下需求

心里知道要做电子书阅读器，但「具体做成什么样」往往没想清楚。作者的做法是先和 AI 讨论：

我想做一个电子书阅读器，打算先从 MVP 版本开始，
你觉得这一版做哪些功能比较合适呢？

MVP（minimal viable product，最小可用产品）的意思是：第一版只做最核心、最必要的功能，先把主流程跑通。好处是用低成本快速验证方向——一上来功能铺太大，发现方向不对时，很多工作就白做了。

逐条收窄：一个具体的谈判过程

AI 给出的方案里有几处需要砍，作者的做法很有代表性：不要看完第一段就提交，把意见逐条追加到输入框，最后一起发。

• AI 建议支持导入 EPUB。EPUB 格式偏复杂，作者要求先只支持最简单的 TXT。
• AI 建议做目录和章节功能。只支持 TXT 的话，纯文本没有目录和章节的概念，这部分直接去掉。
• AI 建议明亮、护眼、深色三种主题。第一版只做明亮主题。
• AI 建议书签。不是必要功能，先不做。

最后补一句总结：

总之我们先做最基本的功能，其余的功能后面再迭代。
你觉得前面这些想法有没有什么问题呢？

AI 反过来补充了几条边界：第一版只支持 UTF-8 编码；只支持纵向滚动，不做分页；载入大文件时要给提示；并列出可以推迟的功能清单。到这里，「做什么、不做什么」有了明确共识。

把共识固化成产品设计文档

口头共识会随会话丢失，所以要落成文档作为后续开发的底稿：

我同意你的建议，接下来帮我整理一份产品设计文档吧。
不用太详细，把整体方向和主要功能梳理出来就可以。

作者特意强调措辞里的「不用太详细」：文档太长自己看着累，只要保证大方向和预期一致，细节后面再迭代。这份文档之后会同时被技术设计和代码实现引用，成为统一依据。

可选：先做一个 demo

有些项目在产品设计之后还会加一步——让 AI 画一个 demo。demo 指只有前端、数据全部模拟的可操作页面：能看到界面、能点、能走流程，但背后没有真实逻辑。

作者用自己做的「个人知识库」demo 举例：左边文档列表，中间推荐问题，点一个问题开始回答，点引用文件右边显示原文——回答和知识库文件都是假的，只有前端是真的。

做 demo 有两个好处：

1. 提前验证产品设计。 很多东西光靠文字想象不出来，真正画出页面、动手操作，才会发现之前没想到的问题。
2. 让后续实现更精确。 demo 能直观告诉 AI「最终大概就是这个样子」，这是文字描述很难做到的；实现时把产品设计文档和 demo 一起交给 AI，它既知道要做哪些功能，也知道界面和交互怎么还原。

什么时候值得做 demo？ 作者只看一个因素：后端实现成本。个人知识库涉及文档处理、搜索检索策略、模型调用，后端成本高，值得先做 demo 把界面和交互定下来；电子书阅读器后端很简单（导入 TXT 即可），再单独做 demo 反而是重复劳动，不如直接做产品，跑起来之后哪里不顺手就在完整产品上改。

如果决定要做，指令可以很简单：

帮我做一个 demo，不用实现真实的后端功能，数据模拟一下就行，
我主要是想看看整体界面和操作流程是否合理。

第 3 步：技术设计

技术方案可以接着当前会话问，也可以新开会话。作者选择新开：一是让讨论更聚焦，二是避免上下文越积越多。他同时说明，现在的顶级模型长上下文能力越来越强，加上上下文压缩机制，正常使用一般不用担心——他自己经常在一个会话里连续跑几个小时。

先讨论方向，而不是直接要一份详细设计：

在这个目录下面有一份产品设计文档，请你读一遍，
然后告诉我用什么技术栈设计这个产品比较合适。
不用给出过于详细的设计，我们就先探讨一下。
我听说 Electron 还可以，你怎么看呢？

AI 的回答应该包含三部分才有用：推荐方案、它的缺点、以及替代选项。 这里它说 Electron 很合适，给出建议的技术栈，也指出缺点，并给出另一个候选 Tauri；最后总结为 Electron + React + TypeScript + Vite + Electron Forge。

方向认可后，再要文档：

行，就按你说的来。现在请你写一个技术方案，放在 docs 文件夹里面。

作者坦言自己也不是特别懂这块，只要保证大体方向没问题就行——这正好体现了「文档的作用是给后续实现一个统一依据」，而不是要求你自己成为架构专家。

第 4 步：产品实现

先给 AI 一双眼睛

正式写代码之前，最重要的一件事是：让 AI 拥有自行验证结果的能力。

如果用 Codex，作者建议至少装两个插件：

• computer use：可以操作电脑；
• Chrome：可以查看 Chrome 页面。

有了这两个，大部分功能都能交给 AI 自己验证。用别的 Agent 的话，去找对应的插件或 skill。

道理很直接：人写代码如果没法验证，也会写出一堆 bug；AI 同样如此。给不给验证环境，决定了它是「写完就交差」还是「写完自己跑一遍」。

让它读文档、实现、自测

新开会话，指令是把两份文档一起交给它：

这个目录下面有两个文档，一个是产品设计，一个是技术方案。
请你读一下这些文档，然后根据里面的要求实现这个产品，提交。

因为 AGENTS.md 里写了「每次改动都要写测试并确保通过」，Codex 完成后不仅实现了功能，还跑了自测。这一步的作用是把明显的 bug 挡在交付之前。

但作者紧接着提醒：测试只能尽量提高可靠性，不能保证最终产品没有 bug。真正用起来怎么样，还是得自己跑一遍。

第 5 步：人工验证

执行 npm start 启动，第一次就报了错：「操作失败，请稍后重试」。这恰好说明了上一条：AI 能自测，也不代表完全可靠。

把报错原样贴给它：

打开之后直接显示了一个报错：操作失败，请稍后重试。

修好之后错误消失，再导入一本 TXT 试读，MVP 完成。

人工验证不可省的理由有两个：交互体验和边界情况很难被自动测试覆盖；而且「这东西到底是不是我想要的」只有亲手用过才知道。

五步流程与它的弹性

其中第 1 步是一次性的；后面每加一个新功能（例如给阅读器加全文搜索），其余四步都会重走一遍：先定搜索入口放在哪、结果怎么展示，再定文本怎么索引、搜索怎么实现，然后开发自测，最后亲自验证。

流程不是死的。做到什么程度，取决于你想对结果保留多少掌控力：

• 简单且不重要的需求：跳过产品设计与技术设计，搭好环境、下指令、实现、验证，结束。
• 复杂且重要的需求：完整走五步，尽量保证质量。

参与得越多，把控越强，投入也越多；参与得越少，速度越快，偏离预期的风险越高。

三条不能省的原则

无论流程怎么裁剪，作者认为有三件事应当坚持：

1. 必须有版本管理。 AI 不可能每次都写对，甚至会改坏原本正常的功能；Git 让每一次功能完成都有快照可回。
2. 必须让 AI 能自测。 不给验证环境，你就会沦为人肉测试员，来来回回帮它找 bug。把相关工具和插件开放给 AI，交付质量会高很多。
3. 必须人工验证。 自动化测试覆盖不到交互体验和边界情况；产品好不好用，最终要自己试。

作者最后说明：这套流程是他现阶段探索出的方法，不是唯一答案；随着模型能力进化，AI 编程的模式还会变化。

理解检验

1. 为什么 AGENTS.md 里的两条规则能提高交付质量？分别对应流程中的哪一步风险？

参考答案：第一条「每次改动都创建 commit」对应的是改坏无法回退的风险——AI 修改时常会破坏原本正常的功能，有版本快照才能精确退回。第二条「改动后必须写/更新测试并确保通过」对应的是写完就交差、bug 直接流到用户手里的风险——它把自测变成 Agent 的默认动作，把明显问题挡在交付前。两条都写进项目说明书，是为了让每轮新会话都自动继承这些约束，而不依赖你每次重复交代。

2. 与 AI 讨论 MVP 时，作者为什么要求「逐条追加意见、最后一起提交」，而不是看一段就改一段？

参考答案：一次提交完整意见，AI 能在同一个上下文里通盘考虑各条删减之间的相互影响（例如去掉 EPUB 之后，目录与章节功能也就没有意义了），避免改一处、后面又要推翻前面的结果；同时也减少来回轮次。作者的示范是：先通读整份回答，把 EPUB、目录章节、多主题、书签等意见全部追加到输入框，最后统一提交，并补一句「其余功能后面再迭代」。

3. 什么情况下值得先做 demo？判据是什么？

参考答案：判据是后端实现成本。后端成本高（如个人知识库涉及文档处理、检索策略、模型调用）时，先做一个只有前端、数据模拟的 demo，把界面和交互定下来，避免后端投入之后才发现产品设计不对；后端成本低（如电子书阅读器只需导入 TXT）时，专门做 demo 属于重复劳动，不如直接实现产品，再在真实产品上迭代。demo 的另一个作用是给后续实现提供直观参照，让 AI 既知道功能也知道界面怎么还原。

4. 为什么在让 AI 写代码之前，必须先给它安装 computer use / Chrome 这类插件？

参考答案：没有验证能力的 Agent 只能写完就交差，bug 会直接流到人工验证环节，人就被迫成为人肉测试员。装上能操作电脑、能查看页面的插件后，AI 可以自己启动程序、点击界面、检查结果，从而在交付前发现并修掉明显问题。作者同时强调，这只能提高可靠性，不能替代人工验证——演示中 AI 自测通过后，npm start 仍然报了错。

5. 五步流程中，哪一步是一次性的？哪些步骤可以按需求裁剪？裁剪的代价是什么？

参考答案：环境搭建（Git + AGENTS.md）是一次性的，每个项目做一次。产品设计和技术设计可以按需求复杂度裁剪：简单且不重要的需求可以跳过这两步，由 AI 自行决定；复杂且重要的需求则完整走完。代价是决策权转移给 AI——流程越短，你对最终结果的控制越弱，成品偏离预期的可能性越高。三条原则（版本管理、AI 自测、人工验证）不建议裁剪。

与前后内容的关系

这一篇给的是一条可复用的交付流水线，强调「用文档固定预期、用验证兜住质量」。同书的另外两篇是它的具体化：一篇演示从零到上线一个能收款的 SaaS（把部署、数据库、支付、安全扫描等环节接进这条流水线），另一篇以真实 SaaS 项目为例，展示需求访谈、界面参考、后端集成和排错在实战中怎么展开。三者对照看，可以把「流程」和「具体工具选择」分开理解。