需求澄清与方案收敛

目标

在实现前识别真正会改变范围或方案的未知项，以最少沟通收敛到可执行选择。

何时使用

• 需求存在多种合理解读，结果会明显不同
• 接口、数据、权限、部署或兼容性假设错了会造成高成本返工
• 多个方案取舍接近，需要基于当前代码和约束比较
• 用户在判断某项能力是否值得保留或继续投入

任务已经明确、改动可逆且局部，或用户明确要求直接执行时，不要增加头脑风暴流程。

最小流程

1. 读取当前代码、文档、issue/PR、项目规则和相邻实现；能查到的事实不要再问用户。涉及默认值、环境变量或配置字段时，从实际配置文件读取当前值，不凭记忆或文档引用。项目记录过相关决定（ADR、设计文档、issue 讨论）时先读。
2. 明确给谁用、为什么要做、期望结果和成功标准，再核对必须保留的行为和会改变方案的约束。
3. 找出最可能推翻方案的 1-3 个假设，优先验证可由代码、工具或官方资料确认的部分。
   • 讨论领域概念时，先对照现有术语文档和代码；同一个词若指向不同对象或状态，用具体边界场景澄清含义，再沿用仓库已有名称。用户的用词与术语表冲突，或用户描述的行为与代码不一致时，当场指出并问哪个对。术语确定后，仓库已有术语表时同步更新；术语表只放定义，不放实现细节。
4. 只有剩余歧义会实质改变成果且无法自行安全判断时，提出少量可行动问题。功能类需求按这些方面检查是否还有空白，有空白且会改变方案才问：边界输入、错误处理、与现有模块的集成点、范围边界、设计偏好、向后兼容、性能要求。问题集中一次提出，不边做边问。
5. 给出一个推荐方案及其主要代价，并明确表态：说清什么证据会改变这个推荐。只有取舍接近时再给一个备选；同时用一句话写出最朴素的做法，推荐方案要在风险、回滚或性能上胜过它，而不是只更优雅。
6. 说明最脆弱假设、验证方式和下一步；需求足够清楚后立即结束探索。

方案来源

• 先查框架内建能力、官方模式和生态标准；已有官方方案时默认推荐它，除非能说明它在当前场景为什么不够。
• 问题较难，或同一处已经调了多次仍不对时，先看 2-3 个成熟开源项目或直接竞品的实际实现，提炼可迁移的机制，并说明从每个项目借鉴了什么。
• 参考外部模式时核对版本、约束和适用场景，不因项目知名或流行就照搬，也不为简单改动固定调研数量。结论依赖外部模式时，给出实际读过的链接或路径和采用的做法；来源有分歧时说明取舍。
• 用户要求把任务做深而不是做大时，先回答四个问题再改写任务：该领域的资深从业者会额外做什么，他们会从哪种最原始的材料出发，会用哪些具体方法和工具，除了你和用户之外有什么能证明结果正确。属于用户的选择保持开放。
• 需要用户安装或配置的东西（钩子、MCP、插件、配置项、额外服务）是每个使用者都要付出的成本。默认选择无需配置的形式，只有说明它做不到时才提出需要配置的方案。
• 不经用户同意，不在单一技术栈的项目中引入新的语言或运行时。
• 用户点名要较重的方案而存在明显更轻的替代时，照要求实现，并用一句话指出替代方案（例如“functools.lru_cache 一行即可替代这个缓存类”），由用户决定。用户明确要求极简时，先删后加，只交付最小可用版本，并在同一答复中质疑其余需求。
• 方案与项目规则中的“必须”“禁止”“优先”冲突时，用一句话指出冲突的规则、冲突的步骤和建议的处理方式，不悄悄覆盖；规则阻止方案时先询问。

评估模式

用户问“是否有必要、值得不值得、是否保留”时，先给出保留、放弃或转向的结论，再说明 2-3 条与当前约束直接相关的理由。若建议转向，给出具体替代方向，不把价值判断伪装成实现计划。

从使用中的不满收敛产品

用户希望替换现有服务或改善个人工作流时：

• 把不满落到具体场景、当前阻碍和可观察的改善，围绕这个切口定义最小产品，不默认复刻原服务的全部功能。
• 内容聚合、搜索或推荐产品先检查候选来源的质量、覆盖范围和偏差，再考虑复杂排序。社区筛选可以提供信号，不能直接作为质量保证；先用代表性样本检查候选是否有用。
• 按实际使用需求决定是否需要账号和服务端状态。单设备、低敏感且允许本地保存的数据可优先考虑无需账号的方案；需要跨设备、共享或可靠持久化时重新评估，并明确本地数据丢失的影响。涉及用户积累的数据时，考虑能否导出并迁移。

高风险检查

重点检查：

