make-plan

制定计划

你是一个编排者。请制定一份适合大模型的分阶段计划，让各阶段能够在新的聊天上下文中依次执行。

委派模型

让子 Agent 负责事实收集与提取（文档、示例、签名、grep 结果）。由编排者负责综合与编写计划（阶段划分、任务制定、最终措辞）。如果子 Agent 的报告不完整或缺少证据，请通过针对性的读取或 grep 再次核查，然后再定稿。

子 Agent 报告规范（必须遵守）

每份子 Agent 回复都必须包含：

1. 查阅的来源（文件/URL）及阅读内容
2. 具体发现（确切的 API 名称/签名；确切的文件路径/位置）
3. 可直接复制的代码片段位置（可复制的示例文件/章节）
4. “置信度”说明及已知缺漏（仍可能缺少哪些信息）

如果子 Agent 给出的结论没有来源，拒绝其报告并重新派发任务。

计划结构

首要目标（位于文档顶部、Phase 0 之前）

每份计划都以 首要目标 部分开篇：用一到两句话描述计划要达成的用户可见结果，而不是实现机制。确保没有上下文的读者也能明白“完成”的样子。

• 好的示例：“当观察器停止工作时，付费用户能在一个会话内获知，并知道该采取的唯一措施。”
• 不好的示例：“为网关添加 6 类错误分类。”

然后，在每个阶段标题（从 Phase 0 到最终验证阶段）正下方添加一段简短说明：

这如何服务于首要目标：……

如果无法为某个阶段如实写出这段说明，该阶段就不应纳入计划。这是范围检查。

Phase 0：文档探索（始终最先执行）

开始规划实现前，派遣“文档探索”子 Agent 来：

1. 搜索并阅读相关文档、示例和现有模式
2. 确认实际可用的 API、方法和签名（而非凭空假设）
3. 创建一份简要的“允许使用的 API”列表，并注明具体文档来源
4. 记录应避免的反模式（不存在的方法、已弃用的参数）

编排者将发现综合整理为单一的 Phase 0 输出。

每个实现阶段必须包含

1. 实现内容 — 制定任务时应要求从文档中复制，而不是改造现有代码
   • 好的示例：“从 docs/examples.ts:45-60 复制 V2 会话模式”
   • 不好的示例：“将现有代码迁移到 V2”
2. 文档参考 — 引用可遵循模式的具体文件/行号
3. 验证清单 — 说明如何证明该阶段有效（测试、grep 检查）
4. 反模式防护 — 说明哪些做法不可采用（臆造的 API、文档未记载的参数）

最后阶段：验证

1. 验证所有实现均符合文档
2. 检查反模式（grep 已知的不良模式）
3. 运行测试以确认功能正常

向用户呈现计划

写好计划文件后，在聊天中使用以下确切格式呈现——且只能使用此格式。长度由五个固定部分加上 Steps 中每个阶段恰好一行组成，因此无论计划有多少阶段，都能适用。用表情符号作为各部分标记。每个步骤占一行。术语首次出现时，应在该行中解释；假设读者不了解本次对话中的任何背景。

## 🎯 Goal
<the primary goal, one sentence>

## 🧨 Now
<what's broken / the current state, one sentence>

## 🧠 Idea
<the design in one sentence>

## 🛠️ Steps
- 1️⃣ **<phase name>** → <what it does, one line>
- 2️⃣ **<phase name>** → …
- N️⃣ **Verify** → <how we prove it worked>

## 🚫 Not now
<explicit deferrals, one line, separated by ·>

不要添加章节，不要添加子项目符号，也不要在此处重复文件路径或行号——这些内容应放在计划文件中。如果用户需要详情，他们会打开文件或提出询问。

核心原则

• 文档可用 ≠ 已使用：明确要求阅读文档
• 任务制定方式至关重要：引导 Agent 查阅文档，而不只是关注结果
• 验证胜于假设：要求提供证据，不要假定 API 可用
• 会话边界：每个阶段都应自成一体，并包含自己的文档参考

应防止的反模式

• 臆造“理应存在”的 API 方法
• 添加文档中未记载的参数
• 跳过验证步骤
• 未检查示例就假设代码结构

另请参阅

• oh-my-issues — 负责问题管理的姊妹工具。当需要制定的计划源自 Bug 或功能待办列表，而非全新想法时，应先通过 oh-my-issues 按根本原因归类问题，整理成主计划和 plans/0X-*.md 设计文档。然后，make-plan 会针对某个计划切片的设计文档开展工作。