Wb-Flow：计划先行与并行波次的Agentic Coding协作模式

Agentic Coding 正在从“单轮对话生成代码”走向“多 Agent 协作完成工程任务”，这已经不是一个新鲜概念。但真正把 Agentic Coding 落地到项目里，很多人会发现几个恼人的问题：Agent 写代码水平不稳定、任务一复杂就丢失上下文、多个任务同时推进时互相覆盖代码、代码评审阶段来回返工。本文要聊的 Wb-Flow，正是针对这些问题提出的一种“计划先行 + 并行波次”的 Agentic Coding 协作模式。

本文将围绕 Wb-Flow 的核心思想展开，先讲清楚 Agentic Coding 的背景和痛点，再拆解 Planned（计划驱动）与 Parallel Waves（并行波次）的含义，然后给出一个可落地的工程示例，包括任务规划文档、Wave 拆分规则、代码示例和运行验证流程，最后补充常见问题和最佳实践。无论你是刚开始接触 AI 编程的开发者，还是已经在团队中尝试 Agent 协作的技术负责人，这篇文章都值得读完。

1. 背景与核心概念

1.1 什么是 Agentic Coding

Agentic Coding 指的是让具备代码生成与执行能力的 AI Agent 参与软件开发的编码、测试、修复、重构等环节。与传统的“AI 补全代码”或“单次对话生成代码”不同，Agentic Coding 强调的是 Agent 能够在较长任务链路中自主规划、执行、检查结果，并根据反馈调整后续动作。用一个更贴近工程的说法来解释：普通的 AI 编程工具像是“高级的自动补全器”，你给它一个函数签名的上下文，它帮你补出函数体；而 Agentic Coding 更像是“一个能独立消化需求、拆解任务、写出完整代码模块、并自己跑测试修 bug 的初级开发工程师”。

这个能力听起来很理想，但实际使用中，Agent 的“自主性”往往伴随着不可控性。比如，一个 Agent 在生成 API 接口时，可能同时修改了数据库表结构文件；另一个 Agent 在处理前端组件时，无意中删除了公共工具函数。当多个任务并行推进时，这种不可控性会被放大。Agentic Coding 的真正难点，不是让 Agent 写代码，而是让多个 Agent 在同一个代码库中安全、有序地协作。

1.2 为什么 Agent 协作需要“计划性”

如果让一个 Agent 独立完成一个中等规模的功能，比如“给现有系统增加一个用户积分模块”，它通常能给出一个看似合理的实现。但在团队协作中，这个功能可能涉及数据库迁移、后端接口、前端页面、权限配置、日志埋点等多个改动点。如果没有一个统一的计划，Agent 可能会做出以下行为：

• 刚开始写接口，就顺手改了数据库表结构，导致其他模块报错。
• 只实现了代码，没有考虑异常处理和日志，评审时被打回。
• 生成了大量无用代码，污染代码库。
• 中途发现需求理解偏差，但已经写了一半，返工成本很高。

“计划性”的含义是：在 Agent 动手写代码之前，先通过规划阶段生成一个结构化的任务清单，明确每个任务的范围、依赖关系、输入输出、验收标准。这样，Agent 的执行路径就从“自由发挥”变成了“按计划交付”。这与人类开发者的工作方式本质上是一致的——先画架构图，再写任务书，最后才写代码。

1.3 什么是“Wb-Flow”中的 Parallel Waves

Wb-Flow 的核心特色在于 Parallel Waves，即并行波次。简单来说，就是把一个大型开发任务拆解为多个相互独立的“波次”，每个波次包含一组可以并行执行的任务。波次与波次之间保留严格的先后顺序，波次内部的多个任务则由多个 Agent 并行处理。

用一个类比来理解：如果把一个大型项目比作盖一栋楼，传统的 Agentic Coding 是“一个施工队从一楼往二楼盖，盖完一间再盖下一间”；而 Wb-Flow 的并行波次则是“第一波先打地基和搭框架，第二波同时做水电和砌墙，第三波做装修和验收”。每一波任务都基于上一波完成后的稳定状态，内部又可以并行推进，从而在不牺牲代码质量的前提下，大幅提高整体开发速度。

这种模式的精妙之处在于，它同时解决了两个问题：

