02 AI 协作工作流需求 → 拆解 → 交付本章解决一个问题怎么和 AI 协作才不翻车。它是一套通用方法论不绑定任何具体工具Codex、DeepSeek Harness、Cursor、Claude Code 等均适用因为翻车的原因从来不是工具而是用法。2.1 为什么工作流比提示词重要新手都在收集神级提示词高手在维护工作流。原因很简单提示词只影响单次产出质量一次对话的上下文一关一切归零工作流决定所有产出的下限它让第 100 次协作和第 1 次一样靠谱。再深一层看提示词是消耗品为这次任务定制、用完即弃工作流是资产这次优化的流程下个项目还在吃利息。把每次协作当一次性成本还是当一次流程改进长期差距是复利级的。一个反例把需求一段话贴给 AI → AI 直接开写 → 你大概扫一眼能跑就提交。这个模式下你的系统设计存在于聊天记录里你的测试是我试过一下你的文档是没有的。项目小的时候没事项目一大、人一换全是暗坑。正确的心智你指挥 AI 的方式就是你团队的管理方式。没有哪家正规团队是需求一句话甩给实习生第二天直接上线的。2.2 全景五个阶段五个阶段各有一个核心产出物缺一个就会在后面的某个环节还债阶段核心产出物没有它会怎样一需求澄清需求.md含待确认问题清单AI 理解的需求 ≠ 真实需求做完了才发现二设计与拆解设计.md 任务清单每次对话都在重新发明架构越改越乱三迭代实现一个个小步提交大坨改动无法验收出问题无法定位四验证测试 评审记录“能跑冒充能上线”五交付部署说明 变更记录交接靠口口相传回滚靠运气还要注意每个产出物都是一个阶段间对齐检查点——一份文档就是一次人审 AI的机会。五个阶段不是流程美学是把漫长的实现切成五次低成本纠偏这是离第 1 章缺陷经济学把发现前移最近的落地手段。2.3 阶段一需求澄清——先文档化再分析最后才允许写代码2.3.1 需求偏差是怎么被放大的模糊的需求就像一份没填完的函数签名——AI 要生成代码就必须给每个空白一个取值。它不会停下来问你它按全网最常见的设备点检长什么样来填你们厂三班倒、要先选模板再点检、异常项要拍照——这些只存在于你们厂的细节它一概用平均值填掉。更麻烦的是偏差的放大路径生成那一刻偏差只值一行字但它立刻被固化成表结构、接口、页面后续每个会话又把它当既定事实继续往上盖AI 从不质疑已经生成的代码直到验收那天你才发现做错了——此时返工不是改一行是推倒重来。需求歧义在源头只值 10 分钟的澄清被三层代码固化后就是两天的返工——成本为什么差百倍机制见第 1 章 1.3.2 缺陷经济学。所以阶段一的真实目标只有一句话在偏差还是一句话的时候抓住它别等它变成一个系统。2.3.2 把需求变成文件无论需求来自 PRD、会议、微信语音还是你自己的想法第一步都是落成仓库里的一个 Markdown 文件如docs/requirements/设备点检记录.md。口头需求直接贴给 AI 是最常见的翻车起点AI 会对模糊需求做出自己的、你不知道的补全。写这份文件时最值得花力气的是验收标准——它是后面所有验证的依据任务验收、测试用例、上线检查都引用它。写法只有一条每条都能拆成一个可执行的动作 一个可观察的结果。正例“提交点检后异常项自动出现在班组长的待办列表”反例“界面友好、性能良好”——无法执行、无法观察写了等于没写。2.3.3 先分析后实现让 AI 打草稿思维链原理给 AI 的第一句话永远是分析指令不是实现指令。这不只是谨慎背后有原理直接让它写代码等于让它一步输出终稿——在接龙机制下见第 1 章 1.2.2它必须在没人确认理解的情况下一口气预测完整个实现。而先让它写分析等于强迫它先打草稿、再落笔草稿分析文档本身就是后续生成代码的前文每一段推理都让下一段接龙的起点更准。这就是大模型领域的思维链Chain-of-Thought先推理再作答正确率显著高于直接作答。人也一样——口算 37×89 你也得打草稿不是你不行是复杂问题没人能一步出答案AI 也不能。更划算的是分析文档是给人审的中间产物。理解偏差在需求.md里暴露成本是改一段文字藏在 3000 行代码里成本是重写。分析文档是你和 AI 之间最便宜的对齐检查点。【需求分析提示词模板 · 可直接复制】 请阅读 docs/requirements/{需求名}.md并阅读现有工程代码 后端 src/main、前端 src/views、SQL 目录输出需求分析到 docs/需求.md 1. 需求理解摘要用你自己的话复述背景、用户场景、主流程——不要照抄原文 2. 验收标准列出可测试的验收语句做完什么动作能看到什么结果 3. 现有能力映射逐条说明哪些已支持指出对应代码位置、哪些要新增、哪些要改动 4. 待确认问题清单所有不明确、有歧义、前后矛盾之处每条附你的建议方案 5. 范围边界明确 v1 不做什么 6. 技术影响面预计涉及的表、接口、前端页面、配置 要求先读完上述文件再回答不要凭空推测只做分析不要写任何实现代码。关键动作逐条回答待确认问题清单。这一步的性价比全手册最高——用 10 分钟回答问题省掉的是几天返工。回答后更新进需求.md的澄清记录。2.3.4 反模式❌ “帮我做一个设备点检功能” —— AI 会用想象填补所有空白❌ 需求只存在于聊天窗口里换个会话就没了❌ 看到问题清单懒得答直接说你看着办。2.4 阶段二设计与任务拆解——设计文档驱动实现2.4.1 设计文档是外部记忆会话靠不住文件是唯一真相LLM 没有跨会话的持久记忆——会话像内存RAM断电即失文件才是磁盘。今天聊定表名用 biz_ 前缀、明细单独建表明天的新会话对这些一无所知除非这些决定写在它每次都能读到的地方。这解释了两个现象为什么边聊边做的项目每次都像从零开始——每次会话都在重新发明架构为什么文档厚一点反而更快——你不再需要每次口头交代全部背景。设计文档的本质是外部记忆External Memory把想清楚的成果存在 AI 够得着的地方而不是存在上次对话这个已经蒸发的地方。顺带它还消灭了传话失真你向每个新会话口头转述需求每一次转述都是一次失真的机会指向同一份文件所有会话读的都是原文。2.4.2 先出设计人审设计基于澄清后的需求.md让 AI 产出设计.md模板见第 9 章附录改动模块、数据模型、接口契约、影响面分析。你审的是这份文档不是之后的代码。这是拦住 AI清单的第一项拦住 AI数据库表结构、接口契约、模块划分这三样必须人审过才能进入实现。它们是系统的承重墙改动成本是代码的十倍——代码可以重写表结构和接口上线后再改就是手术。2.4.3 设计阶段提示词模板【设计提示词模板 · 可直接复制】 基于 docs/需求.md对本次功能进行技术设计输出到 docs/设计-{功能名}.md。 前提要求 - 先阅读现有代码相关模块的实体/Mapper/Service/页面禁止脱离现有工程凭空设计 - 遵守仓库根目录规则文件中的全部约定如有冲突在设计中显式标注出来 设计文档必须包含 1. 改动模块清单后端 / 前端 / 数据库各自改哪里 2. 数据库变更表结构 DDL含索引与注释、初始化 SQL、回滚方案 3. 接口契约每个接口的路径/方法/请求/响应/错误码/权限要求 标注哪些复用现有接口、哪些新增 4. 影响面分析逐个列出受影响的现有功能与兼容方案 5. 非功能指标对应的实现手段索引/缓存/异步 6. 风险清单你认为最可能出问题的三个点 完成后停下来等我评审不要开始写实现代码。2.4.4 拆解一个任务 一次可验收的提交让 AI 把设计拆成任务清单拆解标准只有一条每个任务半天内能完成、完成后能独立验证。## 任务清单示例设备点检记录 - [ ] T1 数据库建表 初始化 SQL验收SQL 在本地库执行通过字段与设计一致 - [ ] T2 后端实体/Mapper/Service CRUD验收单元测试通过 - [ ] T3 后端Controller 接口 参数校验验收Apifox 调通异常有错误码 - [ ] T4 后端分页查询 车间数据权限过滤验收A 车间账号查不到 B 车间数据 - [ ] T5 前端列表页 表单页验收联调走通 - [ ] T6 集成端到端流程验证验收按需求.md 验收标准逐条过拆得细的好处在阶段三体现每个任务的产出都小到你能认真验收。AI 一口气生成 3000 行你没法验生成 300 行你就能。拆解质量有个快速自查对着清单问两个问题——每个任务能不能独立演示我能不能想象出验收这个任务时我在屏幕前具体看什么想不出看什么的任务说明它没有可观察的行为边界回炉。【任务拆解提示词模板 · 可直接复制】 基于 docs/设计-{功能名}.md把实现拆解为任务清单追加到该文档任务清单一节。 拆解规则 - 每个任务半天内可完成且完成后可独立验证必须写明验收怎么算过 - 按依赖排序数据库 → 后端 → 前端 → 集成 - 一个任务只做一件事需要同时改两个模块的拆成两个任务 - 涉及表结构变更、公共模块、新增依赖的任务单独拆出并打上【人工审核】标记 每个任务格式T{n} {范围}{内容}验收{可观察的标准}2.4.5 反模式❌ 没有设计文档直接实现——架构决策全部埋进代码里❌ 任务拆成前端、后端两个大块——等于没拆❌ 设计文档写完不回头看代码是否遵守——文档和代码各走各路。2.5 上下文管理让每次协作站在同一起点2.5.1 规则文件项目的入职培训手册在仓库根目录维护一个规则文件各类工具都支持常见名如AGENTS.md、CLAUDE.md、.cursor/rules内容通用每次会话 AI 自动读取。它解决每次都要重新交代一遍的问题。规则文件该放什么放什么示例技术栈与版本SpringBoot 2.7 Vue2 MySQL 5.7禁止引入新框架目录结构约定后端ruoyi-system前端src/viewsSQL 放sql/编码规范Controller 不写业务逻辑统一返回体AjaxResult数据库约定表名前缀biz_必须有create_time逻辑删除用del_flag项目禁忌不改公共模块不新增第三方依赖除非说明理由2.5.2 长会话为什么会衰减工作台面原理一段会话超过十几轮后AI 的产出质量会明显衰减——忘记早期约束、开始自我矛盾。这不是玄学把上下文窗口想成一张固定大小的办公桌就懂了会话刚开始桌上只有规则文件和当前任务AI 对每份材料的注意力都很足对话越长桌上堆的纸越多——每一轮的代码、报错、中间产物全在桌上。两件事同时发生注意力被摊薄材料越多分给第三轮定的那条约束的注意力就越少——早期约束“表名前缀 biz_”逐渐在和最近内容的竞争中失势失真在累积十几轮之后早期约束实际是经过多轮传话的间接引用早已不是原始表述。这就是上下文腐败不是 AI忘了是桌上的东西多到它顾不过来。应对策略全部围绕管理桌面一个任务一个新会话开场喂给它规则文件自动需求.md设计.md 当前任务结论及时落盘会话中产生的有价值决定如新增的约定写回规则文件或设计文档而不是留在聊天里大改动手动分段让 AI 干完一个任务就停验完再开下一个。2.5.3 把项目知识库变成正向循环需求.md、设计.md、任务清单、规则文件共同构成项目知识库。知识库越厚你每次要说的话越少AI 产出越稳。这就是全景图里文档沉淀 → 上下文回填那个回环。2.6 阶段三迭代实现——小步快走逐个验收2.6.1 为什么必须小步提交两个原理实现阶段只有三条纪律但每条都反直觉所以先讲透为什么原理一变更定位的二分法。每个小提交都是给变化打的坐标。出问题时git bisect自动做二分查找10 个提交约 3~4 次运行就能锁定坏提交100 个提交也只要 6~7 次——对数级的定位效率前提是每个提交都足够小、足够独立。具体感受一下提交历史 c1~c6已知 c1 是好的bisect 先测 c4 发现坏了再测 c3 发现是好的——定位 c4两次运行代替通读六次改动。而一个大提交等于没有任何坐标问题在里面只能通读 3000 行。提交信息写清楚为什么改如feat(点检): T2 点检记录CRUD及单元测试是在给坐标命名。原理二认知负荷的上限。人的工作记忆同一时刻只能保持大约 4 个信息块认知负荷理论教育心理学的经典结论。一次验收 300 行你能真正看进去每行在干什么一次验收 3000 行你实际在做的是扫格式——恰好是 AI 最擅长伪装的部分见第 1 章 1.2.2。顺带一提LLM 的上下文窗口同样有限一次让它改 5000 行它对每行的注意力也被稀释出错率同步上升。拆小任务是把你和 AI 都安排在各自的最佳工作区间。于是三条纪律一次只给 AI 一个任务。顺便把那个也改了是事故之源——改动范围失控出问题无法二分定位。每个任务完成后立即验收再开下一个。验收依据就是任务清单里写的验收标准不是看起来行了。改动必须形成小提交。提交信息说清楚为什么改出问题时 bisect 在一堆小提交里定位比在大提交里大海捞针快一百倍。2.6.2 任务执行提示词模板阶段三是提示词最不该发挥创意的阶段——任务指令越机械越好把发挥空间留给纪律【任务执行提示词模板 · 可直接复制】 当前任务T{n}来自 docs/设计-{功能名}.md 任务清单原文如下 {粘贴该任务的完整描述含验收标准} 上下文动手前先阅读仓库根目录规则文件、docs/需求.md 的验收标准部分、 docs/设计-{功能名}.md 中与 T{n} 相关的章节。 执行要求 1. 只完成 T{n}不顺带修改其他任务范围内的代码 发现应该顺手改的地方单独列出来等我决定不要自己改 2. 新增代码严格遵守设计文档里的表结构/接口契约风格与现有代码一致 3. 完成后自述改了哪些文件、每个文件为什么改、有没有偏离设计点 以及你的自测步骤和结果 4. 给出本次改动的提交信息格式{类型}({模块}): T{n} 描述第 3 条自述别省AI 自己报告改动清单既是给你的 diff review 提供导航也是一次廉价的自我对账——它的自述和它实际的 diff 对不上时你就抓到问题了。2.6.3 必须拦住 AI 的时刻场景原因你要做的涉及数据删除/迁移的 SQL不可逆操作亲自审查备份与回滚方案后手动执行引入新依赖/新服务供应链与运维成本确认必要性、活跃度、许可证修改公共模块/框架层影响面远超当前任务单独评审与功能改动分开提交接触密钥、权限、支付等敏感逻辑出事即事故逐行人工审查详见第 5 章表结构、接口契约变更承重墙手术回到阶段二更新设计评估兼容性2.6.4 Code Review 自查让 AI 先自己审一轮提交前让 AI 按清单自查、人再终审人的终审不可省理由见 2.8 分工表【Code Review 自查提示词模板 · 可直接复制】 请对本次改动{说明本次改动的范围}做自查输出问题清单不要修改代码。 逐项检查 1. 正确性空集合 / null / 超时 / 事务边界是否处理是否有 catch 后无任何动作的静默吞异常 2. 伪实现是否有 TODO / 空方法 / 降级为静默的假成功 3. 安全查询是否缺数据权限过滤SQL 是否有字符串拼接是否有硬编码密钥/密码 4. 性能是否有循环内查库或远程调用列表查询的过滤字段是否有索引是否在内存过滤大结果集 5. 一致性与 docs/设计-{功能名}.md 是否一致表结构、接口契约、命名 6. 规则是否违反仓库根目录规则文件中的约定 输出格式按严重度排序阻断/严重/提示每条附文件与行号、问题原因、修改建议 检查无问题的项也明确写已检查未发现问题。2.7 阶段四与五验证与交付详见第 7 章验证不是我点过没问题而是分层的单元测试AI 写、你判断测得对不对→ 接口联调 → 端到端按验收标准逐条过。交付物包括部署说明环境变量、初始化 SQL、配置项、变更记录改了哪些表/接口、影响的旧功能。交付物不是形式主义部署说明是写给三个月后凌晨排障的你的变更记录是回滚决策的依据。本章先立规矩具体手段见第 7 章。2.8 人机分工边界总表职责AI 干人干需求理解复述、提问题、给建议确认理解对不对、拍板范围方案设计产出候选方案、分析影响面选型拍板、审表结构/接口契约编码主体实现把关敏感逻辑安全/数据/架构测试生成测试用例和代码判断测的是不是该测的、跑通验收标准评审自查、按清单初筛终审责任人见第 7 章 Review 清单决策类架构选型/安全策略/数据设计提供信息全责不可下放运维类上线/回滚/密钥生成脚本与预案亲自执行与确认这张表背后只有一条划分原则凡是决定系统应该是什么样的人负责凡是把它做出来的AI 负责。前者——选型、契约、安全边界、数据设计——做错了要返工、要赔偿、要担当而 AI 没有承担能力也无承担通道见第 1 章无利益相关机制后者的规模优势 AI 碾级领先不用白不用。把这条原则想透遇到表里没列的新场景也知道怎么分。2.9 本章检查清单接到一个新需求时需求已落成docs/下的文件而不是停留在聊天窗口每条验收标准都能拆成一个可执行的动作 一个可观察的结果先让 AI 做了需求分析输出了待确认问题清单我逐条回答了问题清单澄清记录已更新设计.md已产出表结构/接口契约经我人工审核任务已拆解每个任务半天内可完成、有独立验收标准想不出验收时看什么的任务已回炉规则文件AGENTS.md 等存在且包含本项目约束实现过程中一次一个任务、每个都验收、小步提交AI 的任务自述与实际 diff 对过账——对不上就是抓到问题了所有拦住 AI清单上的操作由我亲自完成会话中的新决定已写回文档而不是留在聊天里2.10 常见卡点问答FAQQ1AI 说已修复/已完成我怎么验证看行为不看表态。AI 的改好了是文本预测不是测试结论——它没有运行过任何东西见第 1 章 1.2.2它的自信没有任何代价。三个动作① 按复现路径重走一遍——怎么发现的 bug就怎么验证修复② 看本次 diff 而不是全文件——改动范围对不对、顺带改了什么③ 有测试就跑测试套件。它说好了和好了之间的差距就是第 7 章要填的。Q2任务拆多细才算对回到唯一标准能不能独立验收。两个报警信号验收一个任务要同时检查三个以上地方 → 太粗任务小到没有可观察行为“写了一个 DTO”→ 太细纯浪费切换成本每个任务都要重新喂上下文。经验值一个中等功能 4~8 个任务数据库/后端/前端/集成天然是四段。拿不准时宁可偏粗一点验收时发现验不动再拆——拆细了浪费的是你的时间拆粗了浪费的也是你的时间但后者至少能被发现。Q3规则文件写多长合适上限大约 100~150 行。原因直接来自 2.5.2规则文件也是台面上的纸越长单条规则分到的注意力越少AI 反而更容易漏。取舍原则是分层存放项目铁律技术栈、命名、禁忌进规则文件每次都读项目知识设计决策、接口约定进docs/按需引用一次性约定“这个功能先这样”留在当前会话即可。另一个判断法AI 连续违反的约定才值得进规则文件——一个月没人违反的规则是噪音。Q4AI 不遵守规则文件怎么办按概率排查① 会话太长、注意力稀释了 → 换新会话见 2.5.2② 规则太抽象 → 遵循最佳实践没有约束力禁止物理 DELETE一律用 del_flag才有——规则要具体到能机械执行③ 任务指令和规则冲突、任务赢了 → 关键禁忌在任务提示词里重申一遍④ 工具根本没加载规则文件 → 检查文件名和位置。都不管用的终极手段把规则变成机器门禁——用 lint/CI 拦禁System.out、强制参数化查询机器不会分心比提示词可靠得多详见第 7 章 CI 门禁。Q5会话进行到一半发现需求理解错了怎么办立刻停别心疼沉没成本——已经生成的错误代码不会因为再多改两轮变对。三步止损① 停止当前任务② 回阶段一更新需求.md澄清记录里写明此前理解有误正确理解是…③ 评估已产出物——设计哪些章节作废、任务清单怎么重排、已提交的代码哪些可救。判断依据回到缺陷经济学第 1 章 1.3.2现在花 20 分钟返工比带着偏差再盖三层楼便宜十倍。这正是为什么要求 AI 先复述需求、而不是直接写代码见 2.3.3。Q6项目就我一个人也要走完整流程吗要——恰恰因为是一个人。流程里每个环节替代的其实是队友需求澄清替代产品经理的追问设计评审替代架构师的把关检查清单替代 Reviewer 的另一双眼睛。AI 不会替你做这些它只会顺着你走见第 1 章无利益相关机制。可以裁剪的是产物体积不能裁剪的是阶段单人版可以需求设计合并成一个 20 行的文件、任务清单 3 条、规则文件 30 行。产物可简阶段不可省——阶段防的不是队友犯错是你自己靠记忆和聊天记录干活。