# 跨 Org Agent 的动态 Work Graph 设计能力——需求文档

**日期**: 2026-08-05
**性质**: 需求文档（BRD/PRD 层面），不含详细技术设计。回应 `docs/todo/graph-engineering-open-items.md` 条目 E 的确认结果——"Planner agent 里面要有多个 skill，不仅仅是 brd/prd/sdd/benchmark，还有给其他 Org Graph 节点的 agent 做各种动态 Work Graph 设计，提示词强化肯定要做"。
**依赖**：本文档定义的"节点分组可并行"标记方式需要跟 `docs/work-graph-parallel-execution-requirements.md`（条目 G）的详细设计对齐，建议 G 的 `graph_manifest` 数据结构定下来之后再最终敲定本文档的 FR-2。
**状态**: 草案，待评审。

## 1. 背景——一个比原开放问题更大的真实缺口

综述版/14 步版对照笔记原本提出的问题是"要不要把识别并行节点的判断标准写进 Planning Skill 的 prompt"。深入代码后发现实际缺口比这更大：

**当前生产代码里，只有 Planner 一个 Org Agent 真正用上了"动态生成 `graph_manifest` 再执行"这套机制**：

- `src/work_graph_plan.py::plan_work_graph()` 的 `_PROMPT_TEMPLATE`（`work_graph_plan.py:64-74`）是**硬编码**的：不管调用方传入的 `org_node` 是什么，提示词永远要求"Output a graph_manifest with one node per artifact_type (brd, prd, sdd, benchmark)"——这个函数虽然签名上接受任意 `org_node`，但实质上只能用来生成 Planner 的文档写作链。
- 唯一真实调用它的地方是 `src/e2e_pipeline.py::plan_documents()`，而且写死传入 `"planner"`（`e2e_pipeline.py:220`）。
- **Coder 和 Validator 目前完全不走这条 plan→execute 的路径**。`work_graph_orchestrate.py` 模块 docstring 明确记录：真正跑通的闭环（`e2e_pipeline.py`，U-014）里，Coder/Validator 用的是"一个更简单、独立的机制（flat `org_node_trigger.trigger_org_node()` calls）"——一次性的单个 Agent 调用，不经过任何"先规划出一张图、再按图执行"的过程。

也就是说，架构文档 §5"每个 Org Agent 拥有一个 Planning Skill，在接到任务时先生成本轮的 Work Graph"这句话，目前只对 Planner 成立。Coder 的 to-do 拆解+并行分派（架构文档 §6.2）、Validator 的功能/性能/边界测试并行执行（架构文档 §6.3）都还停留在设计意图，没有对应的动态规划实现——这正是用户说"还有给其他 Org Graph 节点的 agent 做各种动态 Work Graph 的设计"这句话所指的真实缺口，不是一个小的提示词优化。

**一个已经存在、值得保留的细节**：`_PROMPT_TEMPLATE` 里已经有 `edge_type: 'zero_token' | 'needs_judgment'` 的区分（`work_graph_plan.py:69-70`），这正好对应 14 步版"边是数据契约，简单聚合应该是零 token 的代码边，只有真正需要判断力的合并才值得用 Agent"这条原则——只是目前这个字段只用在 Planner 的纯串行链上，从未真正驱动过任何"这条边要不要派生一个 Agent"的执行决策。新方案应该保留并真正用起来这个字段，而不是重新发明一套。

## 2. 目标

1. 把"如何设计一张动态 Work Graph"（识别节点边界、识别哪些节点可以 fan-out、区分 `zero_token`/`needs_judgment` 边、给 fan-out 出的并行节点分组打标记）这套方法论，从 Planner 专属的硬编码提示词里抽出来，做成一个**跨 Org Agent 通用**的能力。
2. 让 Coder、Validator 也能各自调用这套能力，生成自己的 `graph_manifest`，走上跟 Planner 一样的 plan→execute 路径，而不是继续停留在"一次性单个 Agent 调用"的简化实现。
3. 在生成 `graph_manifest` 阶段就识别并标注"哪些节点互不依赖、可以并行执行"——即使执行层的并行能力（条目 G）还没上线，至少先把这个信息在数据模型里留出来，不需要等 G 上线后再回头改 Planning 阶段的产出格式。

## 3. 非目标

1. **不要求第一版就覆盖 Coder/Validator 的全部真实工作场景**。架构文档 §6.2/§6.3 描述的 Coder to-do 拆解、Validator 多类型测试并行是长期目标，第一版只需要证明"Coder/Validator 也能用同一套通用方法论生成一个可执行的 `graph_manifest`"这件事本身走得通，不需要一次性把每种真实业务场景都覆盖。
2. **不改变 `plan_work_graph`/`run_graph` 的既有函数签名和执行机制**。这是提示词/方法论层面的扩展（"用什么内容去问 Claude"），不是执行引擎的改动——`_PROMPT_TEMPLATE` 硬编码这件事本身要改，但改的方式是让它按 `org_node`/任务类型选择不同的提示词模板，不是重写 `plan_work_graph` 的调用方式。
3. **不在本文档里定案"节点分组可并行"的具体字段格式**。这个格式需要跟条目 G 的详细设计对齐（G 需要知道 `graph_manifest` 里怎么表达"这组节点可以并发触发"，才能实现相应的调度逻辑），本文档只提出需求，不抢先定字段名。