• Agent 并行协作时的冲突问题：由于同一波次内任务已经在规划时确认彼此独立，Agent 之间不会抢改同一个文件。
• 上下文丢失问题：Agent 只需要专注于当前波次的任务上下文，不需要在长对话中一直记住整个项目的历史，降低了上下文遗忘的风险。

1.4 Wb-Flow 适用场景

Wb-Flow 并非适合所有场景，它尤其适合以下类型的项目：

• 模块边界清晰的中大型项目，比如微服务架构下的新服务开发。
• 需求可以明确拆分为功能点的迭代任务。
• 多 Agent 协作环境中需要统一节奏的团队。
• 需要控制 AI 生成代码质量的严肃项目，而非一次性脚本。

如果是“写一个冒泡排序算法”这种单文件任务，Wb-Flow 反而显得笨重。它的价值体现在“任务足够复杂、涉及文件足够多、并行需求足够强烈”的场景中。

2. 核心思想拆解：Planned 与 Parallel Waves

2.1 计划先行：Wb-Flow 的 Planning 阶段

在 Wb-Flow 模式下，任何代码生成动作之前都有一个规划阶段。这个阶段的目标不是生成代码，而是生成一份“开发计划书”。规划阶段通常包括以下步骤：

• 需求解析：将用户输入的自然语言需求解析为结构化描述。
• 影响面分析：分析需求涉及的后端服务、数据库表、前端页面、配置项。
• 任务拆分：将开发工作拆分为粒度适中的任务，每个任务有明确的负责人（某个 Agent）、输入、输出、验收标准。
• 依赖排序：梳理任务之间的依赖关系，形成有向无环图（DAG）。
• 波次划分：根据依赖关系，把任务分配到不同的 Wave（波次）中。

这个阶段的最大价值在于，它把“写代码”这个模糊的动作，变成了“执行计划”这个确定性的流程。比如，规划结果可能是这样的：

2.2 并行波次的运行机制

当规划完成、波次划分清晰之后，就进入执行阶段。执行阶段遵循一条重要规则：只有当前波次的所有任务全部完成并通过验证，才能进入下一个波次。在当前波次中，多个 Agent 可以并行工作，但每个 Agent 只操作自己被分配的任务文件，不允许越界修改其他 Agent 涉及的文件。

波次执行时还需要考虑以下细节：

• 文件锁定：在 Agent 开始任务前，确认任务涉及的文件没有与其他任务重叠。
• 构建验证：每个任务完成后，触发增量构建或单元测试，确保改动没有破坏现有功能。
• 进度同步：当本波次任务全部完成后，合并代码、解决冲突、统一运行测试，再开始下一波。

这种机制让并行变得“安全”。Agent 之间不需要频繁通信，因为不必要的通信本身就是上下文丢失和冲突的来源。它们只需要遵循一个简单的规则：自己的波次内，按计划完成任务，验证通过后等待同步点。

2.3 波次与波次之间的依赖传递

波次之间的依赖传递是 Wb-Flow 设计的精髓。假设 Wave 1 的任务是数据库表设计和接口契约定义，Wave 2 的任务是后端实现和前端实现。Wave 2 的 Agent 在开工前，会拿到 Wave 1 的产出物——完整的表结构文档和接口定义。这样，后端 Agent 和前端 Agent 在执行时，依据的是同一份契约，不会出现“后端返回userId，前端期待user_id”这种低级但对齐成本极高的问题。

这也意味着，Wb-Flow 与传统“一个 Agent 从头干到尾”的模式有本质区别：Agent 的使用方式从“长链路自主决策”变成了“短链路按计划执行 + 全局计划由人/规划器掌控”。这种模式下，单个 Agent 的决策负担反而更轻，出错概率更低。

3. 环境准备与版本说明

3.1 运行时环境

Wb-Flow 是一种工作流模式，而不是一个具体的软件工具，因此运行环境相对灵活。以一个典型的 Python 后端项目为例，环境准备如下：

• 操作系统：macOS / Linux / Windows（建议使用 Linux 或 macOS，Shell 脚本兼容性更好）。
• Python 版本：3.10 及以上。
• 包管理工具：pip 或 Poetry。
• 代码托管：Git，建议使用 trunk-based 分支策略或短生命周期特性分支。
• AI Agent 工具：支持命令行调用的代码生成 Agent，例如 GitHub Copilot CLI、Codex CLI，或自己开发的 Agent 脚本。版本需要根据你的项目实际情况调整，本文示例以常见环境为例，重点演示配置思路。

