AI 软件开发实战教程（八）：先让项目能稳定地跑起来

“AI 软件开发实战教程”系列第 7 篇把产品规划、工程架构和页面设计整理成纵向开发任务、状态看板与验收覆盖矩阵让 TDD 不会变成一堆彼此失联的测试。到上一篇为止邻行已经有了三份重要事实源产品规划说明首版做什么、为什么做和怎样验收工程架构说明事务、并发、权限、后台任务和测试边界页面体验说明用户看到什么、怎样操作以及各种状态如何表达。现在可以开始写代码了吗还差一个容易被低估的步骤把这些横跨几十页的规则拆成可以独立完成、独立验证和独立提交的任务。如果直接让 AI“按照文档把整个项目实现出来”常见结果是先一次性创建所有数据库模型再一次性创建所有页面最后补一些测试看板显示功能很多实际没有一条完整流程能运行产品规划中的边界散落在代码里没人知道有没有遗漏。这次使用dev-harness-planning生成计划但没有把模板填满就算完成。计划必须证明两件事每个任务能产生一个可运行结果所有产品验收场景都有唯一负责人。看板和任务详情为什么要分开一个计划文档同时写状态、背景、文件、步骤、测试和风险很快就会变得难以扫描。邻行把计划分成三层Dashboard.md 当前阶段、任务状态、优先级和跳转 TaskDetails.md 每个任务的目标、文件、TDD 步骤、验证和提交边界 AcceptanceMatrix.md AC-01 到 AC-56 的负责人、证据类型和真实状态看板只回答“现在做到哪里、下一项是什么”。任务详情回答“这项工作怎样做完”。验收矩阵回答“哪一条产品规则由谁证明”。三份文档职责不同可以避免在多个地方复制同一大段实现说明。任务状态变化时更新看板测试证据变化时更新验收矩阵实现步骤只在任务详情维护。不按技术层拆而按用户闭环拆一种常见拆法是任务一设计全部数据表 任务二实现全部后端接口 任务三实现全部前端页面 任务四补自动测试这种拆法对分工看起来整齐对验证却很不友好。完成第一项以后用户还不能做任何事完成第二项以后仍然没有可用页面到了最后才发现表结构或接口不适合真实流程前面的“完成”需要大面积返工。邻行改用纵向切片社区邀请、登录与私密资料 → 从规则、数据库、服务到真实注册页面一起完成 结构化发布、信息大厅与详情 → 从时间规则、发布幂等到移动页面一起完成 候选计算、解释与站内事件 → 从匹配纯函数到双方页面一起完成 联系方式双向交换 → 从权限、事务、加密快照到复制降级一起完成每项完成后都多出一条可以实际运行的用户能力也能立即用浏览器检查架构和页面设计是否真的成立。技术层仍然存在但它们服务于同一个切片而不是各自成为“已经完成”的孤岛。第一个任务不是业务功能在纵向开发以前计划保留一个前置任务 V0工程骨架与验证契约。它要建立Python、Django 和 PostgreSQL 的锁定环境Web、Worker 和数据库的本地运行方式自定义用户模型的第一条迁移格式、静态检查、单元、集成和浏览器测试可注入时钟不会调用真实第三方的假提醒渠道setup、quick、test、e2e、check 等统一命令。V0 不是先搭一套宏大平台。它只负责让后面的每个任务都能以相同方式启动、测试和验收。例如产品大量依赖截止时刻如果没有可注入时钟测试就会靠真实等待或修改系统时间既慢又不稳定。又例如最后一个座位依赖 PostgreSQL 行锁如果测试环境默认偷偷使用 SQLite测试通过也不能说明并发正确。验证环境本身是产品正确性的一部分。每个任务都先写“怎样失败”任务详情没有只列“实现账号、实现发布、实现匹配”而是为每项写了 RED、GREEN、REFACTOR。以联系方式交换为例RED 非候选、跨社区、受限账户、失效候选必须拒绝 重复点击和并发点击不能产生两次交换 非参与者和页面源码不能看到微信号 GREEN 实现短事务、重新校验、一对一交换和加密快照 双方同时得到对方微信号 REFACTOR 模板上下文只装入当前用户有权看到的一方资料 权限判断集中在服务不散落在页面“先写失败测试”不是追求红色输出本身。测试必须因为目标能力尚未实现而失败而不是因为导入路径写错、数据库没启动或测试代码本身报错。确认红灯原因正确以后才写最小实现让它变绿。一个任务要同时拥有多个证据层次不是所有规则都适合用同一种测试。匹配时间窗口可以用纯函数测试社区权限需要 HTTP 集成测试最后一个座位需要 PostgreSQL 双连接并发复制降级需要浏览器微信分享和会话保持最终需要真机。因此任务详情为每项规定证据层次纯规则 → 时间、地点、状态、提醒分类 服务和数据库 → 幂等、授权、事务、事件一致性 HTTP → 登录、跨社区、CSRF、表单和源码 Playwright → 两个用户的完整移动页面流程 真实设备和外部人员 → 微信 Gate、群管理员、隐私与法律审查越接近用户环境的测试覆盖面越大但它不能代替更底层的精确规则测试。反过来单元测试再多也不能证明微信内置浏览器真的可用。56 个验收场景为什么需要单独矩阵产品规划已经写了 56 个验收场景。如果只在任务描述中随手标几个编号很难发现某一条没人负责同一条被多个任务都认为由对方负责人工 Gate 被写成自动化已通过任务完成后没有真实测试路径。验收矩阵为 AC-01 到 AC-56 每条记录场景摘要唯一负责人计划证据当前真实状态。生成以后做了机器检查编号范围AC-01–AC-56 总数56 顺序完整是 重复0 遗漏0 当前自动通过0最后一行很重要。计划覆盖了 56 条不代表实现通过了 56 条。当前状态全部是“未实现”或“等待成品”这才符合项目事实。“协作任务”和“最终负责人”要分开一条验收往往跨多个模块。例如 AC-24 要求第三方提醒失败不能回滚发布、候选或交换而且一方失败不影响另一方。候选任务会创建业务事件交换任务会保存交换事实提醒任务会处理发送失败。三项都参与但验收矩阵仍把 K7 提醒任务设为最终负责人。这样关闭任务时不会出现K3我已经创建事件剩下不是我的问题 K4交换已经保存提醒由别人测试 K7上游应该已经保证事务我只测 HTTP协作关系可以有多个最终关闭责任只能有一个。把最危险的测试单独标出来验收矩阵没有把所有场景都写成“自动测试”。几类证据被明确加粗AC-27 最后一个座位必须在 PostgreSQL 做真实并发AC-23、AC-39、AC-40必须主动扫描“不包含”敏感资料AC-31 到 AC-35只能由 iOS 和 Android 微信真机最终通过AC-39除了代码和备份检查还需要隐私与法律审查共同关闭。这能防止自动化系统为了提高通过率用容易执行但证据不足的测试替换真实要求。外部 Gate 也要进看板但不能自动完成Gate B 和 Gate C 被当作正式任务保留G1微信成品真机验收 状态等待可运行成品 G2受控试用准备 状态等待外部人员与合规证据它们有明确输入、步骤和通过条件却不会在 AI 完成代码后自动变绿。G1 需要真实 iOS、Android、微信版本和测试群G2 需要群管理员同意、地点确认、七天基线、试用名单以及隐私和法律意见。计划可以替这些工作准备记录模板不能替责任人签字。看板的状态必须反映事实邻行统一使用几种状态 规划中任务定义完成代码尚未开始 开发中当前正在执行而且同时只能有一个✅ 已完成退出条件和证据全部满足⏸️ 等待成品/外部任务定义清楚但缺少真实输入 远期没有真实数据支持现在进入首版。创建了文件不等于任务完成测试通过一部分也不等于任务完成AI 暂时停止更不等于任务受阻。每个任务完成时必须同时更新看板状态任务详情中的验证记录验收矩阵中的真实证据路径节点检查点本地 Git 提交。这让第二天查看项目的人不必从聊天记录猜测实际进度。计划也要接受自动检查文档不是代码但仍然可以做一些确定性验证。本次计划检查了Dashboard 中有 14 个任务TaskDetails 中有对应的 14 个任务标题验收矩阵恰好有 56 行编号严格等于 1 到 56没有重复没有TBD、TODO、FIXME等模板残留Markdown 没有明显空白错误。这不能证明任务拆分一定完美却能消除链接缺失、编号漏掉和模板没填完这类低级错误。本节点形成的实际开发顺序邻行首版最终按这个顺序推进V0 工程骨架 → K1 社区访问与私密资料 → K2 发布、大厅和详情 → K3 候选与站内事件 → K4 联系方式交换 → K5 双方反馈与座位 → K6 编辑、截止和状态生命周期 → K7 外部提醒 Worker → K8 删除、审计和社区管理 → K9 完整移动浏览器验收 → K10 部署、恢复和试用数据 → G1 微信真机 → G2 受控试用准备K4 完成以后登录—详情—交换—复制的首条成品闭环已经存在可以开始准备微信真机测试但完整 Gate B 仍等到 K9 页面和浏览器质量收束。写在最后一个好计划不是把所有工作都提前写得很详细。它应该让下一步足够明确让每条产品规则都有负责人让不同证据不会互相冒充也让远期想法不会偷偷混进首版。现在邻行的下一步已经非常具体执行 V0先写配置和健康检查的失败测试建立 PostgreSQL 与统一验证命令。从这一刻开始后续教程会进入真正的 TDD 开发。文章不会只展示最后的绿色测试还会记录第一条测试为什么失败、最小实现怎样让它通过、重构改变了什么、浏览器看到了什么以及还有哪些真实 Gate 不能由 AI 关闭。本篇验证摘要计划按用户可完成的纵向流程拆分而不是按模型、页面和接口横向切块每项任务都记录产品规则、第一条失败测试、实现范围和完成门禁56 条验收场景分别标注负责人、自动证据、浏览器证据或人工验证要求PostgreSQL 并发、微信真机和真实用户接受度不会被普通单元测试代替看板允许“部分通过”和“环境待验”避免任务完成被误写成产品已上线。附录相关工具与仓库gstack仓库garrytan/gstack地址https://github.com/garrytan/gstackdev-harness仓库Dev-Wiki/dev-harness地址https://github.com/Dev-Wiki/dev-harnessUI UX Pro Max Skill仓库nextlevelbuilder/ui-ux-pro-max-skill地址https://github.com/nextlevelbuilder/ui-ux-pro-max-skill