1. 从“随口一问”到工程化为什么需要一条需求开发流水线我做了十多年开发带过不少团队也见过太多人把 AI 当成一个“许愿池”——打开对话框敲一句“帮我写个登录功能”然后盯着屏幕等奇迹。结果呢生成的代码要么跑不起来要么缺胳膊少腿要么风格跟项目格格不入改起来比自己写还费劲。问题不在于 AI 不行而在于我们把一个需要上下文的工程问题简化成了一次随口的提问。这个项目的核心就是把“用 AI 写代码”这件事从一次性的、随机的对话变成一条可复用、可编排、可沉淀的需求开发流水线。你可以把它理解成一条工厂里的装配线需求进来经过拆解、设计、编码、审查、测试几个工位每个工位都有明确的输入输出和质量标准AI 只是这条线上的“工人”之一而不是那个拍脑袋的“大师”。它解决的核心痛点有三个。第一是上下文丢失每次对话都从零开始AI 不知道你的项目结构、技术栈、命名习惯第二是质量不可控生成的东西没有经过系统性的校验全靠人肉 review第三是经验无法沉淀这次调好的提示词下次换个需求又得重来。流水线的思路就是把这些隐性的、一次性的东西变成显性的、可复用的资产。适合谁来参考如果你是一个人扛一个项目的独立开发者这套东西能帮你把 AI 的产出稳定在“可用”水平如果你是团队里的技术负责人它能帮你把 AI 协作的规范固化下来让不同的人用 AI 产出的代码质量趋于一致哪怕你只是刚接触 AI 编程的新手理解这条流水线的设计思路也能让你少走很多“随口一问然后被坑”的弯路。2. 流水线的整体设计与编排思路2.1 为什么是“流水线”而不是“超级提示词”很多人第一反应是我写一个超长的、包罗万象的提示词不就行了把所有要求都塞进去让 AI 一次搞定。我试过结论是——不行。原因很简单单个提示词的注意力是有限的。当你把需求分析、架构设计、编码规范、测试要求全塞进一段话里AI 会顾此失彼往往把最显眼的编码部分做了把隐性的规范约束丢了。流水线的本质是分而治之。把一个大任务拆成若干个边界清晰的小任务每个小任务只关注一件事用一个专门的提示词模板去驱动。这样做的好处是每个环节的产出都可以被单独检查、单独优化。哪个环节出问题就改哪个环节的模板不会牵一发而动全身。另一个关键考量是可复用性。流水线里的每个“工位”本质上是一个函数输入是上一环节的产出输出是这一环节的结果中间的逻辑由提示词模板和少量参数决定。需求变了流水线的结构不变只是输入变了。这就是它比“随口一问”强的地方——你积累的是流程而不是一次性的对话记录。2.2 流水线的五个核心工位我把这条流水线拆成五个工位每个工位对应需求开发的一个阶段。这个划分不是拍脑袋定的而是对应了真实开发中从“想法”到“可交付代码”的自然流程。工位名称输入输出核心职责1需求澄清一句话需求结构化需求说明把模糊需求变成明确的验收标准2方案设计结构化需求技术方案文档确定技术选型、模块划分、接口定义3代码生成技术方案初版代码按规范产出可运行的代码骨架4代码审查初版代码审查报告修订代码检查规范、边界、安全隐患5测试补全修订代码测试用例验证结果覆盖核心路径和边界情况这五个工位串起来就形成了一条从需求到可交付代码的完整链路。注意这不是说每个需求都必须走完五个工位——小改动可以跳过方案设计直接进代码生成。流水线的价值在于结构清晰、按需裁剪而不是死板地走流程。2.3 编排工具的选择为什么用 Maestro 这类编排思路说到“流水线编排”很多人会想到各种工作流引擎。我这里说的 Maestro不是指某一个具体的商业产品而是指用编排的思路来管理 AI 协作这一类做法。核心思想是把每个工位定义成一个可调用的节点节点之间有明确的依赖关系和数据传递整个流程可以被描述成一份配置文件。为什么不用简单的脚本串起来因为脚本是“硬编码”的改一个环节要动代码。而编排配置是“声明式”的你只需要描述“工位 A 的输出给工位 B”具体怎么执行由编排层负责。这样一来调整流程顺序、增加一个审查环节、替换某个工位的提示词模板都只需要改配置不用改逻辑。我实际用下来编排层至少要提供三个能力节点定义每个工位干什么、数据流转上一个节点的输出怎么传给下一个、条件分支比如审查不通过就回到代码生成。有了这三点一条流水线就能跑起来了。3. 核心工位的提示词设计与实操要点3.1 需求澄清工位把“帮我写个功能”变成可验收的清单这是整条流水线里最容易被忽视、但最重要的一环。大部分人跳过这一步直接让 AI 写代码结果就是 AI 按自己的理解写了一个“看起来像”的东西但跟你想要的差十万八千里。需求澄清工位的提示词模板核心是逼着 AI 把模糊需求拆成明确的、可验证的条目。我常用的模板结构是这样的你是一名需求分析师。请把下面这个需求拆解成结构化的需求说明。 原始需求{user_input} 请按以下格式输出 1. 功能目标一句话说明这个功能要解决什么问题 2. 输入这个功能接收什么数据格式是什么 3. 输出这个功能产出什么结果格式是什么 4. 边界条件列出至少 5 个需要处理的边界情况 5. 验收标准列出至少 3 条可验证的验收条件 6. 不做什么明确列出本次不涉及的范围 要求不要写任何代码只做需求分析。如果原始需求有歧义列出你的假设。这个模板的关键在于最后两条——“验收标准”和“不做什么”。验收标准让后续的代码生成有明确的靶子“不做什么”则防止 AI 过度设计把范围无限扩大。我踩过的坑就是不写“不做什么”AI 会自作主张加上一堆你没要的功能代码量翻倍review 成本也翻倍。注意需求澄清的输出一定要人工过一遍。AI 列出的假设有些是合理的有些是它自己脑补的。你花两分钟确认一下能省后面两小时的返工。3.2 方案设计工位先定接口再写实现需求澄清完进入方案设计。这个工位的目标是产出一份技术方案文档核心是确定三件事技术选型、模块划分、接口定义。为什么接口定义要放在写代码之前因为接口是模块之间的“契约”。接口定好了每个模块内部怎么实现可以独立进行甚至可以并行让 AI 生成不同模块的代码。如果接口没定就开写最后拼起来的时候大概率对不上。方案设计工位的提示词模板你是一名资深架构师。基于下面的需求说明产出一份技术方案。 需求说明{requirement_output} 项目技术栈{tech_stack} 项目现有结构{project_structure} 请输出 1. 技术选型用到的库/框架说明为什么选它 2. 模块划分拆成哪几个模块每个模块的职责 3. 接口定义每个模块对外暴露的函数/类包含参数和返回值类型 4. 数据流数据在各个模块之间怎么流转 5. 风险点实现过程中可能遇到的坑 要求接口定义要具体到参数名和类型。不要写实现代码。这里有个实操心得把项目现有结构喂给 AI。很多人不传这个AI 就按自己的想象设计目录结构结果跟你项目里现有的组织方式完全不搭。我一般会把项目的目录树、关键文件的路径、以及一两个现有模块的代码片段作为上下文传进去这样 AI 设计的方案才能“长在”你的项目里而不是飘在空中。3.3 代码生成工位规范约束比功能描述更重要到了代码生成这一步很多人会把需求描述得特别详细却忘了告诉 AI代码要写成什么样。结果功能是对的但命名风格、错误处理方式、日志格式跟项目里其他代码格格不入。我的做法是在代码生成工位的提示词里规范约束占的篇幅比功能描述还大。模板大概长这样你是一名高级开发工程师。基于下面的技术方案生成代码。 技术方案{design_output} 代码规范 - 命名变量用 camelCase常量用 UPPER_SNAKE_CASE类名用 PascalCase - 错误处理所有外部调用必须有 try-catch错误要记录日志并向上抛出 - 日志使用项目统一的 logger格式为 [模块名] 动作 - 详情 - 注释每个导出函数必须有 JSDoc 注释说明参数和返回值 - 禁止不要用 any 类型不要写 console.log不要硬编码配置 参考代码风格 {existing_code_sample} 要求只生成方案中定义的接口对应的实现不要额外增加功能。把“参考代码风格”这一段加上效果提升非常明显。AI 会模仿你给的样例的写法产出的代码读起来就像项目里原有的代码。这比你在提示词里用文字描述“请保持风格一致”有效得多——给例子永远比给描述管用。3.4 代码审查工位让 AI 挑自己的毛病代码生成完不要直接合并。加一个审查工位让 AI 以“审查者”的身份重新看一遍代码。这里的关键是换一个提示词角色不要让同一个角色既写又审否则它会倾向于认为自己写的是对的。审查工位的提示词模板你是一名严格的代码审查员。请审查下面的代码找出问题。 代码{code_output} 需求说明{requirement_output} 请从以下维度审查 1. 功能正确性是否满足需求说明中的每一条验收标准 2. 边界处理需求中列出的边界条件是否都处理了 3. 错误处理异常路径是否覆盖错误信息是否清晰 4. 安全隐患是否有注入、越界、空指针等风险 5. 规范符合是否符合给定的代码规范 输出格式 - 严重问题必须修复... - 建议改进可选... - 修订后的代码... 要求每个问题都要指出具体行号和原因。不要放过任何边界情况。实测下来这个工位能抓出不少真问题。尤其是边界条件AI 写代码时经常只处理“正常路径”审查工位能逼它把异常路径补上。我印象比较深的一次审查工位发现生成的代码在输入为空数组时会崩溃而需求里明确写了要处理空输入——这种问题如果靠人肉 review很容易漏掉。3.5 测试补全工位把验收标准变成测试用例最后一个工位是测试补全。需求澄清阶段列的验收标准在这里正好派上用场——每一条验收标准对应至少一个测试用例。测试工位的提示词模板你是一名测试工程师。基于下面的代码和需求生成测试用例。 代码{revised_code} 需求说明{requirement_output} 请生成 1. 单元测试覆盖每个导出函数包含正常路径和边界路径 2. 测试数据每个用例的输入数据和预期输出 3. 测试框架使用项目现有的测试框架 {test_framework} 要求每条验收标准至少对应一个测试用例。边界条件必须单独写用例。这里有个技巧让 AI 先列测试用例清单确认后再生成代码。因为测试用例的设计比测试代码的编写更重要如果用例设计得不对代码写得再漂亮也没用。我一般会让 AI 先输出一个用例表格我扫一眼确认覆盖度再让它生成具体的测试代码。4. 流水线的落地实现与参数配置4.1 用配置文件描述整条流水线前面说了流水线要用编排的思路来管理。具体落地时我会用一份 YAML 配置文件来描述整条流水线。这样做的好处是流程一目了然改起来也方便。pipeline: name: feature-development stages: - id: clarify name: 需求澄清 prompt: prompts/clarify.md input: ${user_input} output: requirement - id: design name: 方案设计 prompt: prompts/design.md input: ${requirement} context: - ${tech_stack} - ${project_structure} output: design - id: generate name: 代码生成 prompt: prompts/generate.md input: ${design} context: - ${code_style_sample} output: code - id: review name: 代码审查 prompt: prompts/review.md input: ${code} context: - ${requirement} output: revised_code on_failure: generate - id: test name: 测试补全 prompt: prompts/test.md input: ${revised_code} context: - ${requirement} - ${test_framework} output: tests这份配置里每个 stage 定义了四样东西用什么提示词模板、输入是什么、需要哪些上下文、输出叫什么。on_failure: generate这一行是条件分支意思是审查不通过就回到代码生成工位重来。这个回退机制很重要它让流水线有了自我修正的能力。4.2 上下文注入让 AI 知道“项目长什么样”流水线能不能产出可用的代码很大程度上取决于上下文注入做得好不好。我一般会注入三类上下文第一类是项目结构包括目录树和关键文件路径。这个用一条命令就能生成find . -type f -name *.ts -not -path ./node_modules/* | head -50把输出喂给 AI它就知道你的项目里有哪些模块、代码放在哪。第二类是代码风格样例。从项目里挑一个写得最规范的模块把它的代码作为样例传进去。AI 会模仿这个样例的命名、注释、错误处理方式。第三类是技术栈信息包括依赖版本、构建工具、测试框架。这些信息决定了 AI 生成的代码能不能直接跑起来。比如你用的是 TypeScript 5.0AI 生成的代码用了 5.0 才有的语法那就没问题如果它用了旧语法虽然也能跑但不够地道。提示上下文不是越多越好。我试过把整个项目的代码都塞进去结果 AI 反而抓不住重点。一般控制在 2000 到 4000 token 之间比较合适挑最相关的部分。4.3 参数调优温度、模型、重试策略流水线跑起来之后还有几个参数需要调。这些参数没有标准答案得根据你的实际情况试。温度temperature需求澄清和方案设计阶段我一般用 0.3 到 0.5让 AI 有一定的发挥空间能提出一些我没想到的点代码生成和审查阶段用 0.1 到 0.2要的是稳定和准确不要它“发挥创意”。模型选择不同工位可以用不同的模型。需求澄清和方案设计用推理能力强的模型代码生成用代码能力强的模型审查用综合能力强的模型。如果预算有限至少保证审查工位用最好的模型因为审查的质量直接决定了最终产出的质量。重试策略审查不通过时不要简单地重新生成一遍那样大概率还是同样的错误。我的做法是把审查报告作为额外上下文一起传给代码生成工位让它“带着问题改”。这样重试的成功率会高很多。参数需求澄清方案设计代码生成代码审查测试补全温度0.40.30.10.20.2模型偏好推理强推理强代码强综合强代码强最大重试112-15. 常见问题与排查技巧实录5.1 生成代码跑不起来先查上下文再查依赖这是最常见的问题。AI 生成的代码看起来没问题一跑就报错。排查顺序是这样的先看上下文是否完整。如果没传项目结构AI 可能 import 了一个不存在的路径如果没传依赖版本AI 可能用了一个你项目里没装的库。我遇到过一次AI 生成的代码用了 lodash 的某个方法但项目里根本没装 lodash一跑就报模块找不到。再看接口是否对齐。方案设计阶段定义的接口和代码生成阶段实际产出的接口有时候会对不上。比如方案里写的是getUser(id: string)代码里写成了getUser(userId: number)。这种问题审查工位一般能抓到但如果跳过了审查就得自己查。最后看环境差异。AI 生成的代码可能在它的“想象环境”里能跑但你的实际环境有差异。比如 Node 版本不同、操作系统不同、环境变量没配。这类问题只能靠实际运行来发现。5.2 审查工位“放水”如何让 AI 认真挑毛病有时候审查工位会“放水”明明有问题却说没问题。我分析下来原因有两个一是审查提示词不够严格二是审查者和生成者用了同一个模型存在“自我认同”倾向。解决办法有三个。第一在审查提示词里明确要求“必须找出至少 3 个问题”。这个约束会逼着 AI 认真找而不是敷衍了事。第二换一个模型来审查。生成用 A 模型审查用 B 模型B 模型没有“自己写的代码”这个心理包袱挑毛病会更狠。第三给审查工位提供“对照物”把需求说明和代码规范一起传进去让 AI 逐条对照检查而不是泛泛地看。5.3 流水线跑得太慢哪些工位可以并行五个工位串行跑确实慢。实测下来一个中等复杂度的需求跑完整条流水线大概要 3 到 5 分钟。如果需求多这个时间就很可观了。能优化的地方有几个。测试补全可以和代码审查并行因为测试用例的设计主要依赖需求说明不依赖审查结果。多个独立模块的代码生成可以并行如果方案设计阶段把模块拆得足够清晰每个模块的代码生成互不依赖就可以同时跑。还有一个优化点是缓存。需求澄清和方案设计的产出如果需求没变就不用重新跑。我一般会把这两个阶段的产出存下来下次同样的需求直接复用。5.4 常见问题速查表问题现象可能原因排查方向解决办法代码跑不起来上下文缺失检查是否传了项目结构和依赖补全上下文重新生成接口对不上方案与实现脱节对比方案文档和实际代码以方案为准修正代码审查放水提示词不严/同模型检查审查提示词约束加“至少找3个问题”换模型流水线太慢串行执行分析工位依赖关系并行化独立工位加缓存风格不一致缺代码样例检查是否传了风格样例补上样例代码重新生成过度设计需求范围不清检查“不做什么”是否明确在需求澄清阶段明确边界5.5 几个我踩过的坑第一个坑是提示词模板写得太死。一开始我把模板写得很具体结果换个需求就不适用了。后来改成“结构化但留白”模板只规定输出格式具体内容让 AI 根据输入填充通用性好了很多。第二个坑是忽略了人工确认环节。我一开始想全自动跑完结果发现需求澄清阶段的假设如果不对后面全白跑。后来在需求澄清和方案设计之后各加了一个人工确认点虽然多花两分钟但整体效率反而更高。第三个坑是上下文塞太多。前面提过塞太多反而抓不住重点。现在的做法是每个工位只传它真正需要的上下文不多传也不少传。6. 流水线的扩展与个人实践体会这条流水线跑顺之后我发现它能扩展的地方还有很多。比如在代码生成之前加一个“依赖检查”工位自动检查方案里用到的库项目里有没有在测试补全之后加一个“覆盖率检查”工位确保核心路径都被覆盖到。这些扩展不需要改动流水线的主体结构只是在配置里加几个节点的事。我还把这条流水线用在了非编码场景。比如写技术方案文档把“需求澄清”换成“大纲梳理”“代码生成”换成“章节撰写”“代码审查”换成“逻辑校验”整条流水线的骨架完全适用。这说明流水线的价值不在于具体的工位内容而在于把复杂任务拆解成可管理步骤的这个思路。我个人在实际操作中的体会是这条流水线最大的价值不是“让 AI 写代码更快”而是“让 AI 写代码更稳”。快是次要的稳才是关键。一条稳定的流水线产出质量是可预期的不会今天生成得很好明天生成得一塌糊涂。这种可预期性才是工程化的核心。最后分享一个小技巧把每次流水线的运行记录存下来。包括输入、每个工位的输出、人工修改的地方。攒够一定数量之后你会发现一些规律——比如某类需求总是在审查阶段出问题某个提示词模板总是需要人工调整。这些规律就是优化流水线的依据。我现在的提示词模板基本都是根据这些运行记录迭代出来的比一开始拍脑袋写的版本好用太多了。
1. 从“随口一问”到工程化为什么需要一条需求开发流水线我做了十多年开发带过不少团队也见过太多人把 AI 当成一个“许愿池”——打开对话框敲一句“帮我写个登录功能”然后盯着屏幕等奇迹。结果呢生成的代码要么跑不起来要么缺胳膊少腿要么风格跟项目格格不入改起来比自己写还费劲。问题不在于 AI 不行而在于我们把一个需要上下文的工程问题简化成了一次随口的提问。这个项目的核心就是把“用 AI 写代码”这件事从一次性的、随机的对话变成一条可复用、可编排、可沉淀的需求开发流水线。你可以把它理解成一条工厂里的装配线需求进来经过拆解、设计、编码、审查、测试几个工位每个工位都有明确的输入输出和质量标准AI 只是这条线上的“工人”之一而不是那个拍脑袋的“大师”。它解决的核心痛点有三个。第一是上下文丢失每次对话都从零开始AI 不知道你的项目结构、技术栈、命名习惯第二是质量不可控生成的东西没有经过系统性的校验全靠人肉 review第三是经验无法沉淀这次调好的提示词下次换个需求又得重来。流水线的思路就是把这些隐性的、一次性的东西变成显性的、可复用的资产。适合谁来参考如果你是一个人扛一个项目的独立开发者这套东西能帮你把 AI 的产出稳定在“可用”水平如果你是团队里的技术负责人它能帮你把 AI 协作的规范固化下来让不同的人用 AI 产出的代码质量趋于一致哪怕你只是刚接触 AI 编程的新手理解这条流水线的设计思路也能让你少走很多“随口一问然后被坑”的弯路。2. 流水线的整体设计与编排思路2.1 为什么是“流水线”而不是“超级提示词”很多人第一反应是我写一个超长的、包罗万象的提示词不就行了把所有要求都塞进去让 AI 一次搞定。我试过结论是——不行。原因很简单单个提示词的注意力是有限的。当你把需求分析、架构设计、编码规范、测试要求全塞进一段话里AI 会顾此失彼往往把最显眼的编码部分做了把隐性的规范约束丢了。流水线的本质是分而治之。把一个大任务拆成若干个边界清晰的小任务每个小任务只关注一件事用一个专门的提示词模板去驱动。这样做的好处是每个环节的产出都可以被单独检查、单独优化。哪个环节出问题就改哪个环节的模板不会牵一发而动全身。另一个关键考量是可复用性。流水线里的每个“工位”本质上是一个函数输入是上一环节的产出输出是这一环节的结果中间的逻辑由提示词模板和少量参数决定。需求变了流水线的结构不变只是输入变了。这就是它比“随口一问”强的地方——你积累的是流程而不是一次性的对话记录。2.2 流水线的五个核心工位我把这条流水线拆成五个工位每个工位对应需求开发的一个阶段。这个划分不是拍脑袋定的而是对应了真实开发中从“想法”到“可交付代码”的自然流程。工位名称输入输出核心职责1需求澄清一句话需求结构化需求说明把模糊需求变成明确的验收标准2方案设计结构化需求技术方案文档确定技术选型、模块划分、接口定义3代码生成技术方案初版代码按规范产出可运行的代码骨架4代码审查初版代码审查报告修订代码检查规范、边界、安全隐患5测试补全修订代码测试用例验证结果覆盖核心路径和边界情况这五个工位串起来就形成了一条从需求到可交付代码的完整链路。注意这不是说每个需求都必须走完五个工位——小改动可以跳过方案设计直接进代码生成。流水线的价值在于结构清晰、按需裁剪而不是死板地走流程。2.3 编排工具的选择为什么用 Maestro 这类编排思路说到“流水线编排”很多人会想到各种工作流引擎。我这里说的 Maestro不是指某一个具体的商业产品而是指用编排的思路来管理 AI 协作这一类做法。核心思想是把每个工位定义成一个可调用的节点节点之间有明确的依赖关系和数据传递整个流程可以被描述成一份配置文件。为什么不用简单的脚本串起来因为脚本是“硬编码”的改一个环节要动代码。而编排配置是“声明式”的你只需要描述“工位 A 的输出给工位 B”具体怎么执行由编排层负责。这样一来调整流程顺序、增加一个审查环节、替换某个工位的提示词模板都只需要改配置不用改逻辑。我实际用下来编排层至少要提供三个能力节点定义每个工位干什么、数据流转上一个节点的输出怎么传给下一个、条件分支比如审查不通过就回到代码生成。有了这三点一条流水线就能跑起来了。3. 核心工位的提示词设计与实操要点3.1 需求澄清工位把“帮我写个功能”变成可验收的清单这是整条流水线里最容易被忽视、但最重要的一环。大部分人跳过这一步直接让 AI 写代码结果就是 AI 按自己的理解写了一个“看起来像”的东西但跟你想要的差十万八千里。需求澄清工位的提示词模板核心是逼着 AI 把模糊需求拆成明确的、可验证的条目。我常用的模板结构是这样的你是一名需求分析师。请把下面这个需求拆解成结构化的需求说明。 原始需求{user_input} 请按以下格式输出 1. 功能目标一句话说明这个功能要解决什么问题 2. 输入这个功能接收什么数据格式是什么 3. 输出这个功能产出什么结果格式是什么 4. 边界条件列出至少 5 个需要处理的边界情况 5. 验收标准列出至少 3 条可验证的验收条件 6. 不做什么明确列出本次不涉及的范围 要求不要写任何代码只做需求分析。如果原始需求有歧义列出你的假设。这个模板的关键在于最后两条——“验收标准”和“不做什么”。验收标准让后续的代码生成有明确的靶子“不做什么”则防止 AI 过度设计把范围无限扩大。我踩过的坑就是不写“不做什么”AI 会自作主张加上一堆你没要的功能代码量翻倍review 成本也翻倍。注意需求澄清的输出一定要人工过一遍。AI 列出的假设有些是合理的有些是它自己脑补的。你花两分钟确认一下能省后面两小时的返工。3.2 方案设计工位先定接口再写实现需求澄清完进入方案设计。这个工位的目标是产出一份技术方案文档核心是确定三件事技术选型、模块划分、接口定义。为什么接口定义要放在写代码之前因为接口是模块之间的“契约”。接口定好了每个模块内部怎么实现可以独立进行甚至可以并行让 AI 生成不同模块的代码。如果接口没定就开写最后拼起来的时候大概率对不上。方案设计工位的提示词模板你是一名资深架构师。基于下面的需求说明产出一份技术方案。 需求说明{requirement_output} 项目技术栈{tech_stack} 项目现有结构{project_structure} 请输出 1. 技术选型用到的库/框架说明为什么选它 2. 模块划分拆成哪几个模块每个模块的职责 3. 接口定义每个模块对外暴露的函数/类包含参数和返回值类型 4. 数据流数据在各个模块之间怎么流转 5. 风险点实现过程中可能遇到的坑 要求接口定义要具体到参数名和类型。不要写实现代码。这里有个实操心得把项目现有结构喂给 AI。很多人不传这个AI 就按自己的想象设计目录结构结果跟你项目里现有的组织方式完全不搭。我一般会把项目的目录树、关键文件的路径、以及一两个现有模块的代码片段作为上下文传进去这样 AI 设计的方案才能“长在”你的项目里而不是飘在空中。3.3 代码生成工位规范约束比功能描述更重要到了代码生成这一步很多人会把需求描述得特别详细却忘了告诉 AI代码要写成什么样。结果功能是对的但命名风格、错误处理方式、日志格式跟项目里其他代码格格不入。我的做法是在代码生成工位的提示词里规范约束占的篇幅比功能描述还大。模板大概长这样你是一名高级开发工程师。基于下面的技术方案生成代码。 技术方案{design_output} 代码规范 - 命名变量用 camelCase常量用 UPPER_SNAKE_CASE类名用 PascalCase - 错误处理所有外部调用必须有 try-catch错误要记录日志并向上抛出 - 日志使用项目统一的 logger格式为 [模块名] 动作 - 详情 - 注释每个导出函数必须有 JSDoc 注释说明参数和返回值 - 禁止不要用 any 类型不要写 console.log不要硬编码配置 参考代码风格 {existing_code_sample} 要求只生成方案中定义的接口对应的实现不要额外增加功能。把“参考代码风格”这一段加上效果提升非常明显。AI 会模仿你给的样例的写法产出的代码读起来就像项目里原有的代码。这比你在提示词里用文字描述“请保持风格一致”有效得多——给例子永远比给描述管用。3.4 代码审查工位让 AI 挑自己的毛病代码生成完不要直接合并。加一个审查工位让 AI 以“审查者”的身份重新看一遍代码。这里的关键是换一个提示词角色不要让同一个角色既写又审否则它会倾向于认为自己写的是对的。审查工位的提示词模板你是一名严格的代码审查员。请审查下面的代码找出问题。 代码{code_output} 需求说明{requirement_output} 请从以下维度审查 1. 功能正确性是否满足需求说明中的每一条验收标准 2. 边界处理需求中列出的边界条件是否都处理了 3. 错误处理异常路径是否覆盖错误信息是否清晰 4. 安全隐患是否有注入、越界、空指针等风险 5. 规范符合是否符合给定的代码规范 输出格式 - 严重问题必须修复... - 建议改进可选... - 修订后的代码... 要求每个问题都要指出具体行号和原因。不要放过任何边界情况。实测下来这个工位能抓出不少真问题。尤其是边界条件AI 写代码时经常只处理“正常路径”审查工位能逼它把异常路径补上。我印象比较深的一次审查工位发现生成的代码在输入为空数组时会崩溃而需求里明确写了要处理空输入——这种问题如果靠人肉 review很容易漏掉。3.5 测试补全工位把验收标准变成测试用例最后一个工位是测试补全。需求澄清阶段列的验收标准在这里正好派上用场——每一条验收标准对应至少一个测试用例。测试工位的提示词模板你是一名测试工程师。基于下面的代码和需求生成测试用例。 代码{revised_code} 需求说明{requirement_output} 请生成 1. 单元测试覆盖每个导出函数包含正常路径和边界路径 2. 测试数据每个用例的输入数据和预期输出 3. 测试框架使用项目现有的测试框架 {test_framework} 要求每条验收标准至少对应一个测试用例。边界条件必须单独写用例。这里有个技巧让 AI 先列测试用例清单确认后再生成代码。因为测试用例的设计比测试代码的编写更重要如果用例设计得不对代码写得再漂亮也没用。我一般会让 AI 先输出一个用例表格我扫一眼确认覆盖度再让它生成具体的测试代码。4. 流水线的落地实现与参数配置4.1 用配置文件描述整条流水线前面说了流水线要用编排的思路来管理。具体落地时我会用一份 YAML 配置文件来描述整条流水线。这样做的好处是流程一目了然改起来也方便。pipeline: name: feature-development stages: - id: clarify name: 需求澄清 prompt: prompts/clarify.md input: ${user_input} output: requirement - id: design name: 方案设计 prompt: prompts/design.md input: ${requirement} context: - ${tech_stack} - ${project_structure} output: design - id: generate name: 代码生成 prompt: prompts/generate.md input: ${design} context: - ${code_style_sample} output: code - id: review name: 代码审查 prompt: prompts/review.md input: ${code} context: - ${requirement} output: revised_code on_failure: generate - id: test name: 测试补全 prompt: prompts/test.md input: ${revised_code} context: - ${requirement} - ${test_framework} output: tests这份配置里每个 stage 定义了四样东西用什么提示词模板、输入是什么、需要哪些上下文、输出叫什么。on_failure: generate这一行是条件分支意思是审查不通过就回到代码生成工位重来。这个回退机制很重要它让流水线有了自我修正的能力。4.2 上下文注入让 AI 知道“项目长什么样”流水线能不能产出可用的代码很大程度上取决于上下文注入做得好不好。我一般会注入三类上下文第一类是项目结构包括目录树和关键文件路径。这个用一条命令就能生成find . -type f -name *.ts -not -path ./node_modules/* | head -50把输出喂给 AI它就知道你的项目里有哪些模块、代码放在哪。第二类是代码风格样例。从项目里挑一个写得最规范的模块把它的代码作为样例传进去。AI 会模仿这个样例的命名、注释、错误处理方式。第三类是技术栈信息包括依赖版本、构建工具、测试框架。这些信息决定了 AI 生成的代码能不能直接跑起来。比如你用的是 TypeScript 5.0AI 生成的代码用了 5.0 才有的语法那就没问题如果它用了旧语法虽然也能跑但不够地道。提示上下文不是越多越好。我试过把整个项目的代码都塞进去结果 AI 反而抓不住重点。一般控制在 2000 到 4000 token 之间比较合适挑最相关的部分。4.3 参数调优温度、模型、重试策略流水线跑起来之后还有几个参数需要调。这些参数没有标准答案得根据你的实际情况试。温度temperature需求澄清和方案设计阶段我一般用 0.3 到 0.5让 AI 有一定的发挥空间能提出一些我没想到的点代码生成和审查阶段用 0.1 到 0.2要的是稳定和准确不要它“发挥创意”。模型选择不同工位可以用不同的模型。需求澄清和方案设计用推理能力强的模型代码生成用代码能力强的模型审查用综合能力强的模型。如果预算有限至少保证审查工位用最好的模型因为审查的质量直接决定了最终产出的质量。重试策略审查不通过时不要简单地重新生成一遍那样大概率还是同样的错误。我的做法是把审查报告作为额外上下文一起传给代码生成工位让它“带着问题改”。这样重试的成功率会高很多。参数需求澄清方案设计代码生成代码审查测试补全温度0.40.30.10.20.2模型偏好推理强推理强代码强综合强代码强最大重试112-15. 常见问题与排查技巧实录5.1 生成代码跑不起来先查上下文再查依赖这是最常见的问题。AI 生成的代码看起来没问题一跑就报错。排查顺序是这样的先看上下文是否完整。如果没传项目结构AI 可能 import 了一个不存在的路径如果没传依赖版本AI 可能用了一个你项目里没装的库。我遇到过一次AI 生成的代码用了 lodash 的某个方法但项目里根本没装 lodash一跑就报模块找不到。再看接口是否对齐。方案设计阶段定义的接口和代码生成阶段实际产出的接口有时候会对不上。比如方案里写的是getUser(id: string)代码里写成了getUser(userId: number)。这种问题审查工位一般能抓到但如果跳过了审查就得自己查。最后看环境差异。AI 生成的代码可能在它的“想象环境”里能跑但你的实际环境有差异。比如 Node 版本不同、操作系统不同、环境变量没配。这类问题只能靠实际运行来发现。5.2 审查工位“放水”如何让 AI 认真挑毛病有时候审查工位会“放水”明明有问题却说没问题。我分析下来原因有两个一是审查提示词不够严格二是审查者和生成者用了同一个模型存在“自我认同”倾向。解决办法有三个。第一在审查提示词里明确要求“必须找出至少 3 个问题”。这个约束会逼着 AI 认真找而不是敷衍了事。第二换一个模型来审查。生成用 A 模型审查用 B 模型B 模型没有“自己写的代码”这个心理包袱挑毛病会更狠。第三给审查工位提供“对照物”把需求说明和代码规范一起传进去让 AI 逐条对照检查而不是泛泛地看。5.3 流水线跑得太慢哪些工位可以并行五个工位串行跑确实慢。实测下来一个中等复杂度的需求跑完整条流水线大概要 3 到 5 分钟。如果需求多这个时间就很可观了。能优化的地方有几个。测试补全可以和代码审查并行因为测试用例的设计主要依赖需求说明不依赖审查结果。多个独立模块的代码生成可以并行如果方案设计阶段把模块拆得足够清晰每个模块的代码生成互不依赖就可以同时跑。还有一个优化点是缓存。需求澄清和方案设计的产出如果需求没变就不用重新跑。我一般会把这两个阶段的产出存下来下次同样的需求直接复用。5.4 常见问题速查表问题现象可能原因排查方向解决办法代码跑不起来上下文缺失检查是否传了项目结构和依赖补全上下文重新生成接口对不上方案与实现脱节对比方案文档和实际代码以方案为准修正代码审查放水提示词不严/同模型检查审查提示词约束加“至少找3个问题”换模型流水线太慢串行执行分析工位依赖关系并行化独立工位加缓存风格不一致缺代码样例检查是否传了风格样例补上样例代码重新生成过度设计需求范围不清检查“不做什么”是否明确在需求澄清阶段明确边界5.5 几个我踩过的坑第一个坑是提示词模板写得太死。一开始我把模板写得很具体结果换个需求就不适用了。后来改成“结构化但留白”模板只规定输出格式具体内容让 AI 根据输入填充通用性好了很多。第二个坑是忽略了人工确认环节。我一开始想全自动跑完结果发现需求澄清阶段的假设如果不对后面全白跑。后来在需求澄清和方案设计之后各加了一个人工确认点虽然多花两分钟但整体效率反而更高。第三个坑是上下文塞太多。前面提过塞太多反而抓不住重点。现在的做法是每个工位只传它真正需要的上下文不多传也不少传。6. 流水线的扩展与个人实践体会这条流水线跑顺之后我发现它能扩展的地方还有很多。比如在代码生成之前加一个“依赖检查”工位自动检查方案里用到的库项目里有没有在测试补全之后加一个“覆盖率检查”工位确保核心路径都被覆盖到。这些扩展不需要改动流水线的主体结构只是在配置里加几个节点的事。我还把这条流水线用在了非编码场景。比如写技术方案文档把“需求澄清”换成“大纲梳理”“代码生成”换成“章节撰写”“代码审查”换成“逻辑校验”整条流水线的骨架完全适用。这说明流水线的价值不在于具体的工位内容而在于把复杂任务拆解成可管理步骤的这个思路。我个人在实际操作中的体会是这条流水线最大的价值不是“让 AI 写代码更快”而是“让 AI 写代码更稳”。快是次要的稳才是关键。一条稳定的流水线产出质量是可预期的不会今天生成得很好明天生成得一塌糊涂。这种可预期性才是工程化的核心。最后分享一个小技巧把每次流水线的运行记录存下来。包括输入、每个工位的输出、人工修改的地方。攒够一定数量之后你会发现一些规律——比如某类需求总是在审查阶段出问题某个提示词模板总是需要人工调整。这些规律就是优化流水线的依据。我现在的提示词模板基本都是根据这些运行记录迭代出来的比一开始拍脑袋写的版本好用太多了。
