AI 编程工作流的设计:串行验证设计

775 阅读23分钟

在日常研发中,直接向大模型输入“帮我实现这个功能”或“修复这个 Bug”,往往会陷入“生成代码 → 发现需求或技术方案偏差、编译报错 → 修正偏差和错误 → 完成本轮开发”的循环。如何提高一轮任务的完成质量,减少反复返工?这些问题的根源在于:缺少必要的上下文约束、缺乏明确的决策边界,以及模型在自审时难以克服的“确认偏误”(Confirmation Bias)。

本文分享我在设计 AI 研发工作流(dev-workflow 与 bugfix-workflow)时的一些心得,重点讨论流程中的决策链构建、状态机约束、Agent 角色分工,以及如何在复杂工程中组织主 Agent、独立 Agent 与 SubAgent 协同工作。


一、为什么需要结构化工作流?

在复杂工程中,编写代码只是整个研发链路的末端。未理清需求背景与边界就直接编码,极易导致设计偏离。因此,我们的工作流划分为明确的几个阶段,每个阶段对应特定的角色与责任:

download1.png

阶段与角色定义

阶段角色核心职责在完整流程中的作用
Phase 0Context Analyst梳理已有需求、相关代码关系及外部依赖(如硬件协议、接口规范)补全容易遗忘的需求细节,减少模型幻觉与上下文遗漏
Phase 1Planner设计状态流、定义模块边界、制定技术方案与验收标准在动代码前确认关键决策,确保实现路径透明
Phase 2Coder按照已确认的方案编写或重构代码严格在限制的工程范围内修改,禁止超出方案随意发挥
Phase 3Reviewer独立检查代码 Diff,审查竞态条件、内存泄漏与边界异常打破“自写自审”的思维定势,提供客观审查视角
Phase 4Tester对照验收标准执行静态检查、核对现有证据并列出必要的人工验证项依靠客观证据而非“看起来没问题”的假设来确认交付
Phase 5Delivery 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 --> [*]: 汇总交付与归档

阻断机制的三条硬性规则

  1. 关键决策分别放行:背景确认后才能规划,方案确认后才能编码,实现结果经人工放行后才能进入独立审查。每次放行只允许进入当前关卡对应的下一阶段,不能一次确认就跨过后续 Gate。背景充分、用户补充了信息或没有回复,都不能视为放行。
  2. 审查与验证失败次数上限:Phase 3 与 Phase 4 分别记录连续失败次数,达到 3 次时强制暂停,交由人类工程师干预;返修不重置次数。人工选择“重试”只增加一轮修复与复核机会,仍未通过就停回原失败关卡;选择“跳过”则保留已知问题与未满足的验收标准,不能把跳过写成通过。
  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 消耗与交接成本。合理的分工有助于在可控的协作成本下,获得更可靠的结果:

  1. 精准交接,禁止全量复制: 主 Agent 委派 SubAgent 或独立 Agent 时,传递目标、必要背景、约束条件、相关代码与 Diff、结构化契约,避免把数万行历史对话全文透传。必要背景应足以理解任务,精简上下文不能以遗漏需求边界为代价。
  2. 只返回事实摘要,不返回原始探索过程: 子 Agent 在解析了大量日志或进行了多轮代码检索后,只向主 Agent 返回结构化的结论与关键证据(如文件行号、关键日志原文),并注明事实、推断与未知。原始探索资料保留在子上下文或调查记录中,便于主 Agent 按需回查。
  3. 按需启用,避免过度设计:
    • 单 Agent 即可处理的轻量任务:无需进入完整研发流程的机械性单文件修改、局部 UI 文案调整或短日志解读,可以由主 Agent 直接完成;不必为了角色齐全而额外拆分任务。
    • 开启多 Agent 协同:进入本文两条结构化工作流时,Phase 3 保留独立 Reviewer;额外的调查 SubAgent 则按需启用,例如需要关联多次运行的日志、还原复杂时序,或跨多个独立领域(如 API 契约与底层通信协议)展开调查。是否委派取决于工作量与任务独立性,不按日志行数机械划分。

六、工作流需要 Skill 配合

工作流规定了开发任务如何推进,但在Coder编码过程中,怎样产出符合项目封装与规范的代码?这就需要从项目实践中抽取出详细、实用的各类基础 Skill,把这些基础工作做扎实。

Skill 的封装,可以理解为把程序员的项目经验提炼成 AI 能执行的指引。例如,项目中弹窗应该怎么写,程序员知道,就可以封装成 Skill,让 AI 也知道。AI 读源码或许也能找到答案,但既耗时,也可能绕过项目已有封装,重新采用更底层的实现方式。

Android 领域常见的 Skill 有:

  1. 新页面初始化(如 base-new-page):告诉 AI 新建页面时需要完成哪些工作,以及应该复用哪些基础能力。
  2. UI 转代码(如 figma-to-compose):告诉 AI 如何将 Figma 设计稿转换为符合项目规范的 Compose 代码。
  3. 接口转网络请求(如 api-to-request):告诉 AI 如何接入接口。单个请求、串行请求、并发请求的处理方式不同,可以按场景拆分 Skill。
  4. 页面弹窗:确认框、底部弹窗、全局弹窗等,已经形成项目规范的做法都可以沉淀为 Skill。
  5. 其他常见场景:下拉刷新与上拉加载、Adapter 编写、代码自检、页面卡顿分析等。

AI 越来越聪明,Skill 不必重复所有通用编程知识。更实用的原则是:当 AI 出错,或产出的代码不符合工程师预期时,把可复用的项目规则和经验沉淀下来作为新的skill,减少下一次出现同类偏差。

这正是项目 Skill 的价值。


七、总结

结构化工作流的核心,在于把对 AI 的信任建立在制度和约束上,而不是大模型的偶然表现上。

  1. 通过分阶段角色与阻断状态机,把控需求到代码的每一个决策点,用确定性对抗模型的随意性。
  2. 通过主 Agent 贯穿 + 独立 Agent 审查,维持任务的整体连贯,并降低模型自我确认偏误带来的遗漏。
  3. 通过明确的输入、交付物和返修路径,让各类 Agent 的职责形成闭环,确保“背景—方案—实现—验证”始终围绕同一个目标。
  4. 通过证据调查 SubAgent 隔离噪声、通过验证报告披露未知,保护主上下文的干净与高效,让复杂工程的 AI 辅助研发具备可追溯、可核实的交付基础。

注:本文结合我的项目实践、思考与经验,由 AI 辅助整理,我负责把关和修改。如有错误,欢迎批评指正。

工程设计篇:

《AI编程工作流的设计:串行验证设计》

《AI编程工作流的设计:并行协作设计》

《AI编程工作流的设计:从人工判断到AI裁判》