oh-my-claudecode 的 Planner 智能体解析：结构化访谈、共识规划与可执行工作计划的完整实现

导读

本文基于 oh-my-claudecode 仓库中规划智能体的核心定义文档 agents/planner.md，结合其 TypeScript 注册实现、提示词单一来源工程（prompt-ssot）与 /plan 技能体系，系统讲解一个"只规划、不实现"的战略规划顾问是如何工作的。读完本文，你将掌握：Planner 的职责边界与分工、基于逐题访谈的调研协议、3–6 步可执行计划的产出规范、共识模式下的 RALPLAN-DR 决策结构与 ADR 记录，以及如何把开放问题沉淀到统一位置并完成向执行者的交接。

---

一、Planner 在 oh-my-claudecode 中的定位与注册方式

oh-my-claudecode 是一套面向 Claude Code 的 Teams-first 多智能体编排（Multi-agent orchestration） 框架。在这一编排体系中，planner 被定位为 Advisor（顾问）类智能体：当需求模糊、任务规模大、需要先理清边界时，系统会委派它去完成需求澄清与工作计划设计，而不是直接写代码。

1.1 提示词文件中的元数据声明

agents/planner.md 开头是 YAML frontmatter，定义了智能体的对外身份：

name: planner
description: Strategic planning consultant with interview workflow (Opus)
model: opus
level: 4

• description：战略规划顾问，具备访谈式工作流，默认运行在 Opus 模型上；
• level: 4：与 docs/shared/agent-tiers.md 描述的能力分层对应，属于高层级规划角色；
• model: opus：说明该智能体承担高密度推理任务，倾向分配给最强模型。

1.2 源码侧的注册与配置

提示词文件并不是孤立存在的，它被 TypeScript 侧的智能体配置加载并注册进统一目录。查看 src/agents/planner.ts 可以看到完整映射：

export const PLANNER_PROMPT_METADATA: AgentPromptMetadata = {
  category: 'planner',
  cost: 'EXPENSIVE',
  promptAlias: 'planner',
  triggers: [{ domain: 'Strategic Planning',
    trigger: 'Comprehensive work plans, interview-style consultation' }],
  useWhen: [
    'Complex features requiring planning',
    'When requirements need clarification through interview',
    'Creating comprehensive work plans',
    'Before large implementation efforts',
  ],
  avoidWhen: [
    'Simple, straightforward tasks',
    'When implementation should just start',
    'When a plan already exists',
  ],
};

export const plannerAgent: AgentConfig = {
  name: 'planner',
  description: `Strategic planning consultant. Interviews users to understand
    requirements, then creates comprehensive work plans. NEVER implements - only plans.`,
  prompt: loadAgentPrompt('planner'),
  model: 'opus',
  defaultModel: 'opus',
  metadata: PLANNER_PROMPT_METADATA,
};

其中 loadAgentPrompt('planner') 会将 agents/planner.md 作为系统提示词加载，形成"Markdown 定义提示词、TS 注册运行时"的双层结构。类型定义见 src/agents/types.ts 中的 AgentConfig 与 AgentPromptMetadata：

• AgentCost：取值 FREE | CHEAP | EXPENSIVE，Planner 标注为 EXPENSIVE，供路由层在"何时值得花高价调用"上做成本判断；
• AgentCategory：包含 exploration / specialist / advisor / utility / orchestration / planner / reviewer，Planner 属于 planner 类；
• useWhen / avoidWhen / triggers：用于动态生成委派路由表，决定"什么样的用户请求应当交给 planner"。

在 src/agents/definitions.ts 与 src/agents/index.ts 中，plannerAgent 被汇入统一的智能体注册表并向全仓库导出，供委派机制、Task 子智能体调用（如 Task(subagent_type="oh-my-claudecode:planner", ...)）与技能系统共同使用。

此外，该提示词已进入提示词单一来源（prompt-ssot）工程：生成产物 generated/prompt-ssot/role-planner.md 中以"Role: Planner"的形式沉淀了规划车道（planning lane）的运行原则，强调"规划输出是只读的：在获得明确执行批准前，绝不修改产品源码、运行变更性命令、提交或推送"，与 agents/planner.md 的约束完全一致。

---

二、核心使命与职责边界：为什么 Planner "只规划、不实现"

agents/planner.md 在 <Role> 中定义了 Planner 的使命：

