AI编码流水线实战：从需求澄清到PR的六阶段可复用编排

1. 从“随口一问”到“流水线”为什么零散对话式开发撑不起真实项目我最早用 AI 写代码的方式和大多数人一样打开对话框敲一句“帮我写个登录接口”拿到一段代码复制进项目跑一下报错再贴回去让它改。来回几轮功能勉强能跑但过两天要加个字段、改个校验规则我发现自己完全想不起来当时是怎么跟 AI 描述需求的也说不清那段代码为什么长成那样。更麻烦的是同一个需求换个人来问 AI产出的结构、命名、异常处理风格全不一样代码库很快就变成了一锅粥。这种“随口问”的模式本质上是把 AI 当成了一个随叫随到的代码补全器而不是研发流程里的一个环节。它的问题不在于 AI 写得不好而在于需求没有被结构化过程没有被固化产出没有被约束。一个真实的功能开发从需求澄清、方案设计、编码、自测到提交 PR中间有大量需要人工判断和机器执行的衔接点。如果每个衔接点都靠临时对话去驱动那这条链路就是不可复现的也就谈不上“可复用”。我后来做的一件事就是把这条链路编排成一条流水线需求进来之后先经过结构化的澄清和拆解再进入方案设计然后由 AI 在隔离的工作区里编码接着自动跑测试、生成变更说明最后落到一个标准的 PR 上。整条链路里AI 只负责它擅长的部分人负责决策和验收而流程本身是固定的、可重复执行的。这就是标题里说的“可复用的流水线”。关键词里出现的 Maestro、CodeBuddy Code、git worktree、PR其实正好对应了这条流水线的几个关键环节Maestro 负责把 UI 自动化测试这一环接进来CodeBuddy Code 承担编码执行git worktree 解决多任务并行时的环境隔离PR 则是最终交付的载体。这几个词不是随便凑在一起的它们各自解决流水线里一个具体的痛点。下面我会把整条流水线拆开讲清楚每个环节为什么这么设计、怎么落地、以及我在实操中踩过的坑。适合读这篇的人大概是这几类已经在用 AI 辅助编码但觉得产出不可控的开发者想把 AI 引入团队研发流程但不知道怎么规范的技术负责人以及单纯好奇“AI 写代码”这件事怎么从玩具变成生产力工具的人。不管你用的是哪家的编码助手这套编排思路都是通用的。2. 流水线的骨架设计把一次需求开发拆成六个可独立执行的阶段2.1 为什么是“阶段”而不是“步骤”我一开始也想过用“步骤”这个词但后来改成了“阶段”。区别在于步骤是线性的、必须按顺序走的而阶段是可以有回退、有并行、有分支的。真实开发里方案设计阶段发现需求没澄清清楚是要退回去重新澄清的编码阶段可能同时有多个任务在跑需要并行。用“阶段”来建模更贴近实际。整条流水线我拆成了六个阶段需求澄清、方案设计、任务拆解、编码执行、验证测试、交付提交。每个阶段都有明确的输入、输出和验收标准。输入输出用文件来承载而不是靠对话上下文这是整条流水线可复用的关键。对话上下文是易失的文件是持久的。2.2 六个阶段的输入输出定义我把每个阶段的契约整理成了下面这张表这张表就是整条流水线的“接口文档”。只要每个阶段都严格遵守自己的输入输出格式整条链路就能像流水线一样串起来任何一个环节换人、换工具都不影响整体运转。阶段输入输出验收标准需求澄清原始需求描述结构化需求文档包含背景、目标、边界、验收条件方案设计结构化需求文档技术方案文档包含接口设计、数据模型、关键取舍任务拆解技术方案文档任务清单每个任务可独立编码、可独立验证编码执行单个任务 方案文档代码变更通过本地静态检查验证测试代码变更测试报告单元测试通过 关键路径验证交付提交代码变更 测试报告PR描述完整、变更聚焦、可评审这张表看起来简单但真正落地的时候每个阶段的输出格式都需要反复打磨。比如“结构化需求文档”到底包含哪些字段我改了三四版才稳定下来。太简单了方案设计阶段信息不够太复杂了写文档本身就成了负担。2.3 用文件系统承载阶段产物我选择用文件系统而不是数据库或者某个平台来承载这些产物原因很实际文件可以被 git 管理可以被 diff可以被 review可以被任何工具读取。每个需求对应一个目录目录里按阶段存放产物requirements/ REQ-2024-001-user-login/ 01-clarification.md 02-design.md 03-tasks.md 04-code/ 05-test-report.md 06-pr-description.md这个目录结构本身就是流水线的状态机。看一个需求走到哪一步了直接看目录里有哪些文件就行。哪个阶段卡住了对应的文件就是空的或者不完整的。这种“用文件系统当状态机”的做法比引入一套额外的流程管理工具要轻得多也更容易被团队接受。提示目录命名里带上需求编号和简短描述编号用于排序和引用描述用于人眼快速识别。不要用纯编号也不要只用描述两者结合最实用。3. 需求澄清阶段让 AI 先问清楚而不是先动手3.1 随口问 AI 最大的坑需求是模糊的AI 却假装懂了我踩过最多次的坑就是需求本身没想清楚就丢给 AI。比如“加个用户登录功能”这句话里藏着一堆没定的东西用手机号还是邮箱登录要不要验证码密码强度规则是什么登录失败几次锁定token 有效期多久这些我都没说AI 也不会问它直接按最常见的做法生成一版。结果就是代码写完才发现方向不对返工的成本比一开始澄清需求高得多。后来我强制在流水线最前面加了一个澄清阶段而且这个阶段不允许 AI 写任何代码只允许它提问和整理。这个约束很关键因为 AI 一旦开始写代码就会倾向于把模糊的地方用自己的假设填满而不是暴露出来。3.2 澄清阶段的提示词结构我在这个阶段用的提示词大概是这个结构核心是让 AI 扮演一个“较真的需求分析师”而不是“听话的执行者”你是一个需求分析师。下面是一段原始需求描述。 你的任务不是设计方案也不是写代码而是 1. 列出这段描述里所有模糊、缺失、有歧义的地方 2. 针对每个模糊点给出 2-3 个可能的选项并说明各自的影响 3. 整理成一份结构化需求文档包含背景、目标、功能边界、非功能要求、验收条件 原始需求 {requirement_text}这个提示词里“不是设计方案也不是写代码”这句约束非常重要。我试过不加这句AI 会忍不住在澄清阶段就把技术方案也写了导致后面方案设计阶段没东西可做而且澄清和设计混在一起出了问题很难定位是哪个环节的锅。3.3 澄清产物的字段设计澄清阶段产出的结构化需求文档我固定了几个字段。这些字段不是拍脑袋定的是踩坑踩出来的。比如“功能边界”这个字段就是因为我遇到过好几次需求蔓延——本来只做登录做着做着把注册、找回密码都带进来了最后 PR 巨大无比评审的人根本看不完。背景为什么要做这个需求解决什么问题目标做完之后达到什么状态尽量可量化功能边界明确做什么更重要的是明确不做什么非功能要求性能、安全、兼容性等约束验收条件什么情况下算完成最好能对应到测试用例“不做什么”这一项我强烈建议每次都写。它看起来是废话但实际能省掉大量扯皮。AI 在编码阶段如果看到边界里写了“不处理第三方登录”它就不会自作主张去加 OAuth 相关的东西。3.4 澄清阶段的人工介入点这个阶段不能全交给 AI。AI 能列出模糊点但很多模糊点的答案只有业务方或者产品负责人知道。我的做法是AI 产出澄清文档后我快速过一遍把那些需要人拍板的选项标出来去确认然后把确认结果补回文档。这个过程通常十几分钟但能省掉后面几个小时的返工。注意澄清文档一旦确认就冻结。后续阶段如果发现要改必须回到这个文档改而不是在编码阶段临时决定。否则流水线的可追溯性就断了。4. 方案设计与任务拆解把“怎么做”变成可执行的清单4.1 方案设计阶段的核心是“取舍”不是“堆砌”方案设计阶段最容易犯的错是让 AI 写一份面面俱到的技术方案把能想到的技术点全列上。这种方案看起来专业实际上没法指导编码因为里面没有取舍。真正有用的方案是明确告诉编码阶段“我们选 A 不选 B因为 C”。我在提示词里会明确要求 AI 对每个关键技术点给出至少两个备选方案并说明选择理由。比如数据存储选关系型还是文档型接口用 REST 还是 RPC鉴权用 session 还是 token。这些取舍写清楚了编码阶段就不需要再做架构决策只需要执行。基于以下结构化需求文档输出技术方案。 要求 1. 对每个关键技术决策点给出至少两个备选方案 2. 说明每个方案的优缺点和适用场景 3. 明确给出推荐方案和理由 4. 输出接口设计请求/响应结构和数据模型 5. 列出这个方案的主要风险和缓解措施 需求文档 {clarification_doc}4.2 任务拆解的粒度控制任务拆解是整条流水线里最考验经验的一环。拆得太粗一个任务里包含太多决策AI 编码时容易跑偏拆得太细任务之间依赖关系复杂管理成本高。我摸索出来的粒度标准是一个任务应该能在一次编码会话里完成且产出的代码变更可以独立验证。具体来说一个任务通常对应一个接口、一个数据模型、或者一个独立的功能点。如果一个任务需要改动超过五个文件或者需要同时处理前端和后端那大概率是拆得不够细。反过来如果一个任务只是“加一个字段”那可能拆得太细了可以和相邻的改动合并。任务清单我用一个固定格式来写每个任务包含任务编号、任务描述、依赖任务、涉及文件、验收方式。这个格式让编码阶段可以逐个任务独立执行也让并行执行成为可能。4.3 任务之间的依赖关系怎么表达依赖关系用任务编号来引用比如“T003 依赖 T001”。这样在并行执行的时候可以快速判断哪些任务可以同时跑哪些必须等。我一般会把没有依赖关系的任务标记为可并行然后在编码阶段用 git worktree 给每个并行任务开独立的工作区。这里有个经验尽量不要让任务依赖超过两层。如果发现依赖链很长说明任务拆解有问题应该重新审视是不是把一个大功能拆成了必须串行的小步骤。串行步骤越多流水线的吞吐就越低。5. 编码执行阶段git worktree 隔离 CodeBuddy Code 执行5.1 为什么必须做工作区隔离编码阶段是整条流水线里最容易出乱子的地方。多个任务并行的时候如果都在同一个工作目录里改git 状态会互相污染测试跑出来的结果也不可信。我最早就是所有任务在一个目录里顺序做做完一个提交一个效率很低。后来尝试并行结果两个任务的改动混在一起回滚都回滚不干净。git worktree 解决的就是这个问题。它允许你在同一个仓库上挂载多个工作目录每个目录对应一个分支互不干扰。给每个并行任务开一个 worktree任务之间就完全隔离了。任务完成后各自提交到自己的分支最后再合并。# 为任务 T001 创建工作区 git worktree add ../worktrees/T001 -b task/T001 # 为任务 T002 创建工作区 git worktree add ../worktrees/T002 -b task/T002 # 查看所有工作区 git worktree list # 任务完成后清理 git worktree remove ../worktrees/T001这套命令我基本是脚本化的任务清单生成之后自动为每个可并行任务创建 worktree。任务完成后自动清理。手工敲这些命令容易出错尤其是清理的时候忘了删分支时间长了分支列表会非常乱。5.2 CodeBuddy Code 在编码阶段的角色CodeBuddy Code 这类编码助手在这个阶段承担的是“执行者”角色。它接收的是单个任务加上方案文档输出的是代码变更。关键在于它接收的上下文是结构化的、有边界的而不是一句模糊的自然语言。我在这个阶段的提示词会明确告诉它只做这个任务范围内的事不要改无关文件不要引入方案文档里没提到的依赖。这个约束能大幅降低 AI“顺手优化”带来的意外变更。我遇到过好几次AI 在实现一个接口的时候顺手把旁边一个不相关的工具函数重构了结果那个函数有别的调用方直接导致编译失败。你是一个编码执行者。下面是任务描述和技术方案。 要求 1. 只实现任务描述范围内的功能 2. 不要修改任务范围外的文件 3. 不要引入方案文档未提及的第三方依赖 4. 遵循项目现有的代码风格和目录结构 5. 完成后输出变更文件列表和简要说明 任务描述 {task_desc} 技术方案 {design_doc}5.3 编码阶段的常见意外与处理即便约束得再好编码阶段还是会有意外。我总结了几类高频问题。第一类是 AI 对项目现有结构理解不足把新代码放错目录。这个通过在提示词里附上项目目录树可以缓解。第二类是命名风格不一致AI 用了自己的命名习惯。这个通过在提示词里附上几个现有文件的示例可以缓解。第三类是边界条件处理缺失比如空值、超时、并发。这个需要在任务描述里显式列出边界条件。提示在编码阶段开始前把项目里两三个有代表性的文件作为“风格样例”附给 AI比写一堆风格规则更有效。AI 模仿样例的能力很强。6. 验证测试阶段Maestro 接住 UI 自动化这一环6.1 单元测试之外为什么还需要 UI 自动化编码阶段完成后第一层验证是单元测试。但单元测试只能覆盖函数级别的逻辑覆盖不了真实用户路径。我遇到过好几次单元测试全绿但实际跑起来页面点不动的情况原因是某个按钮的绑定事件在重构时被删了单元测试根本没覆盖到这一层。这就是 Maestro 这类 UI 自动化工具的价值。它用声明式的 YAML 描述用户操作流程跑起来就是模拟真实点击、输入、跳转。对于登录、下单、支付这类关键路径我会在验证阶段跑一遍 Maestro 流程确认端到端是通的。appId: com.example.app --- - launchApp - tapOn: 登录 - inputText: 13800138000 - tapOn: 获取验证码 - inputText: 123456 - tapOn: 确认登录 - assertVisible: 首页这段 YAML 描述的就是一个完整的登录流程。它的好处是可读性极强产品经理都能看懂而且改动成本低加一个步骤就是加一行。6.2 验证阶段的测试报告怎么组织验证阶段的输出是一份测试报告我固定包含这几块单元测试结果、UI 自动化结果、关键路径手工验证记录、已知问题列表。这份报告是交付阶段 PR 描述的重要素材评审的人看报告就能知道这个变更验证到什么程度了。测试报告里我特别强调“已知问题列表”这一项。AI 编码难免有覆盖不到的地方与其假装完美不如把已知的局限写清楚。比如“本次未覆盖并发场景”“未处理网络异常重试”这些写出来评审的人心里有数后续也知道该补什么。6.3 Maestro 流程的维护成本控制UI 自动化最大的问题是维护成本。页面一改流程就挂。我的经验是只对最核心的路径做 UI 自动化不要贪多。登录、主流程、支付这三条路径覆盖住就能挡住大部分严重问题。其他边缘路径靠单元测试和手工验证。另外Maestro 流程里的元素定位尽量用文本或者稳定的 testID不要用坐标或者易变的层级选择器。用坐标的流程页面布局一调整就全废。7. 交付提交阶段把变更整理成一个能评审的 PR7.1 PR 描述不是复述代码而是交代上下文走到交付阶段代码已经写完、测试已经跑过剩下的就是提交 PR。很多人把 PR 描述写成代码变更的复述这是浪费。评审的人能看 diff不需要你复述。PR 描述真正要交代的是上下文这个变更对应哪个需求、做了什么取舍、验证到什么程度、有什么已知局限。我的 PR 描述模板固定包含需求链接、变更概述、关键取舍、测试情况、已知问题、评审重点。其中“评审重点”这一项特别有用它告诉评审的人应该重点看哪里。比如“本次重点看鉴权逻辑其他是样板代码”评审的人就能把精力集中在关键部分。7.2 变更聚焦一个 PR 只做一件事我踩过最大的坑之一是一个 PR 里混了多个不相关的变更。原因是编码阶段并行任务做完后合并的时候图省事把几个任务的改动一起提交了。结果评审的人看得很痛苦回滚的时候也没法单独回滚某一个功能。后来我强制要求一个 PR 只对应一个需求或者一个任务。并行任务的改动分别提交 PR分别评审。这样每个 PR 都聚焦评审快回滚也干净。代价是 PR 数量变多但换来的是可维护性值得。7.3 从流水线产物自动生成 PR 描述PR 描述里的很多内容其实在流水线前面的阶段已经产出了。需求链接来自澄清文档关键取舍来自方案文档测试情况来自测试报告。我写了个小脚本把这些产物拼成 PR 描述的初稿人工再润色一下。这样既保证了信息完整又省了重复劳动。# 伪代码示意从流水线产物生成 PR 描述初稿 cat 01-clarification.md | extract_section 目标 pr-draft.md cat 02-design.md | extract_section 关键取舍 pr-draft.md cat 05-test-report.md pr-draft.md这个脚本不复杂但效果很好。它让 PR 描述的质量变得稳定不会因为赶时间就写得潦草。8. 让流水线真正可复用的几个关键经验8.1 阶段产物格式要稳定但内容可以灵活整条流水线能复用靠的是阶段之间的接口稳定。只要每个阶段的输入输出格式不变中间用什么工具、谁来执行都可以换。我一开始担心格式定死了会限制灵活性实际用下来发现格式稳定反而让内容更聚焦因为你知道要填哪些字段就不会漫无目的地写。8.2 人工介入点要少而关键流水线不是全自动就好。人工介入点太多效率低太少质量失控。我的经验是保留三个关键介入点澄清文档确认、方案评审、PR 评审。这三个点都是决策点必须人来做。其他环节尽量自动化。8.3 工具是配角流程是主角Maestro、CodeBuddy Code、git worktree 这些工具都很重要但它们是可以替换的。今天用这个编码助手明天换一个只要流程不变流水线照样跑。我见过太多人把精力花在选工具上却忽略了流程设计。工具解决的是“怎么做快”流程解决的是“怎么做对”。对永远比快重要。8.4 从一个小需求开始跑通全流程如果你打算在自己的项目里落地这套流水线我的建议是不要一上来就全面铺开。挑一个中等复杂度的需求从澄清到 PR 完整走一遍把每个阶段的产物格式打磨到顺手再考虑推广。我当初就是拿一个登录功能试的走完一遍之后发现了好几个格式设计上的问题改完之后再推广就顺多了。8.5 流水线本身也要迭代这套流水线不是一次设计好就固定不变的。我在用的过程中改了很多次比如澄清文档的字段从五个减到四个又加回五个任务拆解的粒度标准调整过三次。每次遇到问题先想是流程的问题还是执行的问题如果是流程的问题就改流程。流水线是活的不是死的。最后分享一个我自己的习惯每个需求走完流水线之后我会花五分钟回顾一下哪个阶段最卡、哪个产物最没用、哪个约束最有效。这些回顾积累下来就是流水线持续优化的依据。工具会过时流程会演进但“把需求开发变成可复用流水线”这个思路我觉得会一直有用。