跨 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 的具体测试用例？