“AI 软件开发实战教程”系列第 1 篇：介绍这套教程为什么存在、会怎样推进，以及如何判断 AI 完成的工作是否真的可以进入下一步。
AI 已经很会写代码了。
你可以告诉它想做一个什么产品，它很快就能生成页面、接口、数据库，甚至顺手补上一份看起来很完整的产品规划。
这确实降低了开发门槛，却也带来了一个新的问题：
当生成速度越来越快，我们怎样知道自己正在更快地接近正确结果，而不是更快地制造返工？
一个应用能够运行，不代表它解决了真实问题；测试显示通过，不代表用户真的能在手机上完成任务；AI 说“已经完成”，也不代表权限、隐私、失败处理和发布过程都有证据。
我准备通过一个真实项目，完整记录从想法到上线的过程。
这个系列不会展示“一句话生成完整应用”，而是尝试建立一条普通开发者也能重复使用的路线：
真实想法
→ 产品讨论
→ 用户验证
→ 产品规划
→ 工程架构与页面设计
→ 开发计划和任务看板
→ 测试驱动实现
→ 自动检查和真实浏览器验收
→ 审查、发布和上线检查
→ 复盘与项目知识沉淀
图文教程是这条路线的主要记录形式。视频可以在项目交付以后再生成，也可以完全不做。内容形式不能代替软件本身的完成证据。
贯穿整个系列的真实项目
这个项目叫“邻行”，来自小区顺风车微信群里的真实问题。
群里有车的人发布“车找人”，准备坐车的人发布“人找车”。消息通常包含时间和路线，例如：
【车找人】
【时间】明早 8:05
【路线】万科 → 环普 / 中软 / 阿里 / 华为
微信群已经聚集了用户，也承担了最终沟通。但供需双方经常不会同时出现，较早的信息很快被新消息刷走。用户只能重复发送、向上翻找，或者不断询问“刚才那辆车还有吗”。
最初的想法很简单：
做一个更容易发布和查找同路信息的工具。
这句话足够让 AI 开始写代码，却不足以让我们判断应该写什么。
它可能被理解成信息板，也可能被扩张成包含支付、派单、地图、聊天、评价和订单的完整拼车平台。两种理解都能生成很多代码，但它们解决的不是同一个问题。
因此，本系列的第一条规则是：
想法可以模糊，开始编码前的产品边界不能模糊。
为什么不能直接让 AI 生成完整产品
直接生成完整产品通常会遇到四类问题。
第一类：把推测当成需求
开发者觉得用户会喜欢某个功能，AI 就把它写进规划；规划写得越正式，这个未经验证的想法越容易被当成事实。
例如，“用户需要智能推荐”“用户愿意注册”“用户愿意填写联系方式”，都不能只靠开发者和 AI 互相认同。
第二类：过早决定未来版本
项目还没有真实用户反馈，就开始规划第一个版本、第二个版本甚至正式版本。这样的路线图看起来清楚，实际往往只是把当前想象分配到不同时间。
当后来发现核心需求判断错了，所有版本都会一起变化。
第三类：页面、数据和权限各做各的
AI 可能先生成所有数据库模型，再生成所有接口，最后补页面。结果是每一层都“完成了一部分”，用户却走不通一条完整流程。
更严重的是，页面隐藏了某个字段，不代表接口和页面源代码没有泄露它。
第四类：用一句“测试通过”结束交付
自动测试只能证明被覆盖的规则没有失败。它不能自动证明手机页面好用、复制功能在微信内置浏览器中有效、部署后数据不会丢失，也不能证明生产环境没有使用错误配置。
所以，本系列不把“生成了多少代码”当作进度，而把“形成了多少经过验证的闭环”当作进度。
整套教程怎样推进
这套教程不是固定不变的剧本。每一篇文章对应一个真实节点，只有前一个节点留下足够证据，后一个节点才会开始。
第一步：保存原始问题
先保存真实消息、用户行为和当前解决方式，不要急着把它们改写成正式需求。
需要区分：
- 真实观察到了什么；
- 用户本人说了什么；
- 开发者怎样解释；
- AI 又增加了哪些推测。
原始材料是后续判断的起点。如果没有它，产品文档很容易变成自洽但无法核实的故事。
第二步：进行产品讨论
产品讨论不从页面数量和技术选型开始，而是追问：
- 谁正在频繁遇到这个问题；
- 他们现在怎样解决；
- 现有方式失败以后会损失什么；
- 哪一类用户最迫切；
- 最小的解决切入口是什么；
- 哪些能力应该永久排除。
本项目使用了 gstack 中的 office-hours 产品讨论技能。它的价值不是代替开发者拍板，而是不断暴露证据不足和前后矛盾。
产品讨论的产物仍然不是可以直接编码的命令，它更像一份经过追问的设计和待验证清单。
第三步：给讨论做一次节点收尾
AI 工具通常擅长开始一个任务，却不一定会主动处理任务之间的交接。
例如，产品讨论已经完成，但它所属的产品验证阶段可能仍然缺少用户访谈。若只在文档上写“完成”，下一个 AI 会话就可能直接进入架构和开发。
因此，每个重要节点结束后，都要单独回答：
- 本节点原本要达到什么目标；
- 退出条件是否全部满足；
- 产生了哪些长期有效的文件；
- 哪些决定已经确认；
- 哪些仍然只是假设；
- 旧文档是否与新结论冲突；
- 当前可以继续什么；
- 哪些事情必须暂停。
门禁结论只有三种：
- 可以继续；
- 有条件继续；
- 不能继续。
“有条件继续”表示可以准备不依赖缺口的工作，但不能把尚未验证的部分写成确定承诺。
第四步：让真实用户验证关键假设
产品讨论指出的高风险假设，需要通过访谈、观察或小规模试验验证。
访谈不是向用户介绍方案，也不是问“你觉得这个产品好不好”。更有价值的问题是：
- 你现在怎样完成这件事；
- 最近一次失败是什么时候；
- 你为什么选择现在的替代方式；
- 哪一步增加以后，你会直接放弃；
- 如果这个工具消失，你会回到什么做法。
访谈记录要区分用户原话、观察和解释。否则 AI 仍然可能把开发者的理解加工成用户结论。
但真实项目不一定随时具备访谈条件。如果当前确实无法接触目标用户，不能为了让流程看起来完整而编造访谈。更诚实的做法是把“没有完成用户验证”写入检查点，继续推进不依赖该证据的工作，并在产品规划中把相关结论标成假设。
这是一种证据受限的继续，不表示访谈没有价值。读者在开发自己的产品时，如果能够接触目标用户，仍应优先完成真实访谈或行为观察。
第五步：形成正式产品规划
理想情况下，正式产品规划应同时吸收产品讨论和关键用户证据。如果访谈当前无法执行，也可以基于已有行为证据形成草案，但必须明确哪些结论没有获得目标用户确认，并避免使用“用户已经接受”“已经验证”等表述。
产品规划需要回答：
- 产品服务谁；
- 核心问题是什么；
- 用户要完成哪些任务；
- 第一个试用版本包含什么；
- 哪些能力明确不做；
- 每项能力怎样验收；
- 哪些结论还依赖技术验证；
- 什么结果说明值得继续。
版本规划的主要作用不是预测遥远未来，而是给当前版本一个停止位置。
当真实反馈改变了核心判断，应该修改版本规划，而不是为了维护旧文档继续实现错误范围。
第六步：验证关键外部条件
一些产品能力依赖第三方服务、特定浏览器或真实设备，不能只阅读说明后就认为可行。
例如，邻行计划借助第三方服务向微信发送提醒，还需要验证：
- 两个不同用户是否都能及时收到；
- 失效凭据和频率限制怎样返回；
- 网络超时会不会导致重复提醒；
- 服务停止时产品如何降级；
- 用户凭据会不会进入日志；
- 微信内置浏览器是否能保持登录和复制微信号。
这种小范围、可复现的技术试验应在锁定工程方案前完成。失败并不可怕，危险的是没有试验就把候选方案写成已确认依赖。
第七步：确定工程架构和页面体验
产品范围稳定以后，再决定怎样实现。
工程架构至少需要说明：
- 系统由哪些模块组成；
- 数据从页面怎样进入业务规则和数据库；
- 身份、社区和联系方式权限在哪里校验；
- 状态怎样变化；
- 重复提交、并发修改和任务重试怎样处理；
- 第三方服务失败时，哪些业务事实必须保留；
- 自动测试怎样分层；
- 部署、迁移和备份怎样安排。
页面设计也不能只追求“看起来像一个现代应用”。需要围绕真实任务验证：
- 用户能否在手机上快速完成发布；
- 信息层级是否一眼可懂；
- 表单出错后能否继续；
- 空状态是否告诉用户下一步；
- 状态变化是否足够明显；
- 复制、返回微信和重新打开链接是否顺畅；
- 颜色、文字和点击区域是否便于不同用户使用。
页面体验设计工具可以提供配色、字体、间距和交互建议，但产品事实必须决定设计方向。
第八步：生成开发计划和任务看板
产品、架构和关键页面流程明确以后，才适合生成开发任务。
开发计划不能只有“完成登录”“完成搜索”这样的标题。每个任务至少需要：
- 用户为什么需要它；
- 本次交付什么可观察结果；
- 明确不包含什么；
- 依赖哪些前置任务；
- 正常流程怎样验收；
- 权限、错误和边界怎样验收；
- 运行哪些自动检查；
- 最后执行哪条真实浏览器路径。
本系列计划使用 dev-harness 的计划能力，把稳定的产品和架构材料转换成看板。看板是执行工具，不是替代产品讨论的工具。
第九步：按纵向功能小步实现
开发阶段采用测试驱动方式，但重点不是机械地追求测试数量。
每个纵向任务按照下面的顺序完成：
定义用户可观察结果
→ 先建立会失败的验收或规则测试
→ 实现最小可行修改
→ 运行目标测试
→ 运行相关自动检查
→ 在真实浏览器中完成用户路径
→ 审查代码差异和权限边界
→ 保存证据并更新任务状态
一个纵向任务应尽量同时包含页面、服务端规则、数据保存和验证，避免先生成所有模型，再生成所有页面，最后才发现流程无法连起来。
第十步：自动检查之后，还要真实操作
自动检查适合验证确定规则，例如：
- 时间范围不能反向；
- 用户不能修改他人的信息；
- 重复点击不能产生两条记录；
- 同一提醒不能重复发送；
- 最后一个座位不能被两个人同时占用。
真实浏览器验收则检查另一类问题：
- 页面在手机尺寸上是否可用；
- 登录、返回和刷新是否符合预期；
- 表单键盘是否遮挡按钮；
- 复制失败时是否有降级方式；
- 空状态、错误状态和加载状态是否完整；
- 浏览器控制台是否出现异常；
- 分享链接是否泄露不该公开的信息。
两者不能互相替代。
第十一步：审查、发布和上线后检查
准备发布时，需要重新检查：
- 产品边界是否被无意扩张；
- 权限是否只在页面上隐藏；
- 日志是否泄露秘密数据；
- 数据结构升级是否可重复执行；
- 生产配置是否与本地测试隔离；
- 备份是否真的可以恢复；
- 回滚条件是否明确；
- 部署后的核心用户路径是否仍然成立。
上线以后还要观察页面错误、响应时间、后台任务和第三方服务失败。发布完成不是停止验证，而是验证环境从本地变成了真实生产环境。
第十二步：把错误和经验留给下一个会话
AI 会话会结束，新的会话不应该依赖旧聊天记录才能继续开发。
长期有效的知识需要进入仓库：
- 产品边界进入产品文档；
- 数据和权限边界进入架构文档；
- 构建、启动和检查命令进入统一说明；
- 任务状态进入看板；
- AI 曾经犯过的行为错误进入经验记录；
- 版本变化进入变更记录；
- 每个重要节点的结论进入检查点。
后续落地：本文写作后，项目把分支策略、提交格式、版本选择、发布门禁和 tag 要求
固化到项目的 Git 与发布工作流，并用变更日志区分待发布变更与正式版本。
历史文章继续保存当时过程，
当前协作和发布操作以这两份文件为准。
一个真正可继承的项目，应该允许新的 AI 会话只读取仓库，就能说明当前阶段、下一步和不能做什么。
AI 负责什么，开发者负责什么
这套流程不是让开发者逐行指挥 AI，也不是把所有决定交给工具。
AI 适合：
- 整理大量材料；
- 发现文档冲突；
- 提出边界情况；
- 生成候选方案；
- 编写测试和实现；
- 执行重复检查；
- 保存过程证据；
- 帮助新会话恢复上下文。
开发者仍然需要负责：
- 提供真实问题和用户证据；
- 决定产品边界；
- 判断哪些风险值得接受；
- 确认外部服务和隐私规则；
- 验证真实用户是否愿意使用；
- 批准发布和影响真实用户的操作。
AI 可以加快判断过程，但不能凭空制造用户证据，也不能替产品承担责任。
仓库为什么必须成为事实源
只保存在聊天里的结论有三个问题：难以搜索、难以审查、难以让新会话继承。
因此，本系列坚持把长期有效的信息放入仓库，并且只保留当前有效入口。
已经过时但仍有追溯价值的材料，可以先提交到版本历史，再从工作区删除。这样既不会让后续 AI 误读，又不会丢失项目怎样一步步调整的证据。
项目首页应该直接告诉后来者：
- 当前处于哪个阶段；
- 最近完成了哪个节点；
- 当前必须读取哪些文件；
- 下一步是什么；
- 哪些门禁尚未通过；
- 哪些旧材料只能从历史中查看。
图文和视频只是最后的表达方式
整个开发过程会产生大量真实材料：
- 产品讨论记录；
- 用户访谈；
- 产品与架构文档；
- 页面草图；
- 任务看板；
- 代码差异；
- 失败测试和修复过程；
- 浏览器截图；
- 发布记录；
- 上线检查与复盘。
这些材料首先整理成图文教程。图文足够清楚时，可以直接发布，不必为了“完整”强行制作视频。
如果以后需要视频，可以按章节把已完成的文档和证据导入 Google NotebookLM 等工具，辅助生成讲解结构、旁白和解释画面。关键操作、测试失败、浏览器验收和发布结果仍应使用真实记录，不能把计划中的功能制作成仿佛已经完成的演示。
视频是可选产物，不是项目完成门禁。
当前真实进度
写下这篇文章时，“邻行”还没有开始业务代码开发。
当前已经完成：
- 保存真实群聊场景和需求证据；
- 完成第一轮产品讨论；
- 确认产品不替代微信，也不进入支付、派单、导航和站内聊天；
- 形成经过确认的产品发现设计；
- 建立节点收尾模板和检查点；
- 删除可能误导后续开发的旧规划。
当前尚未完成：
- 高频车主和乘客访谈；当前没有执行条件，已作为证据限制记录，不会虚构；
- 正式产品规划；
- 第三方提醒服务验证；
- 微信内置浏览器真机验证；
- 工程架构和页面设计；
- 开发看板；
- 应用代码、测试和部署。
把这些缺口公开写出来，是为了让教程记录真实过程，而不是为了显得流程完整。下一步会在保留用户接受度假设的前提下形成正式产品规划草案。
下一篇
下一篇是《教程（二）：从微信群消息中找到真正要解决的问题》，将进入第一次真实产品讨论。
它会具体展示：
- 群消息怎样变成需求证据；
- 为什么“消息容易被刷走”还不是最准确的问题；
- 为什么主动提醒进入了首版核心方向；
- 登录、微信号和提醒凭据怎样处理；
- 为什么产品讨论完成后仍然不能直接编码；
- 为什么已经写好的旧规划最终被删除。
最后
AI 降低了写代码的成本，却没有自动消除错误需求、权限漏洞、失败路径、发布风险和知识丢失。
因此，这套教程真正想建立的不是一条更长的提示词，而是一套可以检查的开发过程：
每一步都有真实输入
→ 每一步都有明确产物
→ 每一步都有退出条件
→ 每一步都区分事实与假设
→ 每一步都留下验证证据
→ 没有通过门禁就不跳到下一步
当这条链路真正跑通以后，AI 才不只是一个速度很快的代码生成器，而是进入了一套能够持续交付软件、也能被后来者继续维护的工作方式。
附录：相关工具与仓库
gstack
仓库：garrytan/gstack
地址：https://github.com/garrytan/gstack
本系列会根据实际阶段使用其中的产品讨论、产品评审、工程评审、真实浏览器检查、代码审查、上线检查和复盘能力。工具是否使用，以每篇文章的真实记录为准。
dev-harness
仓库：Dev-Wiki/dev-harness
地址：https://github.com/Dev-Wiki/dev-harness
本系列计划使用它维护项目上下文、统一构建与检查命令、生成开发计划和任务看板，并规范问题修复与版本管理过程。
UI UX Pro Max
仓库：nextlevelbuilder/ui-ux-pro-max-skill
地址：https://github.com/nextlevelbuilder/ui-ux-pro-max-skill
产品规划和关键用户流程稳定以后，本系列计划使用它辅助建立移动端页面的色彩、字体、间距、表单、状态反馈、响应式和无障碍设计基线。
