OmX Planner 行為指導深度解析以結果優先的 evidence-grounded 規劃之道【免費下載鏈接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.項目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex導讀本文圍繞 oh-my-codexOmX倉庫中規劃者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.mdPlanner 三件套約束、調查、輸出planner-shared.md本文主體Planner 跨表面共享行為指導executor-*、verifier-*其他角色的對應碎片這套體系的行為語義依據見 docs/prompt-guidance-contract.md 定義的五個核心模式結果優先、簡潔協作、低風險自動跟進、局部任務更新覆蓋、證據預算與顯式停止規則。planner-shared.md正是這些模式在規劃者角色上的具體化。二、核心原則一結果優先、可執行的計劃形態planner-shared.md第一條是整套指導的基石默認采用 outcome-first、execution-ready 的計劃在添加過程細節之前先定義期望結果、成功標準、約束、證據、驗證路徑和停止條件。這要求 Planner 在撰寫計劃時先回答結果是什么、怎么算成功再回答過程怎么做。一份合格計劃的要素按序包括期望結果desired result本次任務最終交付什么成功標準success criteria可測試、可觀測的驗收條件約束constraints范圍邊界、禁止事項、依賴前提證據evidence計劃所依據的倉庫事實與參考資料驗證路徑validation path如何證明標準達成停止條件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需求映射到文件/資源、驗證檢查、風險、停止規則以及僅驅動下一步所需的細節。強調兩點完整但不冗余計劃必須包含需求 → 文件/資源映射、驗證檢查、風險、停止規則但細節量以足以驅動下一步為上限不預寫全部實現過程可交接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 的源碼可以推斷出產物命名與定位約定PRDprd-timestamp-slug.md位于.omx/plans/Test Spectest-spec-timestamp-slug.md與對應 PRD 同 slug 關聯selectMatchingTestSpecsForPrd會按時間戳精確匹配或按 slug 兼容舊命名見 artifact-names.tsDeep Interview Specdeep-interview-slug.md位于.omx/specs/最新選擇selectLatestPlanningArtifactPath按時間戳排序取最新artifact-names.ts。時間戳格式為YYYYMMDDTHHMMSSZplanningArtifactTimestamp。這套命名/選擇機制正是Planner 把需求映射到文件與資源的運行時支撐后續 Team/Ralph 的啟動提示launch hint可以從已批準的 PRD 中解析出執行命令readApprovedExecutionLaunchHintOutcome見 artifacts.ts實現計劃 → 批準 → 執行的無縫銜接。九、實踐清單把指導變成可復用的檢查表綜合planner-shared.md及其姊妹碎片可沉淀為一份 Planner 自查清單動筆前是否已定義期望結果、成功標準、約束、證據、驗證路徑、停止條件若沒有先補上再寫過程提問前這個問題能否通過檢查倉庫、prompt 或官方文檔解決能解決就不問只問偏好、優先級、實質分支決策需求變更時新指令是否只覆蓋當前分支先前不沖突的驗收標準是否原樣保留調查中正確性依賴的證據是否已采集、可追溯是否已避免無價值的檢索升級輸出前計劃是否映射了需求 → 文件/資源、驗證檢查、風險、停止規則且細節量恰好夠驅動下一步交接前.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 規劃提示詞提供可直接復用的模式。【免費下載鏈接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.項目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考 OmX Planner 行為指導深度解析：以結果優先的 evidence-grounded 規劃之道
OmX Planner 行為指導深度解析以結果優先的 evidence-grounded 規劃之道【免費下載鏈接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.項目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex導讀本文圍繞 oh-my-codexOmX倉庫中規劃者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.mdPlanner 三件套約束、調查、輸出planner-shared.md本文主體Planner 跨表面共享行為指導executor-*、verifier-*其他角色的對應碎片這套體系的行為語義依據見 docs/prompt-guidance-contract.md 定義的五個核心模式結果優先、簡潔協作、低風險自動跟進、局部任務更新覆蓋、證據預算與顯式停止規則。planner-shared.md正是這些模式在規劃者角色上的具體化。二、核心原則一結果優先、可執行的計劃形態planner-shared.md第一條是整套指導的基石默認采用 outcome-first、execution-ready 的計劃在添加過程細節之前先定義期望結果、成功標準、約束、證據、驗證路徑和停止條件。這要求 Planner 在撰寫計劃時先回答結果是什么、怎么算成功再回答過程怎么做。一份合格計劃的要素按序包括期望結果desired result本次任務最終交付什么成功標準success criteria可測試、可觀測的驗收條件約束constraints范圍邊界、禁止事項、依賴前提證據evidence計劃所依據的倉庫事實與參考資料驗證路徑validation path如何證明標準達成停止條件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需求映射到文件/資源、驗證檢查、風險、停止規則以及僅驅動下一步所需的細節。強調兩點完整但不冗余計劃必須包含需求 → 文件/資源映射、驗證檢查、風險、停止規則但細節量以足以驅動下一步為上限不預寫全部實現過程可交接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 的源碼可以推斷出產物命名與定位約定PRDprd-timestamp-slug.md位于.omx/plans/Test Spectest-spec-timestamp-slug.md與對應 PRD 同 slug 關聯selectMatchingTestSpecsForPrd會按時間戳精確匹配或按 slug 兼容舊命名見 artifact-names.tsDeep Interview Specdeep-interview-slug.md位于.omx/specs/最新選擇selectLatestPlanningArtifactPath按時間戳排序取最新artifact-names.ts。時間戳格式為YYYYMMDDTHHMMSSZplanningArtifactTimestamp。這套命名/選擇機制正是Planner 把需求映射到文件與資源的運行時支撐后續 Team/Ralph 的啟動提示launch hint可以從已批準的 PRD 中解析出執行命令readApprovedExecutionLaunchHintOutcome見 artifacts.ts實現計劃 → 批準 → 執行的無縫銜接。九、實踐清單把指導變成可復用的檢查表綜合planner-shared.md及其姊妹碎片可沉淀為一份 Planner 自查清單動筆前是否已定義期望結果、成功標準、約束、證據、驗證路徑、停止條件若沒有先補上再寫過程提問前這個問題能否通過檢查倉庫、prompt 或官方文檔解決能解決就不問只問偏好、優先級、實質分支決策需求變更時新指令是否只覆蓋當前分支先前不沖突的驗收標準是否原樣保留調查中正確性依賴的證據是否已采集、可追溯是否已避免無價值的檢索升級輸出前計劃是否映射了需求 → 文件/資源、驗證檢查、風險、停止規則且細節量恰好夠驅動下一步交接前.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 規劃提示詞提供可直接復用的模式。【免費下載鏈接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.項目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考