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