3.2 项目结构示例

wb-flow-demo/ ├── docs/ │ ├── plan.md # 规划阶段生成的开发计划 │ ├── contract.md # 接口契约定义 │ └── db-schema.md # 数据库表结构设计 ├── src/ │ ├── models/ # 数据模型 │ ├── services/ # 业务逻辑 │ └── api/ # 接口层 ├── tests/ │ ├── unit/ # 单元测试 │ └── integration/ # 集成测试 ├── waves/ │ ├── wave1.sh # 第一波并行任务脚本 │ ├── wave2.sh # 第二波并行任务脚本 │ └── wave3.sh # 第三波并行任务脚本 └── README.md

这个结构将规划文档、任务脚本和代码分离开来，便于多 Agent 协作时快速定位各自的工作范围。

3.3 版本说明

以下工具版本是示例配置，实际使用时请根据项目情况调整：

python=3.10.x pytest=7.x fastapi=0.100.x git=2.x

版本管理的核心原则是：Agent 生成代码前，需要明确知道当前项目的依赖环境，避免生成使用新语法但环境不支持的代码。在 Wb-Flow 规划阶段，应该把依赖版本写入pyproject.toml或requirements.txt，并作为规划文档的附件传给 Agent。

4. 从规划到落地的完整实战案例

下面我们通过一个具体的小型项目来演示 Wb-Flow 的完整流程。项目需求是：开发一个简单的“任务管理 API 服务”，提供任务的创建、查询、完成状态更新功能。整体流程分为规划阶段、Wave 执行阶段和验证阶段。

4.1 规划阶段的产物：开发计划书

在项目启动时，规划器（可以是人工，也可以是一个编排 Agent）生成如下计划文件。

# docs/plan.md ## 需求概述 实现一个任务管理 API，支持创建任务、查询任务列表、更新任务完成状态。 ## 任务拆分 ### T001：设计数据库模型 - 文件：src/models/task.py - 验收标准：Task 模型包含 id、title、status、created_at 字段 - 波次：Wave 1 ### T002：定义 API 契约 - 文件：docs/contract.md - 验收标准：使用 OpenAPI 描述三个接口 - 波次：Wave 1 ### T003：实现任务 CRUD 接口 - 文件：src/api/tasks.py - 依赖：T001, T002 - 验收标准：三个接口均可调用，单元测试通过 - 波次：Wave 2 ### T004：补充集成测试 - 文件：tests/integration/test_tasks.py - 依赖：T003 - 验收标准：集成测试覆盖创建、查询、更新流程 - 波次：Wave 3 ## 波次划分 - Wave 1：T001, T002（并行） - Wave 2：T003（单一任务，因为强依赖前两个） - Wave 3：T004（验证波次）

4.2 Wave 1：数据库模型与接口契约并行

Wave 1 包含 T001 和 T002 两个并行任务，分别交给两个独立 Agent 完成。它们操作的文件完全不同：T001 操作src/models/task.py，T002 操作docs/contract.md，因此不会产生文件冲突。

Agent A 负责 T001，产出文件如下：

# 文件路径：src/models/task.py from datetime import datetime from sqlalchemy import Boolean, DateTime, String from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column class Base(DeclarativeBase): pass class Task(Base): __tablename__ = "tasks" id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True) title: Mapped[str] = mapped_column(String(128), nullable=False) status: Mapped[str] = mapped_column(String(32), default="pending") is_active: Mapped[bool] = mapped_column(Boolean, default=True) created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)

Agent B 负责 T002，产出文件如下：

# docs/contract.md ## 创建任务 POST /api/tasks 请求体：{"title": "string"} 响应：{"id": 1, "title": "string", "status": "pending"} 状态码：201 ## 查询任务列表 GET /api/tasks 响应：[{"id": 1, "title": "string", "status": "pending"}] 状态码：200 ## 更新任务状态 PATCH /api/tasks/{task_id} 请求体：{"status": "completed"} 响应：{"id": 1, "title": "string", "status": "completed"} 状态码：200

Wave 1 验证：两个任务都完成后，合并代码并运行数据模型的基础测试。注意，这一阶段不要求实现完整接口，只要求两个产出物本身是正确、可用的。

4.3 Wave 2：后端接口实现

