在日常研发中,直接向大模型输入“帮我实现这个功能”或“修复这个 Bug”,往往会陷入“生成代码 → 发现需求或技术方案偏差、编译报错 → 修正偏差和错误 → 完成本轮开发”的循环。如何提高一轮任务的完成质量,减少反复返工?这些问题的根源在于:缺少必要的上下文约束、缺乏明确的决策边界,以及模型在自审时难以克服的“确认偏误”(Confirmation Bias)。
本文分享我在设计 AI 研发工作流(dev-workflow 与 bugfix-workflow)时的一些心得,重点讨论流程中的决策链构建、状态机约束、Agent 角色分工,以及如何在复杂工程中组织主 Agent、独立 Agent 与 SubAgent 协同工作。
一、为什么需要结构化工作流?
在复杂工程中,编写代码只是整个研发链路的末端。未理清需求背景与边界就直接编码,极易导致设计偏离。因此,我们的工作流划分为明确的几个阶段,每个阶段对应特定的角色与责任:
阶段与角色定义
| 阶段 | 角色 | 核心职责 | 在完整流程中的作用 |
|---|---|---|---|
| Phase 0 | Context Analyst | 梳理已有需求、相关代码关系及外部依赖(如硬件协议、接口规范) | 补全容易遗忘的需求细节,减少模型幻觉与上下文遗漏 |
| Phase 1 | Planner | 设计状态流、定义模块边界、制定技术方案与验收标准 | 在动代码前确认关键决策,确保实现路径透明 |
| Phase 2 | Coder | 按照已确认的方案编写或重构代码 | 严格在限制的工程范围内修改,禁止超出方案随意发挥 |
| Phase 3 | Reviewer | 独立检查代码 Diff,审查竞态条件、内存泄漏与边界异常 | 打破“自写自审”的思维定势,提供客观审查视角 |
| Phase 4 | Tester | 对照验收标准执行静态检查、核对现有证据并列出必要的人工验证项 | 依靠客观证据而非“看起来没问题”的假设来确认交付 |
| Phase 5 | Delivery Coordinator | 汇总变更、审查结论、验证范围与后续事项,按需更新文档 | 避免局部结论分散,确保交付状态可追溯 |
二、状态机:用确定性对抗模型的随意性
大模型在长会话中极易产生“上下文漂移”——例如在未确认需求细节时就开始生成代码,或者在审查失败后盲目跳过修复。
为此,我们在工作流中引入了状态机与关卡机制(Gate)。在具体的 Skill 中,这些关卡用 Checkpoint #0 等编号表示,下文的 Gate 与 Checkpoint 指同一套机制。
Phase 表示 AI 当前在做什么,Gate 表示哪些地方必须停下来,由人类工程师决定是否继续。 阶段报告完成,只说明 AI 已经交出结果;需要人工放行的关卡,还必须等到用户明确确认才能推进。
| Gate / Checkpoint | 何时触发 | 人类工程师需要确认什么 | 放行后进入哪里 |
|---|---|---|---|
| #0 背景审批 | Phase 0 背景梳理完成 | 场景、目标、当前行为、影响范围与必须保留的规则是否理解正确 | Phase 1 方案规划;尚不允许编码 |
| #1 方案审批 | Phase 1 方案与验收标准完成 | 技术取舍、修改范围、风险与验收方式是否可接受 | Phase 2 编码实现 |
| #2 实现验证与放行 | Phase 2 实现及必要静态检查完成 | 查看实现总结、实际改动和偏差,按清单编译、试机并反馈,或明确同意先进入审查 | Phase 3 独立审查;未取得的运行结果仍标为待验证 |
| #3 审查失败暂停 | Phase 3 连续 3 次未通过 | 根据审查报告选择指导重试、接受已知问题并跳过,或终止 | 按选择再复核一轮、进入 Phase 4,或停止 |
| #4 验证失败暂停 | Phase 4 连续 3 次未通过 | 根据验证报告选择指导重试、接受当前验证状态并跳过,或终止 | 按选择再复验一轮、进入 Phase 5,或停止 |
其中,#0、#1、#2 是正常路径上的三次显式放行;#3、#4 只在失败次数达到上限时出现。Phase 3 审查通过后自动进入 Phase 4;Phase 4 通过,或静态检查通过且无已知代码问题、仅剩已披露的待人工验证项时,进入 Phase 5,不再额外增加一次人工审批。
stateDiagram-v2
[*] --> ContextAnalysis
ContextAnalysis --> BackgroundPending: 背景梳理完成
BackgroundPending --> Planning: Gate #0 人工确认
BackgroundPending --> ContextAnalysis: 补充背景
Planning --> ProposalPending: 方案与验收标准完成
ProposalPending --> Coding: Gate #1 人工确认
ProposalPending --> Planning: 修订方案
Coding --> ImplementationPending: 实现与静态检查完成
ImplementationPending --> Reviewing: Gate #2 人工确认
ImplementationPending --> Coding: 实现反馈
Reviewing --> ReviewFixing: 审查未通过,失败不足 3 次
ReviewFixing --> Reviewing: 定点修复后复核
Reviewing --> ReviewBlocked: 失败达到上限,停在 Gate #3
ReviewBlocked --> ReviewFixing: 人工指导,再重试一轮
ReviewBlocked --> Testing: 人工跳过,保留已知问题
Reviewing --> Testing: 独立审查通过
Testing --> VerificationFixing: 验证未通过,失败不足 3 次
VerificationFixing --> Testing: 定点修复后复验
Testing --> VerificationBlocked: 失败达到上限,停在 Gate #4
VerificationBlocked --> VerificationFixing: 人工指导,再重试一轮
VerificationBlocked --> Delivery: 人工跳过,保留未通过项
Testing --> Delivery: 检查通过、无已知失败,待人工项已披露
Delivery --> [*]: 汇总交付与归档
阻断机制的三条硬性规则
- 关键决策分别放行:背景确认后才能规划,方案确认后才能编码,实现结果经人工放行后才能进入独立审查。每次放行只允许进入当前关卡对应的下一阶段,不能一次确认就跨过后续 Gate。背景充分、用户补充了信息或没有回复,都不能视为放行。
- 审查与验证失败次数上限:
Phase 3与Phase 4分别记录连续失败次数,达到 3 次时强制暂停,交由人类工程师干预;返修不重置次数。人工选择“重试”只增加一轮修复与复核机会,仍未通过就停回原失败关卡;选择“跳过”则保留已知问题与未满足的验收标准,不能把跳过写成通过。 - 证据驱动的可靠交付:进入交付阶段前,必须给出实际执行的静态检查、可用日志、截图或其他验证证据,并逐条标明验收状态。仍需编译、运行或真机确认的项目必须明确列出,不得以主观描述或静态结果代替运行结论。
Gate 中收到反馈时,如何继续?
用户回复“确认”或明确要求进入合法的下一阶段,才表示放行。普通提问、补充信息、缺陷反馈和修改要求都在当前阶段处理。例如,停在 #2 时用户提出“把 3 分钟改成 5 分钟”,就继续在 Phase 2 调整,同步相关方案和验收标准,完成必要静态检查后再次展示 #2;不必从背景分析重新走一遍。
审查和验证中的定点返修也留在当前阶段处理,不重新触发 #0–#2;修复后补齐相关复核与验证,再按原阶段规则继续。
这些规则需要落实到 Skill 的停止条件和任务状态记录中,例如当前的 phase、waiting_checkpoint、已确认方案与失败次数。流程图帮助说明规则,实际执行时仍需核对 Agent 是否遵守了这些边界。
三、深入理解多 Agent 架构:主 Agent、独立 Agent 与 SubAgent 的协同哲学
在 AI 工作流的演进中,单 Agent 的局限性逐渐显现:当任务变得复杂、上下文变得冗长时,单一上下文中的模型更容易出现注意力分散、逻辑混淆和确认偏误。因此,在复杂任务中引入多 Agent 协同,有助于分担工作、隔离上下文,并引入不同的审查视角。
但在实践中,我们必须明确区分它们的职责与存在价值:
1. 什么是主 Agent(Main Agent)?
- 角色定位:整个任务的“项目经理”与“核心主脑”。
- 职责与使命:
- 负责掌控总体进度、维护核心上下文(如原始需求、架构方案、主交付物)。
- 驱动状态机从 Phase 0 稳步流转至 Phase 5。
- 统筹全局,根据需要向外分派子任务,汇总、核实子 Agent 提交的结果,并将需要人工取舍的问题交给人类工程师。
- 为什么不可或缺:在这套设计中,主 Agent 负责维护整条研发链路的连贯性,避免各个子任务有局部结论,却没有统一的进度与交付状态。
2. 什么是独立 Agent(如独立 Reviewer Agent)?
- 角色定位:拥有独立任务上下文的“外部专家”。
- 为什么需要它(打破确认偏误):
- 在传统的单 Agent 模式下,实现与审查使用同一份上下文。模型容易沿用“前面为什么这样实现”的推导,重复自己的假设,从而漏掉竞态条件、边界异常等隐蔽 Bug。
- 独立 Agent 拥有独立的上下文边界。它读取最新背景、“需求契约”、“架构方案”、“实际代码 Diff”及必要的代码上下文,不继承完整的编码对话和实现者的自我评价。它需要知道业务前因后果,但不被前面的实现推导牵着走,从而降低确认偏误的影响。
3. 什么是 SubAgent?
- 角色定位:由主 Agent 动态派生、专门处理特定繁重子任务的“特种兵”(如证据调查 SubAgent)。
- 为什么需要它(解耦与噪声治理):
- 上下文污染治理:在排查复杂 Bug(如蓝牙通信失败、数据同步异常)时,往往伴随着几兆大小的运行日志或多张界面截图。如果全部喂给主 Agent,会迅速耗尽主会话的上下文窗口并引入大量噪音。
- 并行调查与降本增效:SubAgent 可以在独立任务上下文中分析大量日志、时序数据或接口契约,过滤掉无关信息后,只向主 Agent 提交结构化的事实摘要和关键证据。对彼此独立的调查按需并行,有助于保护主 Agent 的注意力并提升复杂任务的排查效率;实际收益仍取决于任务规模与交接成本。
四、让 Agent 真正进入工作流:从角色分工到交付闭环
明确角色之后,还需要把这些角色放回真实的研发任务中,建立一条清晰的协作链:谁负责推进、交接什么、何时进入下一阶段,以及失败后如何处理。
关键在于,每个阶段都要解决一个不同的问题,并向下一阶段交付可核对的结果。角色分工只有与输入、输出、权限和失败处理绑定起来,才能成为真正可执行的工作流。
1. 先分清两个维度:工作职责与协作方式
前文提到的角色,实际上处在两个不同的维度:
- Context Analyst、Planner、Coder、Reviewer、Tester:描述“当前要承担什么职责”。它们分别关注背景、方案、实现、审查和验证。
- 主 Agent、独立 Agent、SubAgent:描述“由谁组织任务、如何划分上下文、如何委派工作”。
因此,这些工作职责并不意味着每次都要分别启动一个 Agent。在这套设计中,主 Agent 默认承担 Context Analyst、Planner、Coder、Tester 及最终汇总的 Delivery Coordinator 职责;独立 Reviewer Agent 在 Phase 3 使用独立任务上下文审查;证据调查 SubAgent 则在日志分析、时序还原等工作确实复杂时按需介入。
一个 SubAgent 也可以承担独立 Reviewer 的职责,前提是它使用独立的审查上下文,且没有参与本次实现或诊断结论的形成。这里的“独立”,强调的是审查视角与上下文边界;“SubAgent”强调的是任务的委派关系。两者并不是互斥的产品类型。
人类工程师则保留业务目标、方案取舍和阶段放行的决策权。主 Agent 可以组织推进,但不能代替人类确认需求,也不能替独立 Reviewer Agent 宣布审查通过。
2. 各阶段如何接力?
Phase 0:Context Analyst 先确认“我们究竟要解决什么问题”
- 输入:用户描述、已有需求、相关代码、历史决策,以及能够取得的接口、设备协议或故障资料。
- 工作内容:还原功能目标,区分当前行为与目标行为,整理影响范围、必须保留的规则和关键未知。
- 交付物:背景说明,包括原有需求、当前行为、目标行为与约束;对于 Bug 修复,还要形成包含“触发条件、预期结果、实际表现、证据来源”的故障基线。
- 交接条件(Gate #0):人类工程师确认背景与问题边界后,再进入方案阶段。背景确认只表示双方理解一致,不代表故障原因已经定位,也不允许提前编码。
为什么需要这一阶段:模型很容易把用户描述中的现象直接当成原因。如果没有故障基线,后续即使代码写得正确,也可能并没有修复当前问题。
Phase 1:Planner 把背景转成“可实现、可审查、可验证的方案”
- 输入:已确认的背景与边界、相关代码关系,以及必要的调查证据。
- 工作内容:明确修改范围与不修改范围,设计状态流、模块职责、异常处理和兼容策略,列出实现任务及验收标准。
- 交付物:技术方案与验证契约。验证契约说明每条验收标准准备如何核对,需要什么证据,以及哪些项目依赖人工或真机验证。
- 交接条件(Gate #1):人类工程师确认方案与验收标准后,Coder 才能开始修改代码。
在 bugfix-workflow 中,主 Agent 还要先承担 Investigator 的职责,交叉核对代码与故障证据,再以 Planner 的身份设计修复。证据不足时,应明确本轮是继续取证还是实施修复,不能把一个猜测包装成已经确认的根因。
为什么需要这一阶段:方案让“模型打算怎么改”在编码前变得可见;验收标准则提前定义“怎样才算完成”,避免模型写完代码后再挑选有利于自己的完成条件。
Phase 2:Coder 在已确认的边界内完成实现
- 输入:已确认的方案、允许修改的模块或文件范围、项目规范及验收标准。
- 工作内容:读取相关代码,按任务清单实现,复用已有能力,并执行允许范围内的轻量静态检查。
- 交付物:实际代码 Diff、变更文件列表、静态检查结果、与原方案的偏差说明,以及必要的人工验证清单。
- 交接条件(Gate #2):主 Agent 汇总实现结果后暂停,供人类工程师编译、运行或真机测试并反馈。人类工程师明确放行后,再交给独立 Reviewer;若同意先进入审查,尚未执行的验证项继续保留为待验证。
如果编码过程中发现方案依赖的接口不存在,或者现有生命周期无法支撑原设计,Coder 需要把事实和影响反馈给主 Agent,更新相关方案与验收标准。涉及实质性取舍时,由人类工程师确认,不能顺手扩大范围或更换目标。
为什么需要这一阶段的权限约束:模型常常会在实现一个功能时顺便重构周边代码。限制 Coder 的修改范围,可以控制 Diff 的规模,也让后续审查更容易识别真正影响行为的变更。
Phase 3:独立 Reviewer 检查“目标是否实现,工程上是否可靠”
- 输入:最新背景、已确认方案、验收标准、实际代码 Diff、必要的调用上下文及项目规范。
- 工作内容:同时进行需求正确性与工程正确性审查。前者检查有没有做错目标、遗漏规则或越出范围;后者检查协程与生命周期、异步竞态、异常处理、资源释放等工程问题。
- 交付物:审查结论与问题列表。问题应包含代码位置、触发条件、具体影响及判断依据。
- 交接条件:审查通过后自动进入验证;未通过则由主 Agent 核实问题、组织 Coder 定点修复,再交回独立 Reviewer 复核。连续 3 次未通过时,停在 Gate #3 等待人工决定。
Reviewer 不直接接管业务实现。这样可以保留“提出问题—修复问题—复核结果”的责任链,避免审查者一边改代码,一边为自己的修改作出通过结论。
为什么必须保留独立上下文:主 Agent 切换一句“现在我是 Reviewer”,并不会清除它之前的实现思路。独立 Reviewer 需要基于需求、方案和代码重新作出判断,而不是延续 Coder 的自我解释。
注意:目标明确、影响局部且验证范围可控的简单任务,可以在入口处采用轻量处理,由主 Agent 实现并自检;一旦进入本文的完整工作流,Phase 3 仍保留独立 Reviewer。
Phase 4:Tester 对照验收标准核对“哪些结果已经得到证据支持”
- 输入:审查后的最新实现、验证契约、故障基线,以及对应版本的日志、截图或其他可用验证资料。
- 工作内容:逐条核对验收标准,检查原始触发场景、相邻正常路径与相关边界,区分已通过、已失败和待人工验证的项目。
- 交付物:验证报告,写明实际执行的检查、证据来源、未执行项及原因,必要时附上人工回归清单。
- 交接条件:已知失败项进入定点返修;具备充分证据的项目才能标记通过,尚未运行的项目保留为待验证。连续 3 次未通过时,停在 Gate #4;只有待人工验证项、没有已知代码问题时,可携带这些待办进入 Phase 5。
在我当前的 Android 项目约束下,AI 默认执行静态检查、逻辑核对和现有证据分析,不主动编译项目,也不新增测试用例;编译、运行与真机验证按人工验证清单或后续明确授权处理。这是项目的执行约定,其他项目可以按自己的验证能力调整。Tester 必须明确区分“静态检查通过”与“真机行为已验证”,不能用前者代替后者。
如果审查或验证返修改变了已经测试过的行为,需要补充独立增量复核,并标明受影响的重测范围,不能直接沿用旧版本的通过结论。
为什么审查后还需要验证:Reviewer 判断的是代码是否存在可识别的问题;Tester 核对的是验收目标是否有证据支撑。尤其在设备通信场景中,回调顺序、硬件状态和网络环境都可能让代码阅读与实际表现产生差距。
Phase 5:Delivery Coordinator 汇总交付,保留可继续追踪的上下文
- 输入:最终实现、审查报告、验证报告及必要的背景或需求记录。
- 工作内容:汇总改动范围、关键决策、验证结论、未解决问题和后续事项;代码与相关验证稳定后,在本阶段末尾按需更新正式文档。
- 交付物:可以追溯到文件与证据的交付说明,以及明确的待人工验证清单。
- 完成边界:如果仍有真机或硬件项目未验证,应明确标记“实现与静态验证已完成,运行行为待验证”,不能笼统宣布全部通过。
为什么需要统一收尾:多个 Agent 的局部结论只有经过主 Agent 汇总,才能回答用户真正关心的问题:改了什么、解决了什么、凭什么这样判断、还剩什么没有确认。
3. SubAgent 如何参与,又为什么不负责整条流程?
证据调查 SubAgent 通常在 Phase 0 或 Phase 1 介入;Phase 4 如果需要复杂的修复前后对照,也可以复用。它的任务应当足够具体,例如:
分析指定设备在这一轮重连中的日志,按时间顺序整理断开、重试、连接回调与页面状态更新;区分已经观察到的事实与尚未证实的原因,并给出关键日志位置。
SubAgent 返回的应是时间线、关键证据、结论适用范围与未决问题。主 Agent 再把这些事实与业务背景、代码关系交叉核对,形成诊断或方案。
这条边界非常重要:调查 Agent 提供证据,主 Agent 组织决策,独立 Reviewer 审查实现。参与过诊断的调查 Agent 不兼任同一任务的独立 Reviewer,避免它在审查时继续维护自己的前期判断。
同时,独立上下文并不天然意味着工作目录或设备也被隔离。多个 Agent 共用工程或设备时,仍需明确文件所有权和操作顺序;同一台设备的页面操作、配对或取证应由一个执行者统一负责,避免调查过程相互干扰。
. 这套流程的必要性:把错误拦在更早、更清楚的位置
结构化工作流会增加背景整理、方案说明和独立交接的成本,但它要减少的是错误决策进入代码后,反复实现、反复排查、反复回滚的成本。
- 背景阶段拦截目标错误:避免把设计行为当成 Bug,或把用户现象误当成故障原因。
- 方案阶段拦截决策错误:在代码生成前暴露状态流、模块边界和验收条件的问题。
- 实现阶段拦截范围失控:让每一处修改都能对应已确认的任务,减少无关重构与额外风险。
- 独立审查拦截实现遗漏:引入没有参与编码推导的视角,检查需求偏差与工程缺陷。
- 证据验证拦截虚假完成:把“看起来合理”“静态检查通过”和“运行行为已验证”分开记录。
- 主 Agent 收尾拦截交接丢失:保留结论、依据和未决事项,让下一轮工作能够接续。
这些机制不能保证模型永远不犯错,但能让错误更早暴露、影响范围更容易控制、完成结论更容易核实。对于设备通信、异步状态和跨模块改动,这种可追溯性正是工作流的主要价值;对于简单任务,则可以压缩报告与调查规模,避免为了角色数量而增加无效协作。
五、上下文隔离与 Token 消耗控制策略
引入多 Agent 和 SubAgent 架构时,需要控制 Token 消耗与交接成本。合理的分工有助于在可控的协作成本下,获得更可靠的结果:
- 精准交接,禁止全量复制: 主 Agent 委派 SubAgent 或独立 Agent 时,传递目标、必要背景、约束条件、相关代码与 Diff、结构化契约,避免把数万行历史对话全文透传。必要背景应足以理解任务,精简上下文不能以遗漏需求边界为代价。
- 只返回事实摘要,不返回原始探索过程: 子 Agent 在解析了大量日志或进行了多轮代码检索后,只向主 Agent 返回结构化的结论与关键证据(如文件行号、关键日志原文),并注明事实、推断与未知。原始探索资料保留在子上下文或调查记录中,便于主 Agent 按需回查。
- 按需启用,避免过度设计:
- 单 Agent 即可处理的轻量任务:无需进入完整研发流程的机械性单文件修改、局部 UI 文案调整或短日志解读,可以由主 Agent 直接完成;不必为了角色齐全而额外拆分任务。
- 开启多 Agent 协同:进入本文两条结构化工作流时,Phase 3 保留独立 Reviewer;额外的调查 SubAgent 则按需启用,例如需要关联多次运行的日志、还原复杂时序,或跨多个独立领域(如 API 契约与底层通信协议)展开调查。是否委派取决于工作量与任务独立性,不按日志行数机械划分。
六、工作流需要 Skill 配合
工作流规定了开发任务如何推进,但在Coder编码过程中,怎样产出符合项目封装与规范的代码?这就需要从项目实践中抽取出详细、实用的各类基础 Skill,把这些基础工作做扎实。
Skill 的封装,可以理解为把程序员的项目经验提炼成 AI 能执行的指引。例如,项目中弹窗应该怎么写,程序员知道,就可以封装成 Skill,让 AI 也知道。AI 读源码或许也能找到答案,但既耗时,也可能绕过项目已有封装,重新采用更底层的实现方式。
Android 领域常见的 Skill 有:
- 新页面初始化(如
base-new-page):告诉 AI 新建页面时需要完成哪些工作,以及应该复用哪些基础能力。 - UI 转代码(如
figma-to-compose):告诉 AI 如何将 Figma 设计稿转换为符合项目规范的 Compose 代码。 - 接口转网络请求(如
api-to-request):告诉 AI 如何接入接口。单个请求、串行请求、并发请求的处理方式不同,可以按场景拆分 Skill。 - 页面弹窗:确认框、底部弹窗、全局弹窗等,已经形成项目规范的做法都可以沉淀为 Skill。
- 其他常见场景:下拉刷新与上拉加载、Adapter 编写、代码自检、页面卡顿分析等。
AI 越来越聪明,Skill 不必重复所有通用编程知识。更实用的原则是:当 AI 出错,或产出的代码不符合工程师预期时,把可复用的项目规则和经验沉淀下来作为新的skill,减少下一次出现同类偏差。
这正是项目 Skill 的价值。
七、总结
结构化工作流的核心,在于把对 AI 的信任建立在制度和约束上,而不是大模型的偶然表现上。
- 通过分阶段角色与阻断状态机,把控需求到代码的每一个决策点,用确定性对抗模型的随意性。
- 通过主 Agent 贯穿 + 独立 Agent 审查,维持任务的整体连贯,并降低模型自我确认偏误带来的遗漏。
- 通过明确的输入、交付物和返修路径,让各类 Agent 的职责形成闭环,确保“背景—方案—实现—验证”始终围绕同一个目标。
- 通过证据调查 SubAgent 隔离噪声、通过验证报告披露未知,保护主上下文的干净与高效,让复杂工程的 AI 辅助研发具备可追溯、可核实的交付基础。
注:本文结合我的项目实践、思考与经验,由 AI 辅助整理,我负责把关和修改。如有错误,欢迎批评指正。
工程设计篇: