grill-to-plan

将想法梳理成计划

将模糊的目标、粗略的想法、计划或设计转化为共同理解、明确决策和最终可执行的计划。

模式

• 轻量模式：只提出最有价值的问题，保持对话式语气；除非用户提出要求或出现需要长期记录的项目决策，否则跳过仓库文档。
• 文档化模式：执行完整工作流——检查代码和文档、更新词汇表、在适当时编写 ADR、记录会话并进行最终总结。

工作流

1. 重述目标。

   • 将用户当前的意图改述为具体、明确的内容。
   • 在用户提供足够的决策、使其足以构成计划之前，将输入视为目标描述。
   • 说明你认为期望的最终状态是什么、范围包括什么，以及哪些内容可能不在范围内。
   • 如果初始背景过于有限，无法做出合理判断，请先询问缺失的背景信息。
   • 根据利害程度选择模式：默认使用轻量模式；涉及项目知识、架构或需要长期保留的决策时，切换到文档化模式。如果无法从初始输入判断模式，请先询问用户是希望进行轻量梳理，还是记录为文档化决策，然后再继续。

2. 先明确范围，再深入探讨。

   • 根据初始输入判断范围是否已确定：你是否已经能列出需要作出的决策？
   • 如果还不能——边界模糊，或仍有多个方向可选——请先提出范围界定问题，缩小目标。
   • 按照逐步收敛的顺序提出范围界定问题：先问影响最大的边界问题，再逐步缩小范围。
   • 范围明确后，切换为决策树顺序，沿各个分支逐一解决相互依赖的决策。

3. 提问前先利用现有背景信息。

   • 自行解答可通过探索查明的问题：先检查代码库、文档、问题跟踪器或会话日志，并报告发现；只询问探索无法确定的事项。
   • 如果某个会改变决策的问题需要通过运行时观察才能确定（例如，两种渲染方案是否都满足约定的延迟限制），请在现有授权范围内运行成本最低的独立测试或原型；如果需要更多授权，则提出方案并等待。将结果及其关键事实记录在第 8 步中；如果不保留会话记录，则记录在总结中。用观察结果解决事实性问题，并将剩余的产品选择或偏好交由用户决定。如果无法获得证据，请将问题保持为待定，并说明缺少什么。
   • 如果查明所需事实需要耗费较长时间，不要因此让会话停滞：在执行环境允许时于后台开始探索，同时继续处理不依赖该结果的问题；获得发现后再将其纳入讨论。
   • 如果讨论涉及领域术语或架构，请查找 CONTEXT-MAP.md、CONTEXT.md 和 docs/adr/。

4. 默认一次只问一个问题。

   • 每个问题开头都要重述目标和相关的已确定决策。
   • 只询问非显而易见的问题：先问会改变架构的问题，最后再问调整细节的问题。
   • 用具体的边界案例探究领域关系，迫使边界定义明确。
   • 存在真正的替代方案时，给出 2–4 个候选方案——可以是答案，也可以是你提出的选项——并为每个方案附上一句权衡说明，同时说明你推荐的方案及理由。若可行方案超过 4 个，则拆分决策，或指出其余被筛除的方案。
   • 除候选方案外，始终提供一种继续讨论的方式：在结构化选项中加入最后一个“讨论 / 重新解释此问题”选项，或在纯文本中持续邀请讨论。用户选择此项时，先重新陈述问题，再讨论：用简单明了的方式重述问题，说明其前提，并使用本次会话中的规范术语。
   • 根据答案的形式选择提问渠道。简短的选择题在有可用且获准的提问工具时，通过该工具（用于向用户提供选项并提问的结构化工具）提出；需要解释、场景或自由文本作答的问题，则通过普通聊天消息提出，并列出相同的编号候选项。选项集不得因工具而异。
   • 推荐方案必须包含在选项中。工具调用必须是该轮的最后一步：调用后停止并等待回答，不要再发送结束语或重述推荐方案。
   • 只有明确选择才算接受。超时、跳过或过期的提示，以及预选选项，都意味着决策仍未确定：在聊天中重复提问。
   • 优先将相关的简单问题合并提问——仅当问题确实相互独立，即一个问题的答案不会改变另一个问题，且全部属于调整细节而非架构决策时，才在一次提问工具调用中按主题分组。相互关联或涉及架构的问题仍应一次只问一个。批量回答引发讨论时，单独回到该问题。
   • 每个分支解决后，简要说明还有哪些分支待处理。当用户回答变得简短、反复表示“直接决定就行”，或每解决 10 个问题后（不论是否收到相关信号），都应提供一次性解决其余问题的选项：针对剩余决策提出你的建议，让用户接受、调整或暂缓。“直接决定”只确定其所回答的问题，不影响其余问题。

5. 在继续下一个问题前，先解决当前问题。

   • 用户希望讨论时，就该问题继续讨论，直到得出结论、明确暂缓，或记录下存在分歧。
   • 如果用户的回复是问题、异议或澄清请求，而非决策，则转入讨论：在普通消息中详细作答，并以此结束该轮。此时不要调用提问工具；应让用户在对话中自由回应。
   • 只有讨论达成一致，或用户表示已准备好作出决定后，才重新使用提问工具；该工具用于收集决策，而非解释问题。
   • 提出下一个问题前，先回顾当前对话和最新的会话记录，再结合已作出的决策来确定下一个问题。

