我用 AI 做完一个产品后，留下了这套交付闭环

AI 编程最容易制造一种错觉：只要把需求发给 Codex 或 Claude Code，产品就会自己长出来。代码确实可以很快出现，可交付结果经常偏离脑中的设想，甚至连启动都过不了。

马克的技术工作坊用一款电子书阅读器演示了完整过程。视频长约 25 分钟，略过工具按钮的细枝末节，集中讲怎样把模糊想法逐步压成可验证的产品。原视频：https://www.youtube.com/watch?v=KJybu1Y2tyY

整个流程一共五步：环境搭建、产品设计、技术设计、产品实现、人工验证。前面的步骤负责减少方向偏差，后面的步骤负责暴露实现偏差。它们连起来，AI 才从代码生成器变成可以参与交付的工程工具。

第一步：先给项目装上安全绳

视频选择 Codex 演示，不过操作逻辑同样适用于 Claude Code、OpenCode、Pi 或 Cursor。Agent 选定以后，讲者先创建项目目录，把目录初始化为 Git 仓库，然后加入一个 AGENTS.md。

Git 是版本管理工具。每完成一个功能，就保存一份可回退的版本快照。AI 改代码的速度很快，也可能在修新问题时破坏原有功能。没有 Git，错误会不断叠加；有了 Git，至少能回到上一个正常节点。视频还建议把代码同步到 GitHub 一类的远端仓库，避免本地文件丢失后连历史也一起消失。

AGENTS.md 可以看作项目的值班手册，专门告诉 Agent 进入仓库后该遵守哪些规矩。视频里只放了两条：

1. 每次改动后创建 Git commit，保留可追踪的版本。
2. 每次改动后编写或更新测试，交付前跑完测试和验收。

这两条很短，却直接约束了交付行为。相关实测也表明，AGENTS.md 的价值取决于规则是否具体、可执行。主文件写成项目百科全书，Agent 反而容易丢掉重点；把高频规则放在入口，细节按需引用，效果更稳。

环境搭建只做了 Git 和 AGENTS.md 两件事，却解决了两个高频风险。代码改坏后可以退，Agent 写完后必须先自行检查。

第二步：先砍范围，再写产品文档

讲者想做一款电子书阅读器，但没有立即让 Codex 开工。他先问 AI：如果从 MVP 开始，第一版应该包含哪些功能？MVP 指最小可用产品，也就是用最低成本把核心流程跑通。

AI 最初建议支持 EPUB、本地导入、目录与章节、三种主题和书签。讲者逐项收缩：

• EPUB 解析偏复杂，首版改为 TXT。
• TXT 没有统一的目录和章节结构，相关功能先删掉。
• 明亮、护眼、深色三种主题只保留明亮主题。
• 书签不影响阅读主流程，也延后处理。

Codex 随后补充了几个边界：第一版只支持 UTF-8 编码，只做纵向滚动，不做分页；载入大文件时给出提示。到这里，「做什么」与「暂时不做什么」已经比较清楚。讲者再让 AI 把共识整理成一份简短的产品设计文档，供后续技术方案和开发共同使用。

这段把规格形成的过程拍得很清楚。第一条提示词很难直接长出好规格。人要读完 AI 的建议，砍掉过度设计，补上隐含边界，再把共识写进文档。产品文档像施工图，后续工作都以同一张图为准。

视频还讨论了 demo。这里的 demo 是可以操作的前端页面，后端数据可以模拟。它有两个用途：提前发现界面和交互问题，并给正式实现提供可见参照。

要不要做 demo，讲者看后端成本。个人知识库涉及文档处理、搜索、检索策略与模型调用，后端成本高，先做 demo 可以避免在错误的交互上投入太多。电子书阅读器首版只导入 TXT，后端很轻，直接做完整 MVP 更省时间。这个判断把原型从固定仪式变成了风险控制工具。

第三步：技术方案只需要先锁定大方向

产品边界确认后，讲者新开一个会话讨论技术方案。新会话可以减少旧上下文干扰，也让讨论更聚焦。他让 Codex 阅读产品设计文档，再判断 Electron 是否合适。

Codex 给出的方案是 Electron、React、TypeScript、Vite 和 Electron Forge，同时说明了 Electron 的缺点，也给出 Tauri 作为备选。讲者没有追求一份覆盖每个类和接口的厚文档，只确认技术栈与架构方向，然后让 AI 把方案写入 docs 目录。

