planning-workflow

规划工作流 — Agent 式开发的基础

核心理念：“规划所需的 token 远少于实现所需的 token，而且成本更低。”

在上下文窗口范围内，大模型在推理一份详细计划时会聪明得多。这正是花费 80% 以上时间进行规划的关键原因。

---

成果 — 如何判断这项技能已取得成效

满足以下所有条件时，才算有一份可用的计划：

• 计划内容完整：一个从未接触过该项目的新 Agent，读完后就能开始实现，无需向人类请求澄清。
• 计划考虑了依赖关系：每项重要任务都注明哪些事项会阻塞它，以及它会解除哪些事项的阻塞，因此工作可以清晰地拆解为 beads 图。
• 计划有充分依据：每项架构选择和每个不明显的功能，都至少有一句说明原因的话，而不只是说明内容——未来的 Agent 需要这些理由，才能做出一致的局部决策。
• 计划经过强推理模型（GPT Pro Extended Reasoning 是经过验证的选择）至少 4 轮审查，并达到稳定状态——也就是说，最近一轮只产生细微修改，而非结构性修改。
• 计划已转换为 beads，且依赖关系图保持完整，这样实现 Agent 无需重新阅读计划，就能通过 br ready --json 领取可开始的工作。

出现以下任一情况，就说明你尚未交付：非简单项目的计划少于约 1,500 行（细节不足）；计划超过约 10,000 行且没有拆分（无法执行）；实现过程中人类仍被问到“这应该怎么做？”（规划被放弃，而非完成）；beads 已创建却没有依赖边（转换时丢失了计划结构）。

何时不应使用这项技能

遇到以下情况时，请选择其他方式：

• 改动小且局部（修复一个 bug、涉及一个文件、少于约 200 LOC）→ 在聊天中规划，或创建一条 TaskCreate；规划的开销会超过实现成本。
• 纯粹进行研究（调查未知代码库、验证一个想法的原型）→ 先使用 codebase-archaeology 或 idea-wizard；规划用于执行，而非探索。
• 架构已有明确规定（移植现有系统、遵循规范，或实现定义清晰的 RFC）→ 使用 porting-to-rust 或 testing-conformance-harnesses；计划本身就是规范。
• 硬性截止期限不允许把 80% 的时间用于规划（线上事故、紧急修复、安全补丁）→ 先发布修复；如果相关领域还需要进一步工作，再补做计划。

依据 — 规划决策的信息来源

当规划模型提出架构方案时，该方案只是一项假设。在它通过某轮审查之前，请先用可验证的信息来源核实所有关键论断：

• **库／框架选择：**查阅实际的最新文档（最新稳定版本，而非模型训练时的版本）。如果模型说“用 X 实现 Y”，请确认 X 仍然存在、仍在维护，而且你要安装的版本支持 Y。
• **现有代码库的相关论断：**对于任何涉及现有项目的计划，模型对项目结构的理解都不可靠。请使用 Grep、git log 或 codebase-archaeology，在结构性论断影响计划之前先予以确认。
• **性能／扩展性论断：**没有引文或计划中的基准测试时，绝不要接受任何数字（“可处理 10k req/s”“加载时间 <100ms”）。计划中的裸数字只是披着事实外衣的猜测。
• **成本论断：**规划时请以服务提供商的定价页面为准进行核实；定价模式会变化。请在计划中注明你所依据的具体套餐。
• **对其他技能／工具的交叉引用：**如果计划写着“使用 <tool> 实现 X”，请确认该工具当前的功能约定支持 X。计划中的链接失效是一种不易察觉的失败方式。

未经核实却通过审查的计划，会在实现过程中带来意外。在规划阶段花少量精力核实，胜过代码写到一半后付出高昂的返工代价。

验证循环（各轮评审之间）

每轮评审后，在将计划交回进行下一轮评审之前，完成以下四项检查：