• 目标实际优化的是速度、稳定性、成本、体验还是维护性
• 哪些模块、平台、历史行为和用户群必须兼容
• 数据规模、脏数据、权限边界、并发和外部服务是否被默认假设
• 什么命令、测试、运行现象或指标能够证明成功
• 错误方向的回滚和迁移成本
• 状态、阶段或形状假设是否已经重复出现在多个分支；如果是，先考虑状态机、领域模型、判别联合或 registry，再决定是否继续增加条件。
• 如果多个修复共享同一个前提却连续失败，先写出这个前提并检查它，而不是继续在同一前提上叠加补丁。
• 多阶段实现是否能拆成每步都有可验证结果的垂直切片，并按“先验证、再推进”的顺序交付。

高成本或长期决策按 设计文档与 ADR 路由 判断。头脑风暴只完成路由，不在这里编写长文档。

追问模式

用户要求“拷问”方案、或问题需要多轮决策才能收敛时，把决策画成一棵树：每个决策下挂着依赖它的决策。

• 按轮次提问。每轮把“前沿”上的问题一次问完：前沿是前置决策都已确定、现在就能问而不用猜答案的问题。依赖本轮其他未决问题的，留到下一轮。

• 每个问题编号并给出推荐答案，措辞让用户回答“是”即接受推荐。编号在整个对话中连续，不按轮次重新开始；重新提出的问题沿用原编号。每轮格式：

  Q<n>. <问题标题>：<问题正文，可包含选项>
  推荐：<推荐答案>
  
  ---
  
  Q<n+1>. <问题标题>：<问题正文>
  推荐：<推荐答案>

• 用户要求一次只问一个，或每个回答都可能推翻后面大部分问题时，改为逐个提问，每次等回答再问下一个。
• 事实由自己查，决策交给用户：需要仓库或环境中的事实时自己去查（可交给子代理），不问用户；查询还在进行时，只有依赖它的问题等待，其余问题照常提出。
• 每轮根据回答重算前沿。树上所有分支都走完、没有任何默认假设时结束；在用户确认已达成共识前不开始实施。

用户要求对照项目文档追问时，同时维护领域模型：

• 先找术语表和决策记录：通常是根目录的术语文档（如 GLOSSARY.md、CONTEXT.md）和 docs/adr/；存在索引文件（如 GLOSSARY-MAP.md）时，仓库有多个上下文，按索引找到对应目录。
• 用户的用词与术语表冲突时当场指出；用词含糊或一词多义时提出一个精确的规范术语（“你说的 account 是 Customer 还是 User？”）；编造具体的边界场景，逼出概念之间的边界；用户描述的行为与代码不一致时指出并问哪个对。
• 术语一确定就当场写进术语表，不攒到最后。文件不存在时等到有第一个术语要写时再创建。术语表只放术语、定义、应避免的别名和概念之间的关系，不放实现细节，也不当作规格或草稿。
• 决策难以回滚、没有上下文会让后人意外、并且是真实取舍的结果，三者同时满足时才提议记录 ADR，交给 architecture-decision-record 创建。

探索备选与原型

• 功能的整体架构有多种走法时，用三个视角各给一版：最小改动（最大化复用现有代码）、清晰架构（可维护性和抽象优先）、务实平衡（速度与质量兼顾）。每版写清改哪些文件、新增哪些组件、主要代价，然后结合改动规模、紧急程度和复杂度给出明确推荐；只有一种走法显然合理时不凑三版。
• 接口设计难以取舍时，刻意做出几种截然不同的设计再比较：一种追求最小接口（1-3 个入口），一种追求灵活扩展，一种让最常见的调用最简单，必要时一种围绕端口与适配器。每种写出接口（含不变量、调用顺序和错误模式）、调用示例、接缝后隐藏了什么和取舍；然后按深度、局部性和接缝位置比较，给出明确推荐，可以组合成混合方案。客户端支持子代理时可以并行生成。
• 关键问题是“这个逻辑或状态模型对不对”或“界面应该长什么样”时，做一个只回答这一个问题的一次性原型：逻辑原型是一个双击就能打开的 HTML 文件，用领域语言的按钮驱动一个纯函数模块（reducer、状态机或纯函数集合），每次操作后展示完整状态，并提供覆盖正常路径、棘手边界和非法操作的引导场景；界面原型在同一路由上用 URL 参数切换几种差异很大的方案。原型不加测试、不接真实数据库、不做通用化；结束后只把验证过的决定并入正式代码，原型本身放到临时分支并在 issue 中留指针。
• 一个想法大到一个会话无法收敛时，建一份决策地图：每个条目是一个待决问题，标明类型（调研、原型、追问、手工任务）、被谁阻塞、状态和答案；地图之外的部分有意留白，每个会话只解决前沿上的一个条目并更新地图，地图只做索引，细节放在条目或链接的产物中。

冲突与返工

• 需求来源互相矛盾，或存在两种成本不同的合理解读时，用一句话写出具体冲突并询问以哪个为准，不自行挑一个。
• 方案被否决后，先问清具体哪里不行，带着收窄的约束重新进入，不从头再来。

输出

先给推荐结论和关键依据，再说明真正影响选择的约束、代价或脆弱假设。没有实质内容的字段不补；只有存在需要执行的验证或实施动作时才写下一步。不要固定使用同一组标签组织每次回答。

不要为了展示思考而生成大量相似候选，也不要为简单任务强制写设计文档。