Wave 1 完成后，Wave 2 的任务 T003 开始执行。Agent 在开工前会读取两个产出物：src/models/task.py和docs/contract.md。这使得它不需要重新理解需求，只需要按照契约实现代码。

# 文件路径：src/api/tasks.py from fastapi import APIRouter, Depends, HTTPException from sqlalchemy.orm import Session from src.models.task import Task router = APIRouter(prefix="/api/tasks", tags=["tasks"]) def get_db(): """实际项目中应替换为数据库连接管理，这里仅做演示。""" raise NotImplementedError @router.post("", status_code=201) def create_task(title: str, db: Session = Depends(get_db)): if not title: raise HTTPException(status_code=400, detail="title is required") task = Task(title=title, status="pending") db.add(task) db.commit() db.refresh(task) return task @router.get("", status_code=200) def list_tasks(db: Session = Depends(get_db)): return db.query(Task).filter(Task.is_active == True).all() @router.patch("/{task_id}", status_code=200) def update_task_status(task_id: int, status: str, db: Session = Depends(get_db)): task = db.get(Task, task_id) if not task: raise HTTPException(status_code=404, detail="task not found") task.status = status db.commit() db.refresh(task) return task

这段代码严格按照docs/contract.md中的路径和字段实现。这里给出的是核心片段，需要放入src/api/tasks.py文件，并根据你的实际数据库配置替换get_db实现。

Wave 2 验证：运行单元测试，验证三个接口的请求和响应结构与契约一致。

4.4 Wave 3：集成测试与收尾

最后一个波次的任务 T004 是补集成测试，验证整个流程是否通畅。

# 文件路径：tests/integration/test_tasks.py def test_full_flow(): # 1. 创建任务 # 2. 查询任务列表 # 3. 更新任务状态 # 4. 断言状态更新成功 pass

集成测试代码中先不写死数据库配置，而是采用 mock 或测试数据库，这样既不会污染开发环境，也能验证核心链路。

4.5 运行与验证

在项目根目录依次执行：

# 安装依赖 pip install -r requirements.txt # 运行单元测试 pytest tests/unit -v # 运行集成测试 pytest tests/integration -v # 启动服务（本地开发模式） uvicorn src.main:app --reload

预期输出：

tests/unit/test_models.py .... [100%] tests/integration/test_tasks.py ... [100%]

在 Agentic Coding 场景下，这三个波次的执行可以理解为：wave1.sh 同时触发两个 Agent，wave2.sh 触发一个 Agent，wave3.sh 触发一个验证 Agent。每个波次脚本执行结束后，检查测试结果，只有通过才进入下一波。

5. 常见问题与排查思路

Wb-Flow 在落地过程中，最常见的坑往往不在 Agent 本身，而在流程设计和工作区管理。下面整理一份高频问题对照表。

5.1 任务冲突的排查流程

如果出现任务冲突，可以按以下顺序排查：

1. 打开plan.md，对比产生冲突的两个任务是否触碰了相同文件。
2. 检查两个 Agent 的起始 prompt 中是否包含了同样的“全局修改”指令（例如“优化所有代码风格”），这种指令是冲突的常见来源。
3. 检查 Git 日志，定位冲突文件的修改顺序。
4. 撤销其中一个 Agent 的修改，重新独立执行。

5.2 上下文丢失的排查清单

如果 Agent 在 Wave 2 执行时“忘记”了 Wave 1 的内容，先不要急着怪 Agent 的记忆力。检查以下两点：

• Wave 1 的产出物是否进入了 Agent 的上下文？如果任务依赖的是docs/contract.md，那么这个文件路径是否写入了该 Agent 的任务描述中？
• Agent 的执行环境是否有共享文件系统？如果没有，Wave 1 的产出物不会自动出现在 Wave 2 的工作目录中，需要显式传递。

上下文丢失的本质不是“AI 记忆差”，而是任务的输入输出没有形成清晰的契约。Wb-Flow 通过文档化的产物传递来规避这个问题。

6. 最佳实践与工程建议

6.1 任务拆分遵循“文件级隔离”原则

在规划阶段，任务拆分的核心不是“功能是否独立”，而是“文件是否重叠”。两个功能不同但都修改config.py的任务，不能放在同一个 Wave 中并行执行。反过来，两个功能相关但操作完全不同文件的任务，则非常适合并行。因此，规划阶段一定要生成任务与文件的映射表，并在分配到 Wave 之前进行重叠检查。

