最近常有人问我：AI 编程工具我也在用了，为什么在别人手上那么神，在我手上就翻车？演示视频里它能一口气写几百行代码，放到真实项目里却各种离谱——改 A 坏 B、上下文越聊越乱、代码能跑但没人敢上线。我通常直说：你不是在用 AI 写代码，你是在用 AI 碰运气。真正靠谱的 AI 写代码，不是把需求扔进对话框等奇迹，而是像工厂一样有工序、有质检、有交接规范。这篇是这个系列的第十篇，聚焦一套叫 Superpowers 的工作流——核心是用 Subagent（子代理）驱动开发，把「AI 写代码」变成一条严谨的生产流水线。
这篇内容适合三类人：已经被 AI 编程惊艳过、也被它坑过的人；想在团队里统一 AI 编码规范的人；还有刚入门、不想从第一天就养成坏习惯的新手。看完你会清楚三件事：为什么单会话模式不行、流水线由哪些工位组成、每道工序之间的质检标准怎么定。
1. 为什么「一个会话写到底」的 AI 编程注定翻车
先聊病根，再开药方。很多人用 AI 编程的方式是单会话模式——打开一个对话窗口，把需求贴进去，然后在一个会话里不断追问、修改、再修改。这个模式在小任务上没问题，任务越简单效果越好。但项目一旦超过三五个文件、涉及多轮迭代，三个硬伤会依次爆出来。
1.1 单会话模式的三个死穴
第一个死穴是上下文污染。每一次对话都在消耗模型的注意力，而且对话越长，历史信息就越杂。你前面让它写的函数、中间讨论过的方案、后面又推翻的决定，全都堆在同一个上下文里。模型不会自动区分哪些是最终决策、哪些是早期废弃想法。我见过最典型的一幕：在第十轮修改时，模型“顺手”把第二轮已经被废弃的旧逻辑又实现了一遍。不是它坏，是它脑子里装的东西太多了，注意力被稀释了。
第二个死穴是角色切换困难。写代码和审查代码是两种完全不同的认知模式。写代码要激进、要快速产出；审查代码要挑剔、要怀疑一切。你把两件事放在同一个会话里，模型会在“我相信自己写的代码没错”和“我要找找自己的毛病”之间反复拉扯。结果就是审查形同虚设——自己看自己的代码永远觉得没问题。这跟你让一个刚写完文章的作者自己校对错别字一样，他看到的都是自己想表达的意思，而不是屏幕上真实存在的文字。
第三个死穴是缺乏质量门禁。单会话模式下没有任何强制验收环节。模型写完一个模块，不会有人拦住它问：单元测试呢？边界情况呢？异常分支呢？代码风格呢？它默认“任务完成”等于“代码能跑”。但真实的工程交付，代码能跑只是及格线。没有质检工序，所有问题都会堆到集成阶段集中爆发，那时候排查成本已经翻了不止一倍。
提示：判断你的 AI 编程模式是否需要升级，只需要看一个信号——你的对话历史里有没有出现过“不好意思，我好像把之前的功能改坏了”这句话。出现过，就说明该换流水线了。
1.2 Superpowers 流水线的核心思路：物理隔离对抗上下文混乱
Superpowers 这套工作流解决上述问题的思路，概括成八个字：拆开工序，隔离上下文。它把复杂的 AI 能力调用封装成一个个可复用的技能，其中最有价值的技能就是 Subagent 调度。
具体来说，主代理不再亲自完成所有事情，而是像车间主任一样，把开发任务拆解成若干独立的工序，每个工序交给一个专门的子代理去完成。每个子代理拥有独立的上下文、独立的系统提示词、独立的任务边界。编码子代理永远不会看到你前一小时跟需求子代理讨论的记录，它只拿到一张写清楚“要做什么、不能做什么、怎么算完成”的任务卡片。这不只是省 token 那么简单，它从根本上切断了上下文污染的上游。
流水线刚被发明的时候，工人们从全流程组装变成每人只做一道工序，看起来“低效”——每个人都只懂一颗螺丝的拧法，但工厂的整体效率和产品一致性反而暴涨。AI 编程也是同理：单个代理的全能并没有换来整体稳定，工序拆分才是稳定性的来源。
2. 流水线的工位怎么设计：五个核心 Subagent 的角色拆解
把 AI 开发当作生产流水线，第一件事就是设工位。我实际跑下来，最少需要五个工位，对应五道工序。每个工位都是一份独立的岗位说明书（系统提示词）加一套输入输出规范。少了任何一个，流水线都会出现质量漏洞。
2.1 需求解析 Agent：堵住上游的坑
第一个工位是需求解析。它的输入是最原始的客户需求——可能是一段话、一个文档、甚至一次会议记录。它的输出是一份结构化的需求清单，包含每个功能点的编号、名称、触发条件、操作步骤、预期结果，以及最关键的验收标准。
这个环节最容易被新手跳过，因为大家都觉得“需求我比 AI 懂，不用它帮我分析”。但事实上，我见过太多编码环节翻车的事故，追根溯源全在需求解析阶段埋了雷。举一个最常见的场景：需求写着“实现用户登录”。你以为这需求很清楚，但需求解析代理必须追问一串问题：登录失败怎么办？密码连续错误要不要锁定？要不要第三方登录？“记住我”怎么实现？Token 过期了怎么处理？这些答案不落在纸面上，编码代理就只能靠猜。猜对了是运气，猜错了是事故。
所以需求解析的输出里必须包含“边界条件”和“异常场景”两个字段，并且所有验收标准都必须可验证——也就是说，要能转换成测试用例。写不出测试用例的功能点，说明需求本身还没搞明白。
2.2 架构设计 Agent：先画图纸再动工
第二个工位是架构设计。它不写代码，只画图纸。输入是上一道工序的需求清单，输出是技术方案、模块划分、数据流描述、接口定义，以及任务拆分清单。
为什么需要独立一个工位做架构设计？因为跨模块的问题在编码环节解决成本最高。比如一个订单系统，如果不在架构阶段就确定订单号生成策略、表结构设计、缓存与持久化的一致性方案，编码代理在实现每个任务的时候就会各自为政。等集成的时候，你会发现 A 模块的订单号用了时间戳，B 模块用了自增 ID，两边对不上账，返工成本高到想删库跑路。
架构设计还有一个关键产出是任务拆分清单，它直接决定流水线后续环节怎么调度。拆分的粒度标准我总结成三条：每个任务能独立验证；每个任务的文件变更范围可控；任务之间的依赖关系清楚。满足这三条的任务拆分，编码环节才跑得顺。
2.3 编码实现 Agent：一条铁律，一次只做一件事
第三个工位是编码实现。它是流水线上真正的“生产工位”，输入是架构设计产出的其中一个任务条目，输出是能运行的代码、配套的单元测试、以及变更说明。
这个工位有一条反直觉但极其重要的规则：一个子代理一次只处理一个任务。不是五个、不是两个，就是一个。很多人第一次听到会觉得太慢，恨不得一次让 AI 写五个功能。但实际跑下来，一次一个任务才是效率最高的。原因有三条：第一，上下文聚焦，编码代理不需要在多个任务间来回切换，出错概率大幅下降；第二，变更范围可控，拿到的 diff 就是这一个任务对代码的改动，审查环节的成本成倍降低；第三，失败定位简单，出了问题就是这个任务的锅，不需要在几坨代码里大海捞针。
编码工位还有一条纪律：不允许越界“帮忙”。编码代理经常会有一种莫名的“好心”，在实现任务 A 的时候顺手“优化”一下任务 B 涉及的文件。这种越界行为是流水线的大敌，必须通过任务卡片的约束和审查工位的把关双重拦截。
2.4 代码审查 Agent：立场必须和对端相反
第四个工位是代码审查。它的工作不是“看看代码行不行”，而是“默认代码有问题，然后找出问题”。输入是编码工位产出的 diff、测试结果和任务卡片，输出是一份分级的问题清单。
审查工位的系统提示词必须与编码工位形成立场对立。编码工位被鼓励“快速完成、相信自己的方案”，审查工位则要明确告知“你收到的代码应该被假定为有错，你的职责是找出错误”。这两个工位的立场不对立，审查就会变成走形式。我见过很多团队的审查代理设计得特别温和，输出永远是“代码质量良好，可以合并”，这跟没有质检员有什么区别。
问题清单按严重程度分级：阻断级（逻辑错误、安全漏洞、违反架构约定）、建议级（可读性、性能隐患）、风格级（命名、格式）。只有阻断级清零，代码才能进入下一道工序。
2.5 测试验证 Agent：用数据说话，不许报喜不报忧
第五个工位是测试验证。输入是审查通过的代码和测试计划，输出是测试报告。这份报告必须包含：测试场景清单、每个用例的输入输出预期、实际执行结果、失败用例分析、覆盖率数据。
我最不能接受的一句话是“测试通过”。四个字没有任何信息量。测试报告要说清楚测了多少个用例、覆盖了哪些场景、有没有失败、失败卡在哪、覆盖率是多少。没有数据，你根本无法判断任务是否真正完成。
除了常规的单元测试和集成测试，测试工位还要主动做“刁钻”的边界验证：空值、超长字符串、并发请求、重复提交、权限不足。这些场景在需求清单里可能没有一行字，但测试工位必须补上。AI 生成的代码，天然对边界情况考虑得不够激进，你不测它，它就敢漏。
3. 实操手册：把流水线跑起来的关键环节
讲完工位设计，这一章讲怎么把它搭起来。我按实际操作顺序，把最关键的三个环节拆开：系统提示词怎么写、任务交接怎么做、质量门禁怎么判断。
3.1 系统提示词模板：每个工位的岗位说明书
流水线的灵魂是系统提示词。一份合格的岗位说明书，至少包含角色定义、职责边界、输入输出格式、禁止事项四个板块。下面是我现在用的编码工位模板，可以直接抄：
你是一名资深后端开发工程师。你的任务是根据任务卡片实现指定的功能。 工作要求： 1. 严格按照任务卡片中的"任务描述"实现，不扩大也不缩小范围 2. 动手前先阅读任务卡片列出的相关文件，理解现有代码风格 3. 实现过程中同步补写单元测试，覆盖正常路径和边界场景 4. 完成后输出：变更文件清单、核心逻辑说明、测试结果 禁止事项： - 不修改任务卡片"约束条件"中未允许修改的文件 - 不对既有 API 签名做任何变更 - 不引入任务卡片未声明的依赖 - 如果发现任务描述与现有代码冲突，先停下来在输出中说明原因，不要自行决策 输出格式： - 变更文件：列出新增/修改的文件路径 - 实现说明：每个变更文件的改动要点 - 测试结果：运行的测试命令与通过情况这里面的关键是最后加的“冲突先停下来说明”这一条。很多事故的源头是编码代理遇到了代码现状与任务描述矛盾的情况，它往往自作主张选了一个方向继续写。与其赌它对，不如强制它把矛盾暴露出来，让上游环节来处理。
3.2 交接协议：用任务卡片代替聊天记录
流水线各工位之间的信息传递，绝对不能靠复制粘贴聊天记录。正确做法是给每个任务生成一张标准化的任务卡片，作为各环节之间的“流动单据”。
任务编号：T-003 所属模块：用户中心 任务描述：实现租户级密码过期策略配置与登录校验拦截 输入文件：src/auth/policy.py、src/auth/login.py 约束条件： - 不修改既有 API 签名 - 兼容 PostgreSQL 和 SQLite 两种存储 - 密码策略可配置，默认过期时间 90 天 前置依赖：T-001（用户模型）、T-002（认证中间件） 验收标准： - [ ] 超过过期时间的密码在登录接口返回 403_PASSWORD_EXPIRED - [ ] 密码策略配置接口只能由租户管理员调用 - [ ] 单元测试覆盖率达到 80% 以上 - [ ] 不破坏既有登录流程的测试用例任务卡片最重要的字段是“约束条件”和“验收标准”。约束条件划出边界，验收标准定义终点。没有这两项的卡片是不合格的，不允许下发到编码工位。
3.3 质量门禁：打回与放行的判定规则
每道工序的产出物在流入下一道工序之前，都要经过质量门禁。我把门禁规则做成一张检查表，贴在每个项目的文档里：
| 工位 | 放行条件 | 打回条件 |
|---|---|---|
| 需求解析 | 每个功能点有可验证的验收标准；边界场景已列出 | 存在无法转成测试用例的功能点；有未澄清的关键歧义 |
| 架构设计 | 模块划分清晰；任务拆分满足“可独立验证、变更可控、依赖清楚” | 存在跨模块职责重叠；拆分粒度过粗或过细 |
| 编码实现 | 测试通过；变更范围符合任务卡片；无越界修改 | 冒烟测试失败；改动超出约定范围；缺少配套单元测试 |
| 代码审查 | 阻断级问题清零；建议级问题有处理结论 | 存在阻断级逻辑错误；安全风险；接口与架构设计不一致 |
| 测试验证 | 所有用例通过；覆盖率达到约定值；失败项有明确原因 | 存在未解释的失败用例；关键场景未覆盖 |
这道门禁是流水线的约束骨架。没有它，每个工位都在“我觉得我做完了”的幻觉里打转；有了它，每个环节的产出都必须接受下游标准的检验。
4. 实战效果与踩坑实录
理论讲完，讲讲把它跑在一个真实中型项目上的结果。这个项目是一个内部管理系统重构，6 个模块、32 个功能点、最终代码量约 8000 行，中间经历了三轮迭代。
4.1 一次中型重构的实测数据
我拿同一个项目做过对照。第一轮用单会话模式写，第二轮用 Subagent 流水线写。两轮的需求和验收标准完全一样，结果如下：
| 对比维度 | 单会话模式 | Subagent 流水线 |
|---|---|---|
| 上下文溢出次数 | 3 次（被迫清空重开） | 0 次 |
| 跨模块修改导致的回归问题 | 7 个 | 2 个 |
| 任务被打回返工的比例 | 约 40% | 约 12% |
| 一次通过评审并成功上线的任务 | 12 个 | 27 个 |
| 单任务平均耗时 | 约 29 分钟 | 约 18 分钟 |
注意，这个数据只代表一个有代表性的项目，不是普适结论。但趋势是稳定的：流水线模式在稳定性上的提升是数量级的，耗时的下降主要来自返工减少。看起来每个工位多了一些步骤，但省掉的是最贵的“推倒重来”。
4.2 三个典型的翻车现场
翻车现场一：编码代理的“顺手帮忙”。在实现订单导出任务时，编码代理觉得订单查询函数写得太烂，顺手重构了。结果它不知道另一个模块正在依赖这个函数的旧签名，集成时全线报错。根因是任务卡片的约束条件写得不具体，只写了“不许改订单模块之外的文件”，没写“不许改订单查询函数的签名”。现在我的任务卡片里凡是涉及已有函数的，都会写明“保持外部签名不变”。
翻车现场二：审查代理跟编码代理“客套”。早期的审查代理提示词写得过于温和：“请检查代码质量并提出建议”。结果它跟编码代理达成了一种诡异默契，每次都输出“代码质量良好”。后来我把审查代理的提示词改成“你收到的代码应该被假定为有错，你的职责是找出错误”，并且强制要求逐行检查 diff、输出分级问题清单。立场一换，问题发现率立刻不一样。
翻车现场三：测试代理的“一键通过”。测试代理只跑了一遍主流程就汇报“测试通过”，结果上线后用户一提交空表单就报错。问题出在测试计划覆盖不足——边界场景根本没写进用例。从那次以后，我给测试工位加了一条硬性要求：输出报告中必须单列“边界场景测试”一栏，列不出来就算测试未完成。
4.3 出问题先别急着改代码：反推流水线哪一环漏了
流水线跑久了你会发现一个规律：AI 写代码出 bug 不可怕，可怕的是你找不到 bug 是在哪个环节被放进来的。我的排查思路是反向追溯——先不碰代码，先查流水线：
| 故障现象 | 最可能漏掉的环节 | 该查什么 |
|---|---|---|
| 功能逻辑跟需求完全对不上 | 需求解析 | 需求清单里有没有遗漏原始需求的关键约束 |
| 改了不在范围内的文件 | 编码约束 + 审查 | 任务卡片约束条件是否明确；是否逐文件比对 diff |
| 同一个任务反复返工不过 | 需求解析 | 需求清单本身是否有歧义，先澄清再编码 |
| 上线后才发现问题 | 测试验证 | 测试计划的用例清单是否覆盖边界和异常场景 |
这个反推过程我每次都做，目的不是追责，而是让流水线越跑越严。每发现一个漏洞环节，就补一条对应的规则。跑了几个月之后，质检规则从最初的十几条涨到四十几条，这就是一个生产系统逐渐变得靠谱的过程。
5. 让流水线真正严谨的四个进阶习惯
最后分享几个让流水线从“能跑”升级到“严谨”的习惯。这些不是一次性配置，而是长期运行中沉淀出来的纪律。
5.1 用任务清单当看板，而不是聊天记录
整个流水线的运行状态，应该挂在一个结构化的任务清单上。每个任务是一个条目，包含任务编号、当前所处环节、状态（待处理、进行中、待验收、已完成、已打回）。所有调度决策都基于这份清单，而不是翻聊天记录。这样做的好处是：即使某个环节被打断，任何时候回来扫一眼清单，就知道整个项目推进到了哪里。
5.2 文件级别的“一次只改一个文件”
除了任务级别一次只做一件事，文件级别也要贯彻同样原则。我实际总结出来的规则是：一个编码子代理的一次任务，涉及的修改文件尽量控制在两三个以内。跨文件改动是最大的不确定性来源——文件越多，上下文越分散，回归风险越大。虽然有些需求天然跨文件，但架构设计阶段通过合理的模块划分，可以把大多数跨文件需求切成单文件变更。
5.3 里程碑节点做回归抽检
AI 生成的代码有个特点：新功能看着没问题，但它可能悄悄破坏了旧功能。所以除了每个任务的独立测试之外，我还会在每个里程碑节点做一次回归抽检。规则很简单：从旧用例池里随机抽取 20%，跑一遍全量回归。把它当成新员工转正考核——不要看他表现多好，要看他有没有把别人的活儿搞砸。
5.4 人留在流水线的最末端
把流程自动化了，不代表人可以下线。流水线能保证一致性、完整性和规范性，但产品 sense、商业逻辑、用户体验这些主观判断，机器现在还做不了主。所以我的流程里永远保留一道人工工序：合并代码、发版上线、灰度观察，这几件事必须由人来做。
我的实际体会是，Subagent 流水线引入之后，我的工作内容变了。过去我在跟 AI 的代码搏斗，现在我在管理一条流水线——很大一部分时间是设计任务卡片、校准系统提示词、分析被打回的任务。这比写代码本身更有价值。如果你也想把 AI 编程从“碰运气”变成“做工程”，别急着让它一次写十个功能，先花一个下午，把流水线的工位搭出来。
最后分享一个小技巧：在所有子代理的系统提示词末尾，都加上同一句话——“如果你发现自己要做超出职责范围的事，停下来，在输出中说明原因，不要自行扩大动作边界。”这句话救了我很多次，它把不该由当前环节处理的问题提前暴露在流水线上，而不是等它发展成上线事故。
