OmX Planner 行为指导深度解析：以结果优先的 evidence-grounded 规划之道

导读

本文围绕 oh-my-codex（OmX）仓库中规划者（Planner）角色共享行为指导文档 docs/prompt-guidance-fragments/planner-shared.md 展开，系统剖析 OmX 如何通过结构化提示词约束让 Planner 产出"结果优先（outcome-first）、可执行（execution-ready）"的规划。读者将理解这套指导的每条行为准则、它在 prompts/planner.md 等提示词表面的注入方式、同步机制与回归测试保障，以及规划产物（PRD、Test Spec、Deep Interview Spec）在源码中的落地形态。

一、背景：OmX 的 Prompt Guidance 碎片体系

OmX 的核心工作方式是"协调层 + 角色提示词"：AGENTS.md 定义顶层操作契约，prompts/*.md 定义各角色（executor、planner、verifier 等）的收窄执行面。为了让这些角色的行为语义保持一致，OmX 将共享行为指导抽取为独立的"碎片（fragment）"文件，集中存放在 docs/prompt-guidance-fragments/ 目录下：

• core-operating-principles.md：所有表面的通用操作原则
• leader-specialist-routing.md：专家路由契约
• core-verification-and-sequencing.md：验证与顺序指导
• planner-constraints.md / planner-investigation.md / planner-output.md：Planner 三件套（约束、调查、输出）
• planner-shared.md（本文主体）：Planner 跨表面共享行为指导
• executor-*、verifier-*：其他角色的对应碎片

这套体系的行为语义依据见 docs/prompt-guidance-contract.md 定义的五个核心模式：结果优先、简洁协作、低风险自动跟进、局部任务更新覆盖、证据预算与显式停止规则。planner-shared.md 正是这些模式在规划者角色上的具体化。

二、核心原则一：结果优先、可执行的计划形态

planner-shared.md 第一条是整套指导的基石：

默认采用 outcome-first、execution-ready 的计划：在添加过程细节之前，先定义期望结果、成功标准、约束、证据、验证路径和停止条件。

这要求 Planner 在撰写计划时，先回答"结果是什么、怎么算成功"，再回答"过程怎么做"。一份合格计划的要素按序包括：

1. 期望结果（desired result）：本次任务最终交付什么；
2. 成功标准（success criteria）：可测试、可观测的验收条件；
3. 约束（constraints）：范围边界、禁止事项、依赖前提；
4. 证据（evidence）：计划所依据的仓库事实与参考资料；
5. 验证路径（validation path）：如何证明标准达成；
6. 停止条件（stop condition）：何时允许完成、何种阻塞必须上报。

姊妹碎片 docs/prompt-guidance-fragments/planner-constraints.md 以近乎相同的措辞重申了这一点，而 prompts/planner.md 的 output_contract 则把它落实为具体的 Markdown 骨架：Plan Summary（含保存路径、Scope、复杂度估计）、Requirements and Acceptance（需求与验收标准）、Implementation Steps（带文件/资源引用的步骤）、Risks and Verification（风险/缓解、验证命令、停止条件）。

三、核心原则二：简洁直接的协作，只问必要决策

第二条约束 Planner 的沟通与提问方式：

保持协作风格简短直接；只向用户询问仓库检查无法解决的偏好、优先级或实质分支决策。

也就是说，Planner 的三问边界是：

可问	不可问
用户偏好（如技术选型倾向）	代码事实（应自行检查）
优先级权衡	能通过检索文档/源码解决的问题
实质分支决策	显而易见、低风险可推断的下一步

这与 prompts/planner.md 的约束一致："Inspect repository facts yourself; ask only for priorities, tradeoffs, or decisions that inspection cannot resolve."（自行检查仓库事实，只询问检查无法解决的优先级、权衡或决策。）执行环（execution_loop）第 3 步进一步规定："Resolve only genuine preference or tradeoff questions; otherwise choose the smallest coherent path."（只解决真正的偏好或权衡问题，否则选择最小自洽路径。）

四、核心原则三：局部覆盖 vs. 全局保留

第三条处理"用户中途改需求"的经典场景：

将更新的用户任务更新视为活动规划分支的本地覆盖，同时保留先前不冲突的约束。

这条规则的精髓在于"局部覆盖，而非全量重置"。当用户在规划过程中追加或修改信息时，Planner 应当：

• 把新指令看作当前规划分支的作用域内覆盖（local override）；
• 不触碰、不重写与之无冲突的既有验收标准。

这一语义在 prompts/planner.md 的 scenario_handling 中有具体示例：用户说 continue 时继续当前分支并补证而非重启；说 make a PR 时将其视为下游执行上下文，计划聚焦于其验收标准；说 merge if CI green 时把它当作下一步操作的限定条件（scoped condition），而非计划证据本身。对比 templates/AGENTS.md 中的通用版措辞（"Treat newer user task updates as local overrides for the active task while preserving earlier non-conflicting instructions"），可以看到碎片是通用原则在 Planner 角色上的精确化。

五、核心原则四与五：证据落地与克制式调查

第四条把"调查"与"计划落地"绑定：

如果正确性依赖于仓库检查、prompt 审查、官方文档或其他证据，请持续使用这些来源，直到计划落地。

第五条则为调查行为设置了预算边界：

更多的规划努力不等于反射性升级到 web/工具；仅在能够实质改善计划或所需证据时才检查或检索。

两条合起来构成 Planner 的"证据纪律"：

• 何时继续调查：当计划正确性确实依赖仓库事实、官方文档或测试时，不因省事而凭记忆猜测（对应姊妹碎片 docs/prompt-guidance-fragments/planner-investigation.md：持续检查引用的代码、测试、文档，直到需求、受影响资源、验证命令、失败行为与实质未决问题都可追溯）；
• 何时停止升级：计划所需证据已足够时，不因"显得努力"而启动无意义的检索循环。这与 docs/prompt-guidance-contract.md 的"证据预算（evidence budget）"模式一脉相承——工具使用只持续到任务落地与验证完成，避免只为改进措辞或收集非必要证据的额外循环。

六、默认输出形态：需求到资源的完整映射

第六条（planner-shared.md 的最后一条）规定默认终态：

默认最终输出形态：outcome-first 且 execution-ready，需求映射到文件/资源、验证检查、风险、停止规则，以及仅驱动下一步所需的细节。

强调两点：

1. 完整但不冗余：计划必须包含"需求 → 文件/资源映射、验证检查、风险、停止规则"，但细节量以"足以驱动下一步"为上限，不预写全部实现过程；
2. 可交接（handoff）：计划是给 Executor 或 Team 执行的交接物，而非研究报告。

这与 docs/prompt-guidance-fragments/planner-output.md 完全一致（"...mapping requirements to files/resources, validation checks, risks, stop rules, and the next handoff"）。从源码实现看，src/planning/artifacts.ts 中的 readPlanningArtifacts 与 isPlanningComplete 体现了"计划完整"的工程判据：存在 prd-*.md 且存在匹配的 test-spec-*.md 才算 planning complete——即一份"可执行"的计划必须同时包含产品需求文档与测试规格，这正是"需求映射到文件/资源 + 验证检查"的落地形态。

七、碎片如何注入 Planner 提示词：标记契约与同步机制

碎片不是孤立的文档，而是通过 OMX Guidance 标记契约 注入到实际运行的角色提示词中。以 prompts/planner.md 为例，文件中存在三对标记：

<!-- OMX:GUIDANCE:PLANNER:CONSTRAINTS:START --> ... <!-- OMX:GUIDANCE:PLANNER:CONSTRAINTS:END -->
<!-- OMX:GUIDANCE:PLANNER:INVESTIGATION:START --> ... <!-- OMX:GUIDANCE:PLANNER:INVESTIGATION:END -->
<!-- OMX:GUIDANCE:PLANNER:OUTPUT:START --> ... <!-- OMX:GUIDANCE:PLANNER:OUTPUT:END -->

同步由 src/scripts/sync-prompt-guidance-fragments.ts 完成：它以 docs/prompt-guidance-fragments/ 下的碎片为源，用 replaceBetween 在目标文件（AGENTS.md、templates/AGENTS.md、prompts/executor.md、prompts/planner.md、prompts/verifier.md）的标记之间做精确替换；以 --check 运行时若发现漂移（drift）则抛错 prompt_guidance_fragment_drift:...。

配套的回归测试 src/hooks/tests/prompt-guidance-fragments.test.ts 断言：prompts/planner.md 标记块内的内容必须逐字等于 planner-constraints.md、planner-investigation.md、planner-output.md 的 trim 后内容。也就是说，任何对碎片的手工修改若未同步到角色提示词，CI 会直接失败——这保证了"文档即配置"的单一事实来源（SSOT）属性。

八、规划产物体系：从指导到 .omx 目录的工程化

Planner 的行为指导最终要落到磁盘上的规划产物。从 src/planning/artifacts.ts 与 src/planning/artifact-names.ts 的源码可以推断出产物命名与定位约定：

• PRD：prd-<timestamp>-<slug>.md，位于 .omx/plans/；
• Test Spec：test-spec-<timestamp>-<slug>.md，与对应 PRD 同 slug 关联（selectMatchingTestSpecsForPrd 会按时间戳精确匹配或按 slug 兼容旧命名，见 artifact-names.ts）；
• Deep Interview Spec：deep-interview-<slug>.md 位于 .omx/specs/；
• 最新选择：selectLatestPlanningArtifactPath 按时间戳排序取最新（artifact-names.ts）。

时间戳格式为 YYYYMMDDTHHMMSSZ（planningArtifactTimestamp）。这套命名/选择机制正是"Planner 把需求映射到文件与资源"的运行时支撑：后续 Team/Ralph 的启动提示（launch hint）可以从已批准的 PRD 中解析出执行命令（readApprovedExecutionLaunchHintOutcome，见 artifacts.ts），实现"计划 → 批准 → 执行"的无缝衔接。

九、实践清单：把指导变成可复用的检查表

综合 planner-shared.md 及其姊妹碎片，可沉淀为一份 Planner 自查清单：

1. 动笔前：是否已定义期望结果、成功标准、约束、证据、验证路径、停止条件？若没有，先补上再写过程；
2. 提问前：这个问题能否通过检查仓库、prompt 或官方文档解决？能解决就不问；只问偏好、优先级、实质分支决策；
3. 需求变更时：新指令是否只覆盖当前分支？先前不冲突的验收标准是否原样保留？
4. 调查中：正确性依赖的证据是否已采集、可追溯？是否已避免无价值的检索升级？
5. 输出前：计划是否映射了需求 → 文件/资源、验证检查、风险、停止规则，且细节量恰好够驱动下一步？
6. 交接前：.omx/plans/ 下是否已保存 PRD 与匹配的 Test Spec？是否能在无需猜测的情况下推进交接？

十、结语

planner-shared.md 用七条精炼的行为准则，为 OmX 的 Planner 角色定义了"结果优先、证据落地、克制调查、局部覆盖"的规划哲学。它本身是 SSOT 体系的一部分——通过 src/scripts/sync-prompt-guidance-fragments.ts 注入 prompts/planner.md，并由 src/hooks/tests/prompt-guidance-fragments.test.ts 锁定同步一致性，最终由 src/planning/ 下的产物机制落地为 .omx/plans/ 中的可执行 PRD 与测试规格。理解这套指导，既能帮助使用者校准对 Planner 的预期，也能为自行设计多 Agent 规划提示词提供可直接复用的模式。