通过结构化咨询，创建清晰、可执行的工作计划。负责访谈用户、收集需求、经由智能体调研代码库，并把工作计划保存到 .omc/plans/*.md。

一个关键的设计是职责单向切分：

智能体	职责	反面（不做的事）
planner	访谈用户、收集需求、调研代码、产出计划	不写代码、不分析需求缺口、不评审计划、不做架构分析
executor	按计划实施	不替代 planner 做规划（且计划文件对它只读）
analyst	需求缺口、边界情况、风险分析（规划前咨询）	不产出最终计划
critic	计划质量评审	不产出计划
architect	代码/架构分析	不替代规划访谈

因此，agents/planner.md 强调一个语言约定：当用户说 "do X" 或 "build X" 时，把它理解为"为 X 创建工作计划"。 这是整个文档约束体系的出发点——Planner 永远不越过"规划"边界。

<Why_This_Matters> 给出了这一设计的原因：过于模糊的计划会让 executor 靠猜浪费时间；过于细碎的计划又会迅速过期。一份好的计划应当包含 3–6 个具体步骤并带有清晰验收标准，而不是 30 个微步骤或 2 条空泛指令。同时，能通过查代码库获得的事实（codebase facts）不应去打扰用户，那会浪费用户时间并侵蚀信任。

---

三、调研协议：一次一问的访谈与"代码库事实不问用户"原则

<Investigation_Protocol> 是 Planner 运转的核心算法，共 7 步：

1. 意图分类（Classify intent）：将请求归类为
   • Trivial / Simple（快速修复）
   • Refactoring（以安全为重点）
   • Build from Scratch（以探索发现为重点）
   • Mid-sized（以边界确定为重点）
2. 代码库事实交给 explore agent：绝不把代码库能回答的问题抛给用户；
3. 只问用户偏好：优先级、时间线、范围决策、风险容忍度、个人偏好，用 AskUserQuestion 提供 2–4 个可点选项；
4. 用户触发计划生成（"make it into a work plan"）时，先咨询 analyst 做需求缺口分析；
5. 生成计划：包含 Context（背景）、Work Objectives（工作目标）、Guardrails（Must Have / Must NOT Have）、Task Flow（任务流）、Detailed TODOs with acceptance criteria（带验收标准的详细待办）、Success Criteria（成功标准）；
6. 展示确认摘要，等待用户明确批准；
7. 批准后交接给 /oh-my-claudecode:start-work {plan-name}。

配合这一协议，agents/planner.md 用 <Good>/<Bad> 示例做了极具指导性的正反对照：

• Good：用户说"加暗黑模式"，Planner 逐个提问"暗黑模式应该是默认还是可选的？""你的时间线优先级是什么？"，同时派生 explore 智能体查找既有主题/样式模式，在用户说"把它做成计划"后生成 4 步计划并附带清晰验收标准；
• Bad：用户说"加暗黑模式"，Planner 一次性抛出 5 个问题，其中还包括"你用什么 CSS 框架？"（这是代码库事实），并且未经请求就生成了 25 步计划、直接开始派生 executor。

3.1 问题分类与提问纪律

在具体提问时，文档要求 一次只问一个问题，绝不批量提问。同时将问题区分为四类，决定各自的处理动作：

类型	示例	处理动作
Codebase Fact	"现在代码里有哪些模式？""X 在哪里？"	先 explore，不要问用户
User Preference	"优先级？""时间线？"	通过 AskUserQuestion 问用户
Scope Decision	"要不要包含特性 Y？"	问用户
Requirement	"性能约束是什么？"	问用户

这与 skills/plan/SKILL.md 中"自适应访谈"（adaptive interview）的示例完全同构：Planner 先自己派生 explore 智能体查出"认证实现在 src/auth/，使用 JWT + passport.js"，再向用户提出一个知情后的偏好问题（"扩展既有认证，还是新增独立认证流？"）。逐题递进式访谈（Q1 问目标 → Q2 问延迟还是吞吐 → Q3 问 p50 还是 p99）能保证每个后续问题都建立在前一个答案之上，避免决策疲劳。

3.2 访谈工具与协作智能体

<Tool_Usage> 明确了 Planner 的工具矩阵：

• 偏好/优先级类问题一律使用 AskUserQuestion（提供可点击选项）；
• 代码库上下文问题派生 explore agent（model=haiku，30 秒超时） 去查；
• 外部文档需求派生 document-specialist agent；
• 计划文件通过 Write 写入 .omc/plans/{name}.md。

在正式生成最终计划前，Planner 必须先咨询 analyst以捕获缺失需求——这是把"隐藏需求、边界情况、风险"兜住的强制环节。对应源码可见 src/agents/analyst.ts：analyst 被描述为"规划前的咨询者，识别隐藏需求、边界情况与潜在风险，在创建工作计划之前使用"，同样运行在 Opus 上。

---

四、计划的形态、粒度与目录约定

4.1 粒度与内容骨架

Planner 生成的计划遵循"恰到好处"原则，计划产物应包含下列骨架：

• Context（背景）
• Work Objectives（工作目标）
• Guardrails：Must Have / Must NOT Have
• Task Flow（任务流）
• Detailed TODOs with acceptance criteria
• Success Criteria（成功标准）

粒度默认是 3–6 个可执行步骤，每步带 executor 可核验的验收标准；除非任务本身要求架构级改动，否则避免架构重设计。三条硬性输出纪律如下：

纪律	反模式 → 正确姿势
防过度规划	30 个带实现细节的微步骤 → 3–6 个带验收标准的步骤
防规划不足	"第 1 步：实现该特性" → 拆成可验证的块
防过早生成	用户未明确要求就出计划 → 保持访谈态直到被触发

4.2 计划文件落在哪里

所有计划统一保存到状态根目录下的 .omc/plans/*.md，草稿写入 .omc/drafts/*.md。这一目录约定贯穿全仓库：

• docs/CLAUDE.md 将 .omc/plans/ 列为 OMC 运行时状态的一部分（.omc/state/、.omc/notepad.md、.omc/plans/、.omc/research/ 等），且这些目录默认属于忽略的操作性产物（operational artifacts）；
• docs/REFERENCE.md 指出，计划持久化遵循同一规则：默认生成的 .omc/plans/ 是本地操作性产物、被 git 忽略；若需让计划成为长期项目文档，可移到受跟踪的 docs 路径或把 planOutput.directory 配置为被评审目录（如 docs/plans）；
• docs/ARCHITECTURE.md 将 .omc/plans/ 归入"数据面"（plans, specs, prompts, results, traces 等持久产物）。

对应到执行侧还有一道保护墙：agents/executor.md 与 agents/git-master.md 都声明 .omc/plans/*.md 对执行者是只读的，任何实施阶段都不得改写计划，保证"计划是执行契约"。

4.3 计划摘要的输出格式

当计划生成完毕，Planner 需按 <Output_Format> 输出统一摘要，等待用户确认：

## Plan Summary

**Plan saved to:** `.omc/plans/{name}.md`

**Scope:**
- [X tasks] across [Y files]
- Estimated complexity: LOW / MEDIUM / HIGH

**Key Deliverables:**
1. [Deliverable 1]
2. [Deliverable 2]

**Consensus mode (if applicable):**
- RALPLAN-DR: Principles (3-5), Drivers (top 3), Options (>=2 or explicit invalidation rationale)
- ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups

**Does this plan capture your intent?**
- "proceed" - Begin implementation via /oh-my-claudecode:start-work
- "adjust [X]" - Return to interview to modify
- "restart" - Discard and start fresh

摘要末尾的三分叉（proceed / adjust [X] / restart）正是"计划必须由用户显式确认后才可交接"这一约束的可执行表达：没有 "proceed"，就没有 /oh-my-claudecode:start-work。

---

五、共识模式与 RALPLAN-DR：多人视角下的严谨决策

5.1 从独立文档到 /plan --consensus 的演进

在 oh-my-claudecode 中，Planner 的访谈式单智能体工作流只是基础形态；当项目进入**共识规划（consensus planning）**时，agents/planner.md 的 <Consensus_RALPLAN_DR_Protocol> 便接管，要求 Planner 运行在 /plan --consensus（即 ralph/ralplan）语境下。据 skills/plan/SKILL.md，原先独立的 /planner、/ralplan、/review 技能已合并进 /plan，Planner 文档中的共识协议正是这套合并后技能中"共识模式"的角色侧契约。

共识模式形成 Planner → Architect → Critic 的迭代回路，每次评审后回到 Planner 进行综合修订。契约要求：

• Planner 先生成初始计划，并附带一份紧凑的 RALPLAN-DR 摘要供 Architect 评审；
• Architect 只做架构稳健性评审（须包含针对首选方案的"钢人式反方论证"antithesis、至少一个实质性的取舍张力，以及可行的综合路径）；
• Critic 独立地对同一份固定计划快照做质量标准评审（须校验原则与选项一致性、替代方案探索是否公允、风险缓解是否清晰、验收标准是否可测试、验证步骤是否具体）；
• 两者必须顺序独立运行：先等待 Architect 的 Task 完成，再发起 Critic 的 Task，二者绝不能并行，Architect 的输出绝不能传给 Critic，只能由 Planner 在双方都完成后做修订综合。

<Consensus_RALPLAN_DR_Protocol> 的五步流程如下：

1. 为第二步的 AskUserQuestion 对齐输出紧凑摘要：Principles（3–5 条）、Decision Drivers（Top 3）、带限定优劣的可行选项；
2. 保证至少 2 个可行选项；若只剩 1 个，须显式写明替代项被否决的理由（invalidation rationale）；
3. 标记模式为 SHORT（默认）或 DELIBERATE（--deliberate / 高风险）；
4. DELIBERATE 模式必须追加：pre-mortem（3 个失败场景）与扩展测试计划（unit / integration / e2e / observability 四层）；
5. 最终修订版计划必须包含 ADR 记录：Decision、Drivers、Alternatives considered、Why chosen、Consequences、Follow-ups。

5.2 决策结构与产出契约

RALPLAN-DR 元素	要求	备注
Principles	3–5 条	贯穿决策的原则
Decision Drivers	Top 3	排名前三的决策驱动力
Options	≥2 个	每个选项附带受边界约束的 Pros / Cons
Invalidation rationale	当选项数收敛到 1	显式说明其余替代项为何被否决
Pre-mortem	DELIBERATE 模式 3 个失败场景	高风险任务强制
Expanded test plan	unit / integration / e2e / observability	DELIBERATE 模式强制
ADR	Decision / Drivers / Alternatives / Why / Consequences / Follow-ups	共识最终计划必备

值得一提的执行细节是 RALPLAN 的状态生命周期管理。共识循环由 persistent-mode 停止钩子通过 ralplan-state.json 守护续行，skills/plan/SKILL.md 要求按场景区分收尾：

• 交接执行（批准 → ralph/team）前调用 state_write(mode="ralplan", active=false, ...)；
• 真正的终止退出（拒绝、错误、非交互停机）调用 state_clear(...)；
• 明确禁止在发起执行模式前使用 state_clear——它会写入 30 秒的取消信号、停用所有模式的 stop-hook 强制，让新启动的执行模式失去保护；
• 必须总是传递 session_id，避免误清并发会话的状态。

5.3 评审轮次上限与交互开关

共识循环最多迭代 5 轮；若达到上限仍未获批准，Planner 须将当前最优版本交给用户决策，并注明"专家共识未达成"。是否插入用户环节由 --interactive 决定：

• 带 --interactive：在"草稿评审"（步骤 2）与"最终批准"（步骤 7）两处用 AskUserQuestion 呈现计划与 RALPLAN-DR 摘要，选项包括 Proceed to review、Request changes、Skip review；最终批准支持 Approve execution via team（推荐）、Approve execution via ralph、Compact then return for execution approval、Request changes、Reject，绝不以纯文本征求批准；
• 不带 --interactive：跳过两次提问，将最终计划标记为 pending approval，调用 state_clear 后停机，绝不自动执行。

---

六、开放问题的统一沉淀：.omc/plans/open-questions.md

agents/planner.md 专门以 <Open_Questions> 小节规定了开放问题（Open Questions）的持久化：

当计划存在未决问题、延期给用户的决策、或执行前需要澄清的事项时，把它们写入 .omc/plans/open-questions.md。

同时，analyst 输出中的 ### Open Questions 一节也必须被抽取并追加到同一文件。每条记录格式为：

## [Plan Name] - [Date]
- [ ] [Question or decision needed] — [Why it matters]

这样设计的目标非常明确：把所有计划与需求分析产生的开放问题汇总到单一位置，而不是散落在多个文件中；文件已存在时追加而不是覆盖。文档明确"orchestrator 或 planner 会在你（analyst）的立场上把开放问题持久化到 .omc/plans/open-questions.md"（见 agents/analyst.md），说明这一目录是 planner 与 analyst 之间跨智能体的交接点之一。

---

七、失败模式：Planner 最容易犯的六个错误

agents/planner.md 用 <Failure_Modes_To_Avoid> 总结了规划角色最典型的反模式，值得逐一对照自查：

#	反模式	后果	正确做法
1	把代码库问题抛给用户（如"auth 实现放在哪？"）	浪费用户时间、侵蚀信任	派生 explore agent 自查
2	过度规划（30 个含实现细节的微步骤）	计划迅速过时、执行成本高	3–6 个带验收标准的步骤
3	规划不足（"第 1 步：实现该特性"）	executor 无法执行	拆成可验证的块
4	提前生成计划	未对齐需求就产出	保持访谈态直到被显式触发
5	跳过确认就交接	方向错误直达执行	永远等待显式 "proceed"
6	架构重设计	本可定点改动却引入重写	默认最小范围（minimal scope）

这些失败模式与 skills/plan/SKILL.md 的 Bad 示例一一对应：查代码库能解决的事实却去问用户、一次性批量抛出多个问题、把 4 个设计选项同时端给用户——文档给出的规避手段都是"先 explore、一次一问、逐个选项讨论后再给推荐"。

---

八、设计与输出的质量控制标准

8.1 量化质量标准

skills/plan/SKILL.md 把质量门槛显式量化到可校验的数字：

• 90%+ 验收标准为可测试（testable）标准；
• 80%+ 论断引用具体的文件/行号；
• 所有风险都有缓解措施；
• 不含无度量的模糊词（禁止 "fast"，要求 "p99 < 200ms"）。

8.2 规划产物只读原则与交接路径

无论处于哪种模式，Planner 都受规划/执行边界约束：规划类模式只能检视上下文、产出计划/规格/提案，在未获显式执行批准前不得运行变更性 shell 命令、不得编辑源码、不得 commit / push / 开 PR、不得调用执行类技能或委派实施任务。产物一律标记为 pending approval。

用户批准后的交接路径有两种（skills/plan/SKILL.md）：

• 经 team 执行（推荐）：调用 Skill("oh-my-claudecode:team")，把经批准的 .omc/plans/ 计划路径作为上下文，由团队技能协调并行智能体按流水线推进大任务；
• 经 ralph 执行：调用 Skill("oh-my-claudecode:ralph")，由 Ralph 技能持有持久化执行与验证。

两份执行入口都不允许 Planner 亲自改源码——"planner 中不要直接编辑源码文件，Ralph 技能拥有持久执行与验证"正是对 <Constraints> 中"绝不开始实现"的运行级落地。相应地，agents/planner.md 交接指令中的 /oh-my-claudecode:start-work {plan-name} 即单智能体/直接执行场景下的启动入口。

8.3 一份真实对话的参照

如果想看这套协议在完整会话中的表现，seminar/demos/demo-4-planning.md 提供了一个 auth 系统规划的可复现演示：plan the user authentication system 触发四轮单选访谈（认证方式 JWT/会话/OAuth/MFA、存储 PostgreSQL/MongoDB…），随后依次派生 analyst（需求规格）、architect（系统设计）、critic（设计评审），最终把计划保存为 .omc/plans/auth-system.md——与 agents/planner.md 描述的协议时序逐条吻合。

---

九、最终自查清单：让每一次规划都可复现

Planner 每次任务结束前都必须过一遍 <Final_Checklist>。这份清单同样适合作为读者自建"规划智能体"的验收模板：

• [ ] 我只问了用户的偏好（而非代码库事实）吗？
• [ ] 计划包含 3–6 个带验收标准的可执行步骤吗？
• [ ] 用户是否显式发起了计划生成？
• [ ] 交接前我是否等待了用户确认？
• [ ] 计划是否已保存到 .omc/plans/？
• [ ] 开放问题是否写入了 .omc/plans/open-questions.md？
• [ ] 共识模式下，是否为第二步对齐提供了 principles / drivers / options 摘要？
• [ ] 共识模式下，最终计划是否包含 ADR 各字段？
• [ ] DELIBERATE 共识模式下，pre-mortem 与扩展测试计划是否齐全？

其中"开放问题统一追踪"更是把分析阶段遗留事项收敛到一处，让整个规划过程从"访谈 → 调研 → 出计划 → 共识评审 → 开放问题收口 → 用户批准 → 交接执行"构成闭环。

---

结语

从 agents/planner.md 的提示词文档出发，可以看到 oh-my-claudecode 的 Planner 并非"生成待办的工具"，而是一套受纪律约束的规划协议：它用一次一问的访谈换取需求对齐，用 explore agent 守住"不问代码库事实"的信任底线，用 3–6 步 + 验收标准换取计划的可执行性，用 RALPLAN-DR 与 ADR 换取高风险决策的可追溯性，再用 pending approval 与只读的 .omc/plans/ 严格守住"规划与执行"的边界。若要在自己的 Agent 编排中复刻这一角色，src/agents/planner.ts 提供了最精简的注册骨架（配置 + 元数据 + prompt 引用），skills/plan/SKILL.md 提供了最完整的流程状态机，而 agents/planner.md 本身则是这个角色所有行为约束的单一真相源。