6.2 每个 Wave 结束后的“同步点”必须固定落产物

同步点可以理解为人类开发中的“提测节点”。Wb-Flow 中，每个 Wave 结束后必须做以下四件事：

1. 合并本波次所有 Agent 的代码。
2. 运行全部单元测试和构建脚本。
3. 更新docs/下的变更记录，将产物更新到共享目录。
4. 只有全部通过，才允许进入下一个 Wave。

不要为了省时间跳过同步点。跳过同步点的代价，通常会在后面一个 Wave 中以数十倍的时间被追回。

6.3 给 Agent 明确的行为边界

在给 Agent 的 prompt 中，除了描述“要做什么”，还必须明确“不要做什么”。例如：

你是 Wave 2 的后端开发 Agent，你的任务是实现 src/api/tasks.py。 你可以读取 src/models/task.py 和 docs/contract.md。 你不允许修改 src/models/ 下的文件，不允许创建新文件，不允许变更依赖版本。

这种边界约束能有效降低 Agent 的“自由发挥”概率。也可以把这段约束写入项目根目录的AGENT_RULES.md，在每次启动 Agent 前自动加载。

6.4 规划文档与代码保持同步

docs/plan.md不是一次性文件。当某个 Wave 执行中发现计划不合理时，应该先修改计划，再让 Agent 继续执行，而不是直接用对话让 Agent“顺便改一下别的地方”。计划文档是 Agent 之间唯一的共享事实来源（single source of truth）。一旦计划被绕过，整个并行波次的节奏就会被打乱。

6.5 安全与生产环境注意事项

在涉及真实生产环境的项目中，以下几点需要特别强调：

• 所有 Agent 生成的数据库变更必须使用迁移脚本（如 Alembic），严禁直接修改生产数据库。
• 涉及用户数据或权限的接口，必须经过安全评审，确认无越权访问风险。
• 生产环境部署前，先在预发布环境运行完整的端到端测试。
• 对 Agent 生成代码的权限做最小化控制，不要在 Agent 运行脚本中使用sudo或错误的高权限数据库账号。

Agentic Coding 的高效率来自于自动化，但“自动化”不等于“免责化”。在 Agent 执行链路上增加检查点、验证步骤和权限边界，是对项目负责，也是对 Agent 的产出质量负责。

6.6 版本控制与分支策略

建议使用短生命周期分支，每个 Wave 的任务在一个独立分支上开发，波次结束后合并回主干。这有几个好处：

• 出问题时可以快速回滚到某个 Wave 的完成状态。
• 任务之间的代码隔离更严格。
• 合并冲突可以尽早暴露，而不是在多个 Wave 之后集中爆发。

示例分支命名规范：

wave1/t001-task-model wave1/t002-api-contract wave2/t003-task-api wave3/t004-integration-test

7. 总结与下一步学习方向

Wb-Flow 是一种值得借鉴的 Agentic Coding 协作模式，它的核心贡献在于把“让 AI 写代码”这件事，从模糊的“生成式”过程，变成了清晰、可控、可验证的“计划 + 波次”执行过程。通过规划阶段定义任务边界和文件映射，通过并行波次提高开发吞吐，通过波次间的同步点保证稳定输出，你可以在团队中构建一条既高效又可控的 AI 辅助开发流水线。

读完本文，你应该已经掌握了以下内容：

• Agentic Coding 的核心痛点是什么，为什么需要计划和并行波次。
• Wb-Flow 中 Planning 阶段的产物和任务拆分方法。
• Parallel Waves 的运行机制和波次间的依赖传递规则。
• 从规划文档到 Wave 脚本的完整落地案例。
• 常见冲突、上下文丢失问题的排查思路。
• 文件级隔离、同步点、行为边界等关键实践原则。

下一步，你可以尝试把你手头一个中等规模的项目按 Wb-Flow 的思路拆解一遍，先不急着引入复杂工具，用现有的 Git、测试框架和 AI 编程工具，按 Wave 节奏驱动开发。当这种“先计划、再拆波、后执行”的模式跑顺之后，再考虑引入更复杂的自动化编排系统。实际项目中优先要盯住的是任务拆分粒度和文件冲突检测，这两点做好了，其他问题都会变得容易解决。

如果本文对你有帮助，可以收藏备用，也欢迎在评论区聊聊你在 Agentic Coding 落地中遇到的真实问题。