## 4. 功能需求

| # | 需求描述 | 优先级 |
|---|---|---|
| FR-1 | 把"如何设计一张 Work Graph"的通用方法论（节点边界怎么划、`zero_token`/`needs_judgment` 边怎么区分、fan-out 候选点怎么识别）抽成一个独立的 Skill（暂定名 `design-dynamic-work-graph`，具体命名留待设计阶段确定），跟现有 `skills/write-brd` 一类专属技能平级存放。 | 必须 |
| FR-2 | 这个 Skill 的产出需要能标注"哪些节点属于同一个可并行分组"——具体字段格式待 G 的设计确定后再补全，本需求只要求"设计阶段必须把这个信息在 `graph_manifest` 层面表达出来"这件事本身。 | 必须 |
| FR-3 | `work_graph_plan.py::plan_work_graph()` 的提示词生成逻辑需要从"永远硬编码 brd/prd/sdd/benchmark"改造成"按调用方传入的任务描述/`org_node` 动态生成"，具体改造方式（拆成多个模板、还是让 Skill 内容本身驱动 Claude 自主判断要生成哪些节点）留待设计阶段决定。 | 必须 |
| FR-4 | Coder、Validator 各自的 `.claude/agents/{coder,validator}.md`（及其 canonical 来源 `src/agent_profile.py::FRONTMATTER`）需要引用这个新 Skill。 | 必须 |
| FR-5 | 需要至少一条真实的 Coder 或 Validator 场景，验证"调用新 Skill 生成 `graph_manifest` → 走 `plan_work_graph`/`run_graph` 路径执行 → 产出正确结果"这条链路真的跑得通，不是只停留在 Planner 一个场景上验证。 | 应该 |

## 5. 验收标准

1. 给 Coder 一个可以自然拆成 2-3 个互不依赖子任务的真实场景（比如"给三个独立的模块各自补一个单元测试"），验证 Coder 能通过新 Skill 生成一个 `graph_manifest`（而不是走现在的单次 `trigger_org_node` 调用），且该 `graph_manifest` 正确标注了这几个节点互不依赖。
2. 验证 `plan_work_graph()` 面对 Coder/Validator 的调用时，不再原样返回"one node per artifact_type (brd, prd, sdd, benchmark)"这个 Planner 专属结构。
3. 验证 Planner 现有的 BRD→PRD→SDD→Benchmark 场景在改造后行为不受影响（回归测试，`src/test_e2e_pipeline.py` 等既有用例应继续通过）。
4. 部署后能在 Coder/Validator 的 `.claude/agents/*.md` 里看到新 Skill 出现在 `skills:` frontmatter 列表。

## 6. 约束与假设

- 复用现有的 `plan_work_graph()`/`run_graph()`/`work_graph_execute.execute_work_graph()` 执行机制，不新建一套并行的规划-执行引擎。
- `_PROMPT_TEMPLATE` 里已有的 `zero_token`/`needs_judgment` 边类型区分要保留，新 Skill 的方法论要明确指导 Claude 在生成边时如何选择这个字段，而不是留空/随意填。
- Coder/Validator 引入 plan→execute 路径后，原来的 `org_node_trigger.trigger_org_node()` 单次调用机制不需要立刻废弃——对于确实只需要单个节点就能完成的简单任务，继续走这条更轻量的路径是合理的（呼应架构文档和 14 步版共同的原则："任务很小或孤立时不需要上图"）。新 Skill 解决的是"任务复杂到值得规划成图时，Coder/Validator 有没有能力做这件事"，不是要求所有任务都必须走图。

## 7. 风险

- **`_PROMPT_TEMPLATE` 硬编码改造有回归风险**：这是唯一一条已经在生产里真实跑通、支撑着 Planner BRD→PRD→SDD→Benchmark 全链路的代码路径，改造时必须有充分的回归测试覆盖，不能因为扩展到 Coder/Validator 而破坏 Planner 现有场景。
- **FR-2 的具体字段格式依赖 G 的设计**，如果 G 的设计阶段推迟或方向调整，本条目的 FR-2/FR-3 也需要跟着调整，两者需要保持沟通同步，不要各自独立往前推进导致字段对不上。
- **Coder/Validator 引入图规划后，"什么时候该规划成图、什么时候该走简单单次调用"这个判断本身也需要方法论指导**——如果不加约束，可能出现"任务很小也被规划成图"的过度设计，第 6 节约束里提到的原则需要在 Skill 提示词里显式写出来，不能只是隐式假设 Claude 会自己把握分寸。

## 8. 开放问题（留给详细设计阶段回答）

- [ ] 新 Skill 的具体命名和目录结构。
- [ ] `_PROMPT_TEMPLATE` 具体怎么改造——是给每个 `org_node` 各自一份模板，还是设计成让 Claude 根据任务描述自主决定要生成哪些节点（更灵活但更难约束输出格式）？
- [ ] FR-2 的并行分组字段具体格式（待 G 确定）。
- [ ] Coder/Validator 第一个接入的真实业务场景选哪个，作为验收标准 1 的具体测试用例？