如果你已经在真实项目里试过 Agentic Coding大概率会遇到一个诡异的现象AI 明明能写单个函数也能解释复杂架构但只要让它“从一个空仓库开始独立完成一个中型功能”它往往会在第 20 分钟之后进入重复造轮子、改坏既有模块、忘记自己写过什么的状态。问题不在大模型的代码能力而在执行秩序。这也是 Wb-Flow 这类方案最值得关注的原因。它把 Agentic Coding 从一个“AI 单干到底”的线性叙事改造成“先规划、再分批并行执行”的工程流程。标题里的 Planned, Parallel Waves 三个词翻译成实际开发语言就是先把任务想清楚再用有节奏的并行波次去执行而不是让一个 Agent 蒙着头写到最后。这篇文章不打算只做名词解读。我会从为什么 Agentic Coding 需要“计划 并行波次”说起讲清楚它与传统单 Agent 模式的本质差异然后用一个可落地的示例设计一套极简 Wave 调度流程最后给出评估方法、常见坑和工程建议。1. 为什么说 Agentic Coding 的瓶颈是执行秩序先看一个真实感很强的场景。假设你给一个 coding agent 抛了这样一个需求给现有博客系统增加一个标签聚合页包含标签列表、按标签筛选文章、标签云展示。很多人第一次用 Agent 时会期待它一次性完成所有事。但实际运行时Agent 经常会这样做先新建了一个功能模块命名和项目现有目录风格不一致。接着为了“快速实现”自己定义了一套新的分页参数没看项目原来的分页拦截器。中途发现数据库查询需要关联表又顺手改了实体类结果破坏了另一个正在使用的查询方法。最后生成了十几个文件却没有跑一遍完整测试。这个过程的本质问题不是“代码质量低”而是线性执行缺少结构约束。单个 Agent 在执行长任务时上下文窗口是有限的记忆是易失的。它很难始终记得第 1 步的决定是否与第 50 步保持一致更严重的是当任务长度超过它的注意力范围后它可能为了完成当前子任务而推翻前面的设计。如果你把产品经理、前端、后端、测试分别交给四个独立的 Agent 去“自由协作”效果往往更差。因为 Agent 之间的沟通成本极高信息在传递过程中会丢失而且没有哪个 Agent 对全局负责。所以从近两年 Agentic Coding 的发展脉络看真正拉开差距的不是谁能生成更多代码而是谁能管住执行过程。Wb-Flow 的思路恰好是针对这个痛点在执行之前先有一个显式的计划然后把计划拆成若干波次每个波次内用并行 Agent 执行一批互相独立的子任务波次之间设置检查点逐批合并验证。2. 从 Copilot 到 Wave-basedAgentic Coding 的三个演进阶段为了理解 Planned, Parallel Waves 到底先进在哪里有必要先梳理一下 Agentic Coding 的演进路径。第一阶段单轮补全。以 GitHub Copilot 早期的行级/函数级补全为代表。开发者写一个函数开头模型补全剩余部分。这个阶段的核心特征是AI 是“输入法”人类是唯一的设计者和集成者。好处是可控坏处是效率提升有限只能在局部减少打字量。第二阶段线性长任务 Agent。以能够自主完成 issue 的 coding agent 为代表。你给 Agent 一个任务它自己决定读哪些文件、改哪些代码、跑哪些测试直到任务完成。这个阶段比补全前进了一大步因为 Agent 开始具备计划能力。但它的计划是隐式的、写在上下文里的并且整个执行过程是线性的一个 Agent 从头做到尾或者一个 Agent 调用多个工具串行执行。线性长任务 Agent 的真实问题是一旦任务规模超过单个上下文窗口的承载能力执行质量会随进度衰减。很多人在长任务中会观察到Agent 后面的改动经常与前面的设计矛盾。这就是上下文衰减和记忆遗忘在起作用。第三阶段计划驱动的并行波次执行。也就是 Wb-Flow 所代表的思路。核心变化有三点计划显式化。在执行开始前先生成一份任务计划这份计划不是 Agent 脑中的思路而是落在文件或数据模型里的结构化结果。任务分批化。所有子任务被组织成多个 Wave每个 Wave 内的任务尽量互相独立可以并行执行Wave 之间有先后依赖关系形成一道质量闸门。结果合并化。每个 Wave 执行完后统一合并代码、解决冲突、运行测试再进入下一个 Wave。下表总结了三个阶段的差异维度单轮补全线性长任务 AgentPlanned Parallel Waves计划方式无计划隐式、上下文内显式、结构化、先于执行执行单位单次生成单个 Agent 连续执行按 Wave 分批Wave 内并行控制节点无少靠 Agent 自觉多每 Wave 结束有检查点上下文压力极小随任务线性增长每个子任务独立上下文适合规模小函数、小改动中小型独立功能中型以上、多模块协作从这张表可以看出Wb-Flow 不是简单地“多 Agent 并行”这么浅。它把并行和计划放在一起核心是用工程管理的确定性来对抗大模型生成的不确定性。3. Wb-Flow 的核心概念Plan、Wave、Task、Merge要理解 Wb-Flow 的运作方式需要先熟悉四个核心概念Plan、Wave、Task 和 Merge。它们不是某个特定产品的专有名词而是一套通用方法论。3.1 Plan先于代码的显式计划Plan 是整个流程的起点也是与普通多 Agent 协作最大的不同。在传统多 Agent 协作里往往是你给一个主 Agent 下命令主 Agent 临时拆解任务给其他 Agent。而 Wb-Flow 的 Plan 是一个独立的、先行的产物它相当于工程里的“设计文档 任务拆解表”。一个合格的 Plan 至少包含本次迭代的目标和边界。涉及的文件、模块和接口。任务清单每个任务包含输入、输出、验收标准和依赖关系。任务的 Wave 归属即哪些任务可以在同一批并行执行。把 Plan 显式化的价值在于它让 Agent 不需要在漫长的执行过程中靠记忆维持全局认知。计划文件随时可以重新读取也可以被人类审查。这相当于给 Agent 的过程加了一个“外部记忆”。3.2 Task最小的可执行单元Task 是 Plan 的基本单位。一个 Task 应该具有以下特征边界清晰只改某一个模块或某几个相关文件。可验收有明确的完成标准比如“通过指定的单元测试”或“接口返回符合约定的 JSON 结构”。上下文可控Task 描述本身加上涉及的文件能够放进一个不算太大的上下文窗口。这是 Wave 并行能成立的前提。如果一个 Task 大到需要读二十个文件才能开始写代码说明拆分粒度有问题。最好的 Task 是“给足描述后Agent 只读 3-5 个文件就能完成”。3.3 Wave并行执行的批次Wave 是 Wb-Flow 最核心的组织单位。一个 Wave 包含一组 Task这些 Task 满足两个条件相互之间没有依赖。修改的文件尽量不重叠。一个 Wave 内的 Task 可以交给多个 Agent 并行执行。Wave 结束后所有改动汇入主干统一解决文件冲突和集成问题。通过后再开启下一个 Wave。这就把“并行”和“计划”绑在了一起。并行不是让很多 Agent 乱跑而是在计划阶段就识别出哪些任务可以安全并行。Wb-Flow 名称里的 Waves 暗示的正是这种“波次推进”第一波处理数据模型和核心接口第二波处理业务逻辑第三波处理页面和联调。每个波次像潮水一样推进一次只覆盖一片沙滩没有交叉。3.4 Merge波次之间的质量闸门每个 Wave 执行完并不等于结束必须经过 Merge 环节。Merge 不只是 git merge还包括检查代码风格和目录结构是否符合项目规范。运行受影响模块的单元测试和集成测试。审查文件冲突和重复定义。必要时回退不达标的 Task重新描述后再执行。Merge 是质量闸门也是 Wb-Flow 比自由多 Agent 更可靠的关键原因。因为它把不可控的“Agent 持续犯错”变成了可控的“每一波都校验一次”。4. 一个可落地的案例为博客系统增加标签聚合页理论讲完接下来用一个具体案例演示 Wb-Flow 的流程。假设你现在维护的是一个基于 Spring Boot Thymeleaf 的博客系统需要新增一个标签聚合页。需求描述如下标签列表页展示所有标签并显示每个标签下的文章数。标签详情页点击某个标签展示该标签下的文章列表支持分页。标签云在首页侧边栏展示热门标签。这是一个典型的中型功能涉及数据库表、MyBatis 映射、Service 层、Controller 层和前端页面。如果让单个 Agent 自由发挥很容易出现表结构设计不统一、分页参数风格不一致、前端页面风格与现有页面脱节等问题。使用 Wb-Flow 的思路流程可以这样设计。4.1 第一步生成 Plan先让规划 Agent 读取项目结构和现有代码风格生成一份 Markdown 格式的计划文件。# 标签聚合页实现计划 ## 目标 为博客系统增加标签列表页、标签详情页、首页侧边栏标签云。 ## 涉及模块 - 数据库blog.tags 表已有结构待确认 - MyBatisTagMapper、TagMapper.xml - ServiceTagService、TagServiceImpl - ControllerTagController - 页面tags.html、tag-detail.html、fragments/sidebar.html ## 代码风格约定 - Controller 返回视图名使用 ModelAndView。 - 分页参数统一为 page 和 size。 - 新 SQL 使用 XML 文件不使用注解 SQL。 ## 任务列表 ### Task-1 - 职责确认 tags 表结构补充 article_tag 关联表查询方法和 Tag 实体类字段。 - 涉及Tag.java、TagMapper.java、TagMapper.xml - 验收单元测试覆盖标签查询方法。 ### Task-2 - 职责实现 TagService 中的标签列表、标签详情、热门标签查询。 - 涉及TagService.java、TagServiceImpl.java - 验收Service 层测试通过。 ### Task-3 - 职责实现 TagController 的 /tags、/tags/{id}、/tags/hot 三个接口。 - 涉及TagController.java、相关 VO 类 - 验收接口返回正常视图和数据。 ### Task-4 - 职责编写 tags.html 和 tag-detail.html 页面。 - 涉及templates/tags.html、templates/tag-detail.html - 验收页面可访问样式与现有主题一致。 ### Task-5 - 职责修改首页侧边栏嵌入标签云。 - 涉及templates/fragments/sidebar.html、HomeController.java - 验收首页侧边栏显示标签云。 ## Wave 划分 - Wave 1Task-1 - Wave 2Task-2、Task-5 - Wave 3Task-3、Task-4这份 Plan 的关键是 Wave 划分。Task-1 必须先执行因为其他任务依赖 Tag 实体和 MapperTask-2 和 Task-5 不依赖对方可以并行Task-3 依赖 Task-2Task-4 依赖 Task-2但它们之间互不依赖也可以并行。4.2 第二步逐个 Wave 执行每个 Wave 的执行逻辑类似读取 Plan 中当前 Wave 的 Task 列表。为每个 Task 启动一个 Agent 实例。每个 Agent 独立读取相关文件并执行修改。Wave 结束后收集所有 diff 并合并。这里有一个容易被忽略的点Wave 内的 Agent 最好不要共享同一个工作目录否则容易互相覆盖文件。更稳妥的做法是各自在独立分支上完成修改Wave 结束时再统一合入主干。4.3 第三步Merge 与验证Wave 2 完成后应该运行 Service 层测试检查 TagService 和 sidebar fragment 是否同时正常。如果测试失败找出是 Task-2 和 Task-5 的改动冲突还是 Task-2 本身的实现问题。修复后再进入 Wave 3。这种“小步快跑 每波验证”的节奏比让一个 Agent 一口气完成五个 Task 更稳。原因很简单问题被限定在一个 Wave 的范围内排查成本直线下降。5. 核心实现一个极简 Wave 调度器演示代码理解了流程之后我们来看一眼如何用代码实现一个简单的 Wave 调度器。这里给出的是演示思路不绑定任何特定框架你可以根据自己的技术栈改造成 Python、Java 或 TypeScript 版本。5.1 定义 Task 和 Wave 的数据结构# executor/wave_model.py from enum import Enum from typing import List class TaskStatus(str, Enum): PENDING pending RUNNING running SUCCESS success FAILED failed class Task: def __init__(self, task_id: str, description: str, files: List[str], depends_on: List[str] None, wave: int 1): self.task_id task_id self.description description self.files files self.depends_on depends_on or [] self.wave wave self.status TaskStatus.PENDING self.result def to_prompt(self) - str: return f 你正在执行 Task {self.task_id}。 任务描述{self.description} 涉及文件{, .join(self.files)} 请严格按计划完成不要修改波及范围之外的文件。 这里需要注意depends_on字段。它决定了 Task 能否并行。Wave 调度器在计算可并行 Task 时只需要检查一个 Task 的依赖是否都已处于 SUCCESS 状态。5.2 调度器的核心循环# executor/scheduler.py from collections import defaultdict from concurrent.futures import ThreadPoolExecutor, as_completed from typing import List from executor.wave_model import Task, TaskStatus class WaveScheduler: def __init__(self, tasks: List[Task], max_workers: int 4): self.tasks tasks self.max_workers max_workers self.task_map {t.task_id: t for t in tasks} self.wave_tasks defaultdict(list) for t in tasks: self.wave_tasks[t.wave].append(t) def ready_tasks(self, wave_tasks: List[Task]) - List[Task]: 判断哪些 Task 可以并行执行 1. 状态为 PENDING 2. 所有前置 Task 已成功 ready [] for task in wave_tasks: if task.status ! TaskStatus.PENDING: continue deps_ok all( self.task_map[d].status TaskStatus.SUCCESS for d in task.depends_on if d in self.task_map ) if deps_ok: ready.append(task) return ready def run_one_task(self, task: Task, agent_executor) - None: 实际执行单个 Task。agent_executor 可以是任何 coding agent 客户端。 task.status TaskStatus.RUNNING try: result agent_executor.execute(task.to_prompt()) task.result result task.status TaskStatus.SUCCESS except Exception as e: task.result str(e) task.status TaskStatus.FAILED def run(self, agent_executor) - None: 按 Wave 顺序执行。 每个 Wave 内部通过 ThreadPoolExecutor 并行执行互相独立的 Task。 wave_ids sorted(self.wave_tasks.keys()) for wave_id in wave_ids: print(f 开始执行 Wave {wave_id} ) current_tasks self.wave_tasks[wave_id] while True: ready self.ready_tasks(current_tasks) if not ready: break with ThreadPoolExecutor(max_workersself.max_workers) as pool: futures { pool.submit(self.run_one_task, task, agent_executor): task for task in ready } for future in as_completed(futures): task futures[future] # 这里可以在 future.result() 里捕获异常 future.result() # Wave 内的所有任务都结束后进入 Merge/验证阶段 self.merge_and_verify(wave_id) def merge_and_verify(self, wave_id: int) - None: 合并当前 Wave 的分支到主干并运行测试。 实际项目中这里可以调用 git merge、mvn test 等命令。 print(f--- Wave {wave_id} 合并验证 ---) # TODO: 按项目实际流程补充合并分支、运行测试、回滚失败任务这个调度器把 Wave 的执行流程还原得很直白外层按 wave 顺序内层通过ready_tasks识别可并行的 Task再用线程池并发执行。agent_executor是一个抽象接口实际使用时可换成 Claude Code、OpenHands、Cline 等任意 coding agent 的命令行客户端或 SDK。5.3 如何对接一个真实的 Coding Agent为了让上面的调度器真正跑起来需要一个agent_executor。以常见的命令行 Agent 为例可以写一个适配器通过子进程调用 Agent 的 CLI# executor/agent_adapter.py import subprocess from typing import List class AgentClient: 对 coding agent 的命令行封装演示用。 def __init__(self, command: List[str], workspace: str): self.command command self.workspace workspace def execute(self, prompt: str) - str: # 这里只是演示思路实际需要处理工作目录和超时。 process subprocess.run( self.command [prompt], cwdself.workspace, textTrue, capture_outputTrue, timeout600, ) return process.stdout需要提醒的是不同 Coding Agent 的 CLI 参数完全不同。有的支持直接传 prompt有的需要先建 issue 再执行。上面的代码只是演示“适配器”这一层应该存在实际接入时请以你所用工具的文档为准。6. 效果验证怎么判断 Wave 模式比线性模式更好很多人问怎么证明这种“计划 并行波次”真的更有效我的建议是不要靠感觉而是建立一组可对比的指标。6.1 衡量维度和指标指标线性模式表现Wave 模式期望表现如何采集首次通过率低于 30%常常需要多次修复提示每个 Task 独立验收失败可快速替换记录每个 Task 首次执行是否通过文件冲突数长任务后段容易重复修改早期文件Wave 内独立、Wave 间隔离冲突显著减少git diff后统计冲突文件数上下文 token 消耗单个 Agent 持续消耗很多 token 浪费在重复读取子任务上下文独立避免重复记忆统计 Agent 客户端日志平均修复轮次长任务晚期 Bug 修复成本高问题被限制在 Wave 内修复成本低记录每次失败到成功的交互轮数这组指标不复杂但能反映真实差异。尤其是“文件冲突数”在传统单 Agent 长任务里几乎是必然上升的指标。Wb-Flow 通过任务拆分和 Wave 隔离从结构上压低了冲突概率。6.2 一个可复用的实验设计如果你想在团队里验证这个思路可以选一个中等规模 issue用同样的需求分别跑两条流水线一条是单 Agent 直接处理一条是 Wb-Flow 式 Wave 调度。对比以下三个结果最终代码是否通过全部测试。整个过程的耗时。人工介入审查的次数。这个实验不需要很精确能看出趋势就可以。从实际经验看任务越杂、涉及文件越多Wave 模式的优势越明显反之如果只是一个几十行的独立小函数单 Agent 更直接Wb-Flow 反而显得重。7. 常见问题与排查思路在落地 Wb-Flow 的过程中会遇到几个高频问题。下面按现象、原因、排查方式、解决方案整理成表格。问题现象可能原因排查方式解决方案Wave 内并行修改后发生大量重复代码两个 Task 的边界划分不清晰职责有重叠对比两个 Task 的输入输出和涉及文件集合拆分 Task 时遵循“一个 Task 只改一条业务链路”原则Wave 2 等待 Wave 1 太久Wave 1 里的第二个 Task 与 Wave 2 没有依赖却被人为排到了前一个 Wave检查 Plan 中 Task 的 depends_on 关系用更细粒度的依赖关系重组 Wave而不是按业务模块一刀切Agent 在某个 Task 上反复失败Task 描述不清楚Agent 猜不到项目的既有约定查看 Agent 的中间日志和任务描述在 Task 描述中补充代码风格、参考文件和反例合并后测试大面积失败Wave 内虽然并行成功但两个 Agent 同时改了同一个公共类检查 git blame 确认冲突来源在 Task 拆解时识别公共文件依赖把公共类改动单独放一个 Wave总 Token 消耗没有下降每个 Agent 都独立读了一遍同一个大文件查看日志中重复读取的文件优先把只读文件提取到公共上下文或让 Task 描述里直接给出关键代码片段并行度开太高机器卡死同时运行了太多 Agent 进程查看系统 CPU 和内存占用限制 max_workers建议从 2-3 开始逐步调大这里最值得警惕的是“公共文件依赖”。很多 Agentic Coding 项目失败不是 AI 能力问题而是多个并发任务同时改一个公共模块造成不可调和的冲突。Wb-Flow 的解法是在规划阶段检测 Task 间的文件重叠度如果重叠度高于阈值就改变 Wave 顺序或调整 Task 边界。8. 最佳实践与工程建议Wb-Flow 的落地不仅是一个工具使用问题更是一套工程习惯的调整。以下是几条在项目中验证过有效的建议。8.1 先读懂项目再让 Agent 规划不要让 Agent 从零开始猜架构。在生成 Plan 前先让规划 Agent 读取项目的 README、目录结构、核心模块代码甚至让它在主分支上跑一次现有测试。一个不了解全局的规划 Agent 产出的 Plan会把 Wave 切分得完全不落地。比较实用的做法是准备一份“项目概览文档”内容包括技术栈、目录说明、编码规范、典型代码片段。这个文档既是人类新手的入职手册也是 Agent 的规划上下文。8.2 Task 描述要包含验收条件而不是只有目标弱 Task 描述“实现标签分页查询。”这个描述太含糊Agent 不知道该返回什么结构也不知道分页边界在哪里。强 Task 描述实现 TagService 中的 pageArticlesByTag(String tagName, int page, int size) 方法。 - 入参page 从 1 开始size 默认 10最大不超过 50。 - 出参PageResultArticleVO包含 total、page、size、records 字段。 - 数据来源article_tag 关联表status 1 的文章才计数。 - 失败场景标签不存在时返回空记录不抛异常。 - 参考实现可参考项目中 CategoryService 的分页写法。 验收条件TagServiceTest 中新增三个测试用例分别覆盖正常分页、空数据、越界分页。这种描述虽然长但极大降低了 Agent 的试错成本。它把“判断如何实现”变成了“按约定实现”这正是 Wave 模式高效运转的前提。8.3 用中间计划文件替代 Agent 的短期记忆很多 Agent 之所以在长任务中断裂是因为计划只存在于上下文窗口里。Wb-Flow 提倡把计划落成文件Agent 每执行一个 Task 前都可以重新读取。这样即使上下文被其他信息冲掉Agent 也能重新建立全局认知。实践中我会把 Plan 文件放在docs/plans/目录下按日期命名。Wave 执行完后更新计划文件中的 Task 状态。这样人类可以随时查看进展Agent 也不会“失忆”。8.4 并行度不是越高越好并行 Agent 的数量取决于三个因素任务的独立性、机器的算力、上下文的成本。从实际项目看同一时间并行 2-4 个 Agent 是比较舒适的区间。超过这个数量合并冲突和机器资源都会变成新的瓶颈。另外并行度要动态调整。Wave 1 任务简单可以开 3 个并行Wave 3 任务互相有隐性耦合就该降为串行执行或者拆得更碎再做并行。8.5 建立每个 Wave 的回滚能力Wave 执行不可能永远一次通过。比较稳妥的做法是每个 Agent 在独立分支上工作。Wave 合并前先记录当前主干的基线 commit。合并后如果测试失败优先回滚到基线再决定是修复还是重新执行。这比“在错误代码上打补丁”更安全。对于生产仓库还要加一层保护Wave 合并流程只能在受保护的分支策略下进行合并必须经过 CI 检查。8.6 安全与权限边界不能因为 Agent 而放松Coding Agent 本质上是一个可以读写文件、执行命令的程序因此在团队落地时要特别强调安全底座使用最小权限的本地账号运行 Agent避免直接用管理员账号。数据库操作语句必须限定在测试库禁止在未授权情况下连接生产库。涉及删除、批量更新、表结构变更的 Task应在计划阶段单独标注“需人工审批”。Agent 执行的命令应记录日志便于审计。这些要求看起来是老生常谈但在 Agent 自动执行的环境里更容易被忽视。建议在 Wave 调度器的merge_and_verify阶段显式检查本次 Wave 涉及的 SQL 和命令是否包含危险操作。9. 总结与后续学习方向Wb-Flow 给我最大的启发不是“用了这个就能让 AI 包办一切”而是它重新划定了人与 AI 在编码协作中的边界。过去的 Agentic Coding 强调“AI 独立完成任务”Wb-Flow 则更接近一种工程管理方法人类负责定义目标和验收条件Agent 负责在受限的 Wave 内并行执行双方通过计划文件和 Merge 闸门协作。如果你现在正在被 Coding Agent 的“长任务失控”困扰我建议你按以下路径实践第一步先选一个中等规模的独立功能尝试把它拆成至少 5 个 Task。第二步思考哪些 Task 可以并行哪些 Task 之间存在文件级依赖。第三步按 Wave 顺序执行并在每个 Wave 后跑测试。第四步记录每个 Task 的首次成功率、修复轮次和 Token 消耗建立自己的指标基线。第五步根据指标优化 Task 拆解粒度形成适用于你自己项目的“Wave 拆分经验”。更进一步可以研究 Agent 工具中显式的 Planning 模块、多 Agent 通信协议、以及基于文件依赖图的任务调度算法。这些都是 Wb-Flow 理念背后的真实技术基础比单纯追新工具更有长期价值。需要记住的是任何 Agentic Coding 方法都不能替代对项目架构的理解。Plan 拆得好不好取决于你是否真正了解哪些模块可以独立演进、哪些层必须强一致。从这个角度看Wb-Flow 提升的不仅是 AI 写代码的效率也在倒逼开发团队把架构边界设计得更清晰。架构混乱的项目无论用不用 WaveAgent 都会在某个时刻把混乱放大。如果你打算在下一个迭代里尝试 Wb-Flow建议先从非关键业务模块做起准备好分支回滚策略再逐步扩大使用范围。毕竟工具可以激进生产环境必须保守。