6. 对不合理或有害的选择提出异议。

   • 如果用户提出的决策看起来有误、存在风险、前后矛盾，或不如现有替代方案，就不要默默照做。
   • 说明当前方案为何更好，或为何替代方案更优；指出用户所提方案的具体缺点，并询问用户是否想讨论或仍要继续。
   • 只有用户确认，或给出有说服力的反驳后，才继续。
   • 记录最终决策；符合 ADR 规则时，创建 ADR。

7. 以文档模式维护项目知识。

   • 对与 CONTEXT.md 冲突的术语提出质疑。
   • 将含糊或含义过多的术语明确为精确、规范的表述。
   • 尽可能根据代码交叉核验用户的说法，并指出矛盾。
   • 解决领域术语后，立即更新 CONTEXT.md。其中只保留术语表，不包含实现细节。
   • 仅在有具体内容可记录时，才创建 CONTEXT.md 或 docs/adr/。
   • 创建或更新 CONTEXT.md 时，使用 references/CONTEXT-FORMAT.md。
   • 在轻量模式下，仅在用户提出要求或出现需要长期保留的项目决策时执行这些操作。

8. 在有用时维护会话记录。

   • 随着决策逐渐明确，创建或更新会话文档。除非仓库已有既定的规划或决策日志位置，否则将其存放在 plans/{yyyy-mm-dd}-{slug}/session.md。
   • 针对每个问题，记录：背景、问题、你的建议、讨论或辩论摘要、最终结论以及后续事项。
   • 同时记录决策背后的关键事实：经核实的研究发现、外部 API 限制、契约细节和被否决的替代方案。不要只记录决策；实施者可能无法看到这段对话。
   • 将当前对话视为即时事实来源，将会话记录视为已确定状态的持久检查点。
   • 内容应足够精炼，能为下一个问题提供指引，但不要写成对话全文。
   • 创建或更新此文档时，使用 references/SESSION-RECORD-FORMAT.md。
   • 在轻量模式下，除非用户提出要求或讨论产生了值得保留的决策，否则跳过会话记录。

9. 根据模式完成综合总结。

   • 综合总结前，检查是否存在未明说的假设：凡是依赖了却从未询问的内容，都要在记录中明确列为已定决策、待解决问题或明示假设；只有不再存在任何未明说的假设时，才能将计划表述为已敲定。
   • 与用户一同敲定完成定义，就像敲定其他决策一样：提出可证伪的验收标准，让用户确认或修正，并在综合总结中说明已确认的标准；只要写入了 plan.md，也要将这些标准记录其中；否则，实现者不能从本次对话中继承任何可检查的“完成”标准。
   • 始终假设实现会在另一个会话中进行，也可能由另一个 Agent 执行。持久文档（plan.md、session.md、ADR）必须是自包含的交接材料。实现所需的每项决策、约束、研究发现、命名选择和集成契约，都必须写入这些文档或其链接的文档；对话上下文会被丢弃。
   • 在轻量模式下，给出已确定的决策、任何明确延期的事项和下一步。
   • 在文档化模式下，提供完整的综合总结：已敲定的计划、已作出的决策、待解决问题、已更新的文档、风险和后续步骤。
   • 按可能被修改的概率排列计划：先写用户最可能调整的决策（数据模型、类型接口、面向用户的行为），最后写机械性强或已充分理解的工作。
   • 对于包含多个实现单元的计划，分别列出每个单元的交付内容、前置条件和完成检查。展示顺序用于审阅；前置条件决定构建顺序。
   • 如果流程、组件交互、数据流、决策分支或构建顺序等结构用图比用文字更容易理解，就在综合总结和 plan.md 或 session.md 中使用图。聊天中用纯文本绘图，记录中用 mermaid，除非仓库现有文档采用其他图示约定。不要把一句话就能说明的内容画成图。
   • 在综合总结中附上对齐测验：用一组简短的选择题检查用户和计划是否对拟建系统的行为达成一致，并考察用户从未仔细推敲过的行为及计划中的关键路径。用户接受后，阅读 references/ALIGNMENT-QUIZ.md 并遵循其中的要求；将任何变更后的决策纳入综合总结和记录。
   • 只要存在会话记录，就还要按照 references/SESSION-RECORD-FORMAT.md，在 session.md 同目录下保存最终计划 plan.md。如果会话恢复后计划有变，则覆盖原文件。
   • 让 plan.md 保持面向未来：说明要构建什么，以及每个部分需要哪些前置条件。决策历史应链接到 session.md，而不是在计划中重复。

ADR 规则

仅当以下三项同时满足时，才提出或创建 ADR：

• 难以撤销：之后更改该决策会造成显著成本。
• 缺少背景时出人意料：未来的读者很可能会追问为何作出此选择。
• 存在真实权衡：确有不同替代方案，且该决策基于具体理由选定其中一种。

创建 ADR 时使用 references/ADR-FORMAT.md。