1. 为什么“随口问 AI 写代码”总是高开低走我先说说自己踩过的一堆坑前两年我干活特别喜欢直接在对话框里甩给AI一句“帮我写一个用户列表页面带分页和搜索。”AI也确实能给出一段看着挺完整的代码但拿回来一接项目麻烦就开始了。数据库字段对不上、用户权限没考虑、分页参数跟前端约定的名字不一样改起来比从头写还痛苦。那时候我还觉得是AI不行后来才反应过来不是AI不行是我把一件需要完整流程保障的事压缩成了一句话。后来我在团队里观察了一圈发现大家用AI写代码基本是三种姿势第一种是“要什么直接问什么”拿到代码就跑跑不通再继续追问第二种是“把需求描述得很长很详细”希望AI一次性把边界条件都考虑到第三种是“让AI先给方案再写代码”但还是停留在单次对话里AI说着说着就忘了前面的假设。这三种姿势有个共同问题没有把“从需求到代码”的过程当做一个工程流程来管理而是当成一次灵光乍现的问答。你仔细想想就会发现写代码这件事真正决定质量的关键步骤往往不在“写”本身。需求到底想解决什么问题技术方案选什么接口怎么定哪些边界条件下不能做这些问题没定下来之前让AI直接生成代码等于让一个很熟练的施工队在没有图纸的情况下直接砌墙。墙大概率能砌起来但你不知道哪里会留个洞。还有一个特别容易被忽视的问题上下文会丢。单次对话里你问着问着AI就会把最开始的需求约束忘掉。你有过这种体验吧前五分钟还在说“这个接口只给内部管理后台用不需要做权限细分”十五分钟后AI已经给你写出一套复杂的多角色鉴权代码。真的不是AI笨是上下文窗口和注意力机制决定的它只能优先照顾最近的对话内容。我真正开始改变思路是在一次做内部运营工具的时候。那个项目逻辑不复杂但字段极多、状态流转极碎我在对话里反复追问了快二十轮最后AI生成的代码还是缺了三个状态分支。当时我就意识到问题出在我把整个“需求开发流程”压缩进了对话里却没有给这个流程划分边界、明确产物、建立检查点。从那时候起我开始尝试把需求开发的各个环节拆开分别交给不同的Prompt去处理再用一套工作流把它们串起来。这就是“流水线”这个思路的起点。现在团队里再有人跟我说“帮我写个接口”我会先问一句你要不要把这单子走一遍流水线流水线出来的东西不能说100%完美但至少每一道工序都有明确产出和检查点不会出现聊了半小时才发现前置条件没对齐的尴尬情况。2. 需求流转的五道天然工序别再把“脏活累活”丢给一次对话想把AI写代码这件事变得可控首先要接受一个现实“需求变成代码”不是一步而是五个明显不同的工序。我参考了软件工程里需求分析、概要设计、详细设计、编码、测试这一套经典流程把它压缩成更适合AI执行的五道工序每道工序都有明确输入和输出。2.1 工序一需求澄清与范围锁定这个工序的目标是把含糊的想法变成一句可以验证的“需求陈述”。输入可以很粗糙比如“想做一个优惠券功能”但输出必须包含目标用户是谁、解决什么问题、核心场景、非目标场景、验收标准。我通常用一个带模板的Prompt去引导AI做这件事。最核心的技巧是让AI按照“用户故事场景清单验收标准”的格式输出而不是给一个自然语言的描述。有了结构化的产出之后后面的工序才有抓手。2.2 工序二技术方案与接口约束需求澄清之后下一步不是立刻写代码而是确定技术方案。这一步要产出技术选型理由、数据模型设计、接口定义、关键流程时序、风险点。很多人会跳过这一步觉得AI写代码嘛直接把需求丢过去就行。但我的经验是如果没有接口约束AI生成的前端代码和后端代码大概率对不上。要么字段名不一致要么请求方法不对要么状态码处理逻辑不一样。这些对接问题会让整个功能看起来“能用但很别扭”调试成本极高。2.3 工序三任务拆解与依赖排序技术方案出来以后要把这个大目标拆成可以逐个验证的小任务。比如“实现优惠券功能”可以拆成“数据表设计”“创建API”“编写前端组件”“联调测试”等若干任务。这个工序是流水线里最容易被低估的一步。AI在接到一个太庞大的任务时会倾向于“一口气写完”但一口气写完往往意味着某几个部分被糊弄过去。拆解后每个任务都足够小AI能专注处理生成质量会明显提升。用现在流行的说法就是“把它交给Agent框架之前先让Agent自己把任务清单列出来不要代替它做计划”。2.4 工序四编码执行与自动校验到了真正写代码这一步流水线的优势才完全体现。每个任务单元会被单独提交给编码模型关键是上下文是经过筛选的不是把整个需求文档一股脑扔给编码器。比如写数据库相关的代码就只传数据模型定义和相关约束写接口层代码就只传接口定义和业务规则。这一步我还会加一个自动校验环节生成代码后让另一个Prompt扮演“代码审查者”检查是否存在越权、空指针、边界条件缺失等问题。这个审查Prompt不需要很强的推理能力但必须能执行一套规则列表。2.5 工序五回归验证与交付存档最后一关是回归验证。AI生成的代码跑通一次不算完需要检查是否影响了现有功能。我通常会准备一套冒烟测试用例让AI在验证环节里跑一遍再把结果整理进交付文档。这个工序最重要的价值是“存档”。每个需求走完流水线之后会产生一份包含需求文档、接口文档、代码差异、测试结果的记录。下次有类似需求时可以直接从这份记录里复用大部分内容这就是“可复用流水线”的含义——它不仅是工作流可复用连历史产出物都是可复用的元数据。3. 流水线施工从脚手架到可执行的Agent工作流我到底怎么搭的理论说完了聊点实际的。我最初想找现成的工具确实也有一些Workflow编排产品比如n8n开源版、Dify工作流以及各类Agent框架。但它们要么偏业务自动化要么偏对话机器人真正贴近“软件开发需求流水线”的还得自己拼。我的方案是用轻量级Agent框架 自定义阶段解析器搭建一个脚本驱动的流水线。3.1 为什么没有选“全家桶”方案市面上有不少Agent框架声称“你描述需求我自主完成开发”。试用过几个之后我发现它们的问题往往不是能力不够而是阶段边界太模糊。比如它可能自己决定先写数据库还是先写接口你无法精准干预。如果你需要做一个对公司合规很重要的强制检查这种框架有时候就直接跳过了。所以我宁可自己搭也不把流程控制权完全交给框架。我只需要框架帮我做三件事调用模型、保存上下文、按依赖顺序执行任务。剩下的流程逻辑自己写这样每个阶段做什么、什么时候停顿等人确认完全透明可控。3.2 基础骨架一张状态表 若干执行器流水线本质上是状态机。我用一个JSON文件保存当前流水线的状态每个阶段执行完后更新状态字段下一个阶段读取上一阶段产物。这样看起来土但非常稳出问题也好排查。下面这个伪代码是我流水线的核心骨架用Python风格表达pipeline { task_id: coupon_202501, stages: [ {name: clarify, status: done, output: requirement_spec.md}, {name: design, status: in_progress, output: tech_design.md}, {name: split, status: pending, output: task_list.json}, {name: implement, status: pending, output: code_changes/}, {name: review, status: pending, output: review_report.md} ], context: { tech_stack: python3.11 fastapi postgresql, model_plan: { clarify: fast-model, design: strong-model, implement: strong-model } } } def run_stage(stage, context): prompt load_prompt_template(stage) payload build_payload(stage, context) response call_model( modelcontext[model_plan][stage], messagesprompt payload ) validate_output(stage, response) save_artifact(stage, response) update_pipeline_status(stage, done)每个阶段执行前我会先读取前置产出的文件筛选出本阶段需要用到的部分拼接成新的Prompt上下文。这里有个很关键的动作不要把所有内容都塞给下一个阶段。比如实现代码的阶段只需要接口定义和业务规则就不需要把需求澄清时的用户访谈记录全带过去。3.3 上下文管理阶段间的“交接”比阶段本身更难我见过很多人搭流水线压根不管理上下文每个阶段都把自己记忆里的全部信息传给下一个阶段。这样做轻则浪费Token重则让AI在不同阶段之间产生自相矛盾的理解。我的做法是给每个阶段定义一个“上下文契约”指明它读取哪些上游文件忽略哪些。比如“设计阶段只读 requirement_spec.md 和 project_meta.json分阶段只读 tech_design.md实现阶段读取 task_list.json current_task.md”。每个文件还要在开头写上摘要这样模型能更快定位信息。另外一个不得不提的点是模型切换时上下文传递这件事会更麻烦。我用强模型做设计和实现阶段用便宜快速的模型做需求解析和格式转换阶段。便宜模型生成的中间结果强模型能读懂但反过来强模型产出的复杂设计摘要让便宜模型做决策时会吃力。所以我在阶段间加了一个“信息压缩器”专门把上一阶段的结构化产物压缩成摘要和要点列表。3.4 失败重试与人工闸门流水线不是全自动无人工的。我经验总结下来有三个地方必须设人工闸门需求澄清完成时、技术方案评审时、最终交付前。这三个节点上机器可以给出建议但最后拍板的一定是人。技术上我保留了两种恢复策略一种是阶段重跑比如实现阶段生成的代码没通过校验自动回到任务拆解阶段检查是不是任务粒度问题另一种是上下文重置当某阶段连续失败超过3次我会清空该阶段之前的上下文缓存重新从最近的成功产物开始避免AI在错误上下文里越陷越深。4. 每一道工序的Prompt本质上是一份“岗位说明书”流水线搭好之后我琢磨最多的问题是同一个模型为什么换一种Prompt写法产出质量差这么多后来我想明白一件事——在流水线里每个阶段面对的Prompt应该像一份岗位说明书而不是一段聊天开场白。岗位说明书得写清楚这个岗位的职责边界、输入材料、交付标准和不可触碰的红线。4.1 需求澄清工序的Prompt模板我用的需求澄清Prompt大概是这个结构你是软件需求分析师请基于以下原始描述输出结构化需求文档。 原始描述 {{ raw_input }} 输出格式要求 1. 目标用户与使用场景 2. 核心功能清单不超过10条 3. 非目标功能明确不做什么 4. 边界条件与异常场景 5. 验收标准必须是可测试的表述 约束 - 如果原始描述存在信息不足输出疑问清单不要自行脑补。 - 所有验收标准必须满足“可测试”条件禁止使用“一般来说”“尽量”等模糊词。这个Prompt的奇妙之处在于它逼着AI回答两个很多人忽略的问题“非目标功能”和“疑问清单”。非目标功能能有效防止过度设计而疑问清单则帮我们找出需求里的坑。有一次做内部报表功能AI在疑问清单里问了一句“数据量级超过1000万时的降级策略是什么”我们当时真没想过这个问题后来一评估发现确实需要做分页和汇总表需求方案直接改了一遍。4.2 任务拆解工序的Prompt依赖关系不能含糊需求文档出来之后进入任务拆解阶段。这个阶段的Prompt我做了一张很严格的模板你是技术项目经理请根据技术设计文档给出可执行的任务列表。 输出格式JSON [ { task_id: T1, name: 任务名称, depends_on: [上游任务id], entry_points: [涉及的核心文件或模块], acceptance_criteria: [任务完成的验证条件] } ] 要求 - 每个任务尽量控制在单次可完成的粒度估计代码量超过500行的任务必须拆分。 - 必须明确依赖关系没有依赖关系的任务可以并行。 - 验收标准必须是项目里可实际验证的禁止出现“代码优雅”“结构合理”这类无法自动验证的描述。为什么依赖关系必须明确因为流水线调度器要根据依赖关系决定是先做前端还是先做后端。如果任务拆解不清晰后面的实现阶段就会变成串行等待流水线跑一次要多花一倍时间。4.3 不同工序用不同模型省钱的科学不只是省钱我一开始图省事所有阶段都走同一个强模型跑了几个需求之后发现费用有点让人肉疼。后来看了下各模型的标价和效果调整成工序推荐模型类型原因需求澄清轻量快速模型主要是结构化整理不需要太强推理技术设计强推理模型涉及架构选型和接口设计一步错步步错任务拆解轻量快速模型只要遵循模板和依赖规则中等模型就够编码实现强推理模型生成复杂逻辑代码是核心技术环节代码审查轻量模型 规则校验脚本审查逻辑用脚本兜底模型只需做补充说明你可能会问代码审查那么关键的环节怎么用轻量模型我的答案很简单机器能跑规则的地方不要依赖模型的“感觉”。我会先把代码跑一遍已有的静态检查和测试用例只有在这些规则检查无法覆盖的地方比如权限逻辑是否正确、异常处理是否漏了场景才需要模型介入。轻量模型完全能胜任这个工作重点在于规则脚本把大范围问题过滤掉模型只需要聚焦小范围判断。5. 让流水线从“能跑”到“真好用”参数化、模板库和复用心得流水线第一次跑通的时候我很兴奋地拿了一个真实需求去试。结果发现虽然流程通了但整个流水线是“硬编码”的——换一个项目我得改一堆字段。后来我把所有可变内容抽成了参数和模板才真正体会到“可复用”这三个字的威力。5.1 配置参数把“项目差异”和“流程逻辑”分开流水线的流程逻辑阶段顺序、上下文契约、检查规则基本是通用的真正需要根据项目变化的是技术栈信息语言版本、框架、数据库类型目录结构代码放在哪个目录、测试放在哪里团队规范命名规则、提交规范、接口风格模型配置不同阶段的模型选择、温度参数、最大Token我把这些内容放进一个pipeline_config.json文件。跑新项目时只需要复制这个配置文件然后修改对应字段流水线本身不用动。{ project: { name: member_service, tech_stack: python3.11, framework: fastapi, database: postgresql, code_dir: src, test_dir: tests }, models: { clarify: cheap-fast-model, design: strong-reasoning-model, implement: strong-reasoning-model }, rules: { max_task_lines: 500, require_review_pass: true, strict_output_format: true } }有了这份配置文件我从“给流水线喂需求”变成了“给配置文件喂需求”本质上把每个项目的差异性隔离出去。流水线本身变成了一个通用的执行引擎这是“可复用”的第一步。5.2 沉淀模板库比Prompt模板更值钱的是“历史产物”我真正的复用法宝不是一个通用Prompt库而是历史任务完成后的完整产物库。每跑完一个需求我会把需求文档、接口设计、任务清单、最终代码和审查报告归档到一个目录打上标签。再遇到类似需求时直接把历史需求捞出来改几个参数作为当前需求的参考上下文。这个做法让需求澄清和设计阶段的时间直接减少一半左右因为AI有“参照物”了。它知道上次那种方案落地后是可行的也能看到上次踩过的坑。比如第二次做优惠券功能时我在Prompt里加了一句话“以下历史文档是上一个同类功能走完流水线后的最终方案请参考它的设计风格接口规范但要注意本次需求中新增的限制条件。”然后附上历史方案文档。AI生成的方案明显更贴近团队实际的编码习惯而不是给出一个风格独立的“标准答案”。5.3 模板复用的边界什么时候该重来什么时候该抄上次复用不是无脑抄。我的经验是核心流程和归档产物可以复用但技术选型和关键逻辑不能只看历史方案。如果这次需求涉及的调用量比上次高一个数量级或者引入了新的数据一致性要求那技术设计阶段就必须重新分析不能因为历史方案看起来完成度高就直接沿用。我给复用设了一个判断条件如果新需求与历史需求在“目标用户”“数据规模”“可用性要求”三个维度上任何一个发生显著变化技术设计和编码阶段必须从头走一遍需求澄清和任务拆解阶段可以复用。这个条件帮我避免了好几次“凭经验套老方案”的翻车现场。6. 跑完N个需求之后的实测结果、避坑指南和几条真心话这篇文章前面说得比较理论最后来点实际数据。我拿一个真实需求完整走了流水线然后说说数据、坑和我的判断。6.1 真实案例会员积分功能从一句话到可合入代码需求原文只有一句话“给会员加积分功能下单得积分积分能抵扣部分金额。”走流水线之后每阶段的实测结果阶段耗时产出人工确认次数需求澄清约20分钟需求文档含6条验收标准1次确认了积分抵扣比例上限技术设计约40分钟数据模型3个API接口定义1次确认了积分过期策略任务拆解约5分钟8个任务依赖关系明确0次编码实现约90分钟8个任务依次实现生成约3200行代码0次代码审查约15分钟审查报告发现2个细节问题1次人工确认后修复从需求描述到代码入库总耗时约3小时。这个需求如果按传统方式做我预估需要一整天多人协作。流水线最大的收益不是“写代码变快”而是每一道工序的产出都被记录下来了项目评审和后续维护都有据可查。6.2 最值得提前修复的三个坑第一个坑是任务拆解粒度。刚开始我让AI自己定任务粒度结果它几十个任务一律250行左右看起来统一但是很多逻辑紧密耦合的模块被硬拆开了导致实现阶段跨任务的上下文丢失。后来我在拆解Prompt里加了一条如果两个任务修改同一核心文件且交互密集必须合并成一个任务。这条规则直接让跨任务bug减少了大概六成。第二个坑是审查阶段的规则脚本不够严格。一开始我为了省事只跑了语法级检查结果生成代码虽然能运行但存在一个大漏洞部分接口没有加鉴权中间件。这个问题最后还是测试环境跑联调时才发现的。后来我把审查脚本做成了一套检查清单包括“数据访问层是否统一走仓储模式”“新增接口是否在路由表里注册了鉴权中间件”等等每一条都要机器或人工勾选确认才放行。第三个坑是上下文污染。流水线早期我发现编码阶段经常引用无关的历史字段或旧接口名排查后发现是需求阶段把一些闲聊的历史对话也缓存进了上下文。后来我在阶段衔接时加了“信息清理”步骤只保留结构化产出文件弃掉中间对话记录问题立即消失。6.3 我的几条真心话写给想抄作业的你第一次搭流水线不用追求全自动。最理想的是“核心关卡人工拍板其余自动跑”这里的核心关卡就是前面说的人工闸门。全部自动化会导致问题发生后你才发现返工成本反而更高。另外要有心理准备搭这条流水线的成本抵得上写五六个普通需求的代码量。所以它适合的是有持续开发需求的团队如果你只是临时写一个脚本直接问AI反而更快没必要上流水线。我自己的判断标准是同一个场景、同类需求预计会出现3次以上就值得跑流水线如果只是为了验证一个想法能不能实现那它只是“一次询问”不要小题大做。最后就是一个特别重要的建议给每个阶段的产物加版本号。需求文档和设计文档在流水线中途很可能会因为人工确认而修改如果版本管理没跟上后面实现阶段读到的可能还是旧设计。我用的是简单的文件命名规则“document_v2.md”虽然土但从来没有因为版本问题错乱过。我自己现在把需求开发流水线跑起来后最大的变化不是代码生成速度而是心态。以前看到需求会先焦虑“这事从哪里开始”现在很自然地就会想先跑澄清再出设计拆完任务然后让编码器逐个实现最后过一遍审查。这种感觉就像手里有了一条完整的装配线你要做的只是把原材料放到入口然后在几个关键节点上摁一下确认键。