1. 自包含性检查 — 从计划中挑出最晦涩的任务，单独粘贴到一个新聊天中，并询问“按当前描述，这项任务是否可实施？”如果不能，就补充说明。
2. 依赖关系图检查 — 能否画出任务的有向无环图（DAG）？是否存在环？是否有孤立任务（没有下游使用者的任务）？任一情况都是计划错误。
3. 理由检查 — 随机抽取 5 个架构决策。每个决策都必须附有一段理由。如果没有，就请规划模型补充。
4. 稳定状态检查 — 比较本轮计划与上一轮计划的差异。如果存在较大的结构性变更，就需要再进行一轮。如果只是拼写级别的润色，就可以结束。

如果其中任何一项未通过，计划就还不能转换为 beads — 请再进行一轮评审。

---

规划为何重要

• 三思而后行 — 变成“检查计划 N 次，只实现一次”
• 一份非常庞大、复杂的 Markdown 计划，仍比几份实质性的代码文件短
• 在规划阶段提前投入人工意见，就能让你不必参与实现
• 只要启动足够多的 Agent，并提供扎实的计划，代码就能以惊人的速度编写完成

---

精确提示词 — 计划评审（GPT Pro Extended Reasoning）

Carefully review this entire plan for me and come up with your best revisions in terms of better architecture, new features, changed features, etc. to make it better, more robust/reliable, more performant, more compelling/useful, etc. For each proposed change, give me your detailed analysis and rationale/justification for why it would make the project better along with the git-diff style change versus the original plan shown below:

<PASTE YOUR EXISTING COMPLETE PLAN HERE>

---

精确提示词 — 整合修订（Claude Code）

GPT Pro 完成后（可能需要 20–30 分钟），将输出粘贴到 Claude Code 中：

OK, now integrate these revisions to the markdown plan in-place; use ultrathink and be meticulous. At the end, you can tell me which changes you wholeheartedly agree with, which you somewhat agree with, and which you disagree with:

```[Pasted text from GPT Pro]```

---

流程概览

1. INITIAL PLAN (GPT Pro / Opus 4.7 in web app)
   └─► Explain goals, intent, workflows, tech stack

2. ITERATIVE REFINEMENT (GPT Pro Extended Reasoning)
   └─► 4-5 rounds of revision until steady-state

3. MULTI-MODEL BLENDING (Optional but recommended)
   └─► Gemini 3.1 Pro Deep Think, Grok4 Heavy, Opus 4.7
   └─► GPT Pro as final arbiter

4. CONVERT TO BEADS (Claude Code + Opus 4.7)
   └─► Self-contained tasks with dependency structure

5. POLISH BEADS (6+ rounds until steady-state)
   └─► Cross-model review, never oversimplify

---

优秀计划的特点

良好计划	优秀计划
描述要构建什么	解释为什么要构建
列出功能	详细说明用户工作流和交互
提及技术栈	权衡并论证技术选择
包含任务	包含任务及其依赖关系和理由
约 500 行	润色后约 3,500 行以上

必备要素

1. 自包含 — 无需查阅外部文档
2. 细化 — 将复杂功能拆分为具体的子任务
3. 考虑依赖关系 — 哪些任务会阻塞其他任务？
4. 论证充分 — 包含推理，而不只是指令
5. 以用户为中心 — 每个部分如何服务最终用户？

---

常见错误

1. 过早开始实现 — 规划 3 小时，可节省 30 小时的返工
2. 只评审一轮 — 即使到了第 6 轮及以后，仍能持续获得改进
3. 不使用 GPT Pro — Extended Reasoning 在这方面有独到优势
4. 先编写骨架代码 — 一份全面的大计划胜过渐进式编码
5. 丢失上下文 — 将计划转换为 beads，这样 Agent 就不需要原始内容

---

参考资料

主题	参考资料
所有精确提示词	PROMPTS.md
真实案例	EXAMPLES.md
常见问题	FAQ.md