这种颗粒度与项目阶段匹配。MVP 当前要解决的是技术路线会不会走偏。至于模块拆分和接口细节，可以在实现中继续校准。过早写满细节，会把尚未验证的猜测包装成约束。

产品设计管「要做什么」，技术设计管「准备怎么做」。两份文档合在一起，已经构成一份轻量规格。规格驱动开发的价值也在这里：先把预期写清，再让 AI 实现。测试只能判断代码是否符合预期，却不能替人决定预期是否合理。

第四步：给 Agent 一双能检查结果的眼睛

正式开发前，视频强调要让 Agent 自己验证结果。Codex 环境里，讲者安装了 Computer Use 和 Chrome 两个插件。前者可以操作电脑，后者可以查看浏览器页面。换用其他 Agent，也需要提供对应工具或 Skill。

只让 AI 写代码，开发者很快会沦为人工测试员：Agent 写一轮，人找一个 bug，Agent 再修一轮。把运行、页面检查和测试能力交给 Agent，可以提前挡住明显错误，扩大自动审阅的带宽。

讲者随后新开会话，让 Codex 阅读产品设计与技术方案，完成实现。由于 AGENTS.md 规定每次改动都要更新测试并完成验收，Codex 在交付时报告已经跑过各种自测。

这里出现了全片最重要的反例。讲者按提示执行 npm start，应用一打开就显示「操作失败，请稍后重试」。他把现场错误发回 Codex，修复后再次启动，错误消失，TXT 文件也能正常导入。

自测已经通过，人工第一次启动仍然发现故障。这个现场说明了自动测试的边界：测试覆盖已知规则，真实使用还会碰到体验问题、环境差异和未想到的路径。Agent 能看页面、能跑测试，可以提高交付前的可靠性，最终验收单仍要由人签。

第五步：验收要回到真实使用

视频把最后一步交给人。产品是否顺手，交互是否符合预期，边界条件是否能接受，都需要真实使用后判断。发现问题就把现场现象反馈给 Agent，修复后再验一次，直到结果可接受。

这也解释了为什么 AI 输出速度越快，验证越容易成为瓶颈。生成带宽超过人工审阅带宽，多出来的部分就是没有认真检查的代码。主路径通常会跑一遍，异常路径和边界条件更容易留下债务。

扩大验证带宽需要两层门禁。机器负责可重复检查，例如测试、类型检查、构建和页面自动化；人负责产品意图、使用感受和风险判断。两层各自覆盖不同问题，缺一层都会留下盲区。

五步应该按项目风险伸缩

视频没有要求每个需求都照着五步重走一遍。简单且不重要的需求，可以略过详细的产品设计与技术设计，搭好环境后直接实现、自测和人工验证。复杂且重要的需求，则应完整讨论产品边界与技术路线。

可以把裁剪逻辑整理成一个简单对照：

投入越多，结果越可控；交给 Agent 的决策越多，速度会更快，偏离预期的概率也会增加。没有一套固定比例，需求的复杂度、重要性和失败成本决定流程深度。

讲者最终留下三条最低护栏：Git 版本管理、AI 自测和人工验证。产品设计与技术设计可以伸缩，这三项尽量保留。Git 解决可回退性；自测拦住明显问题；人工验证判断结果是否真的能用。

我的补充：把五步改成闭环

视频按教学顺序把过程讲成五步，真实工程里更适合画成一个闭环：产品设计与技术设计形成规格，AGENTS.md 和工具构成 Agent 的工作环境，自动测试与人工验收提供反馈；任何一层发现偏差，都回到前面修正文档、代码或验证方法。

这套结构也能对应 AI 编程常见的三个层次：spec、harness、verification。产品文档和技术方案属于 spec；Git、AGENTS.md、Computer Use 与 Chrome 属于 harness；自动测试和人工试用属于 verification。三个层次里，验证最难省。模型生成越快，错误也会更快越过人工注意力。

如果准备把 AI 编程用于正式交付，可以先做一件小事：把「完成」写成可检查的验收条件，并要求 Agent 提交证据。代码写完只代表生成结束，测试、运行和人工试用都通过，才接近产品完成。