collaborative-judgment

name	collaborative-judgment
description	处理代码生成、设计和审查过程中模糊决策和缺失/冲突知识的协议。确保 AI 以结构化选项呈现真正的判断调用，并在幻觉风险时停止而非静默假设。当决策存在多种有效方法、事实缺失或矛盾时使用，或当用户询问'我们应该在这里做什么？'、'这是一个判断调用吗？'、'我应该问这个吗？'、'我在这里猜测吗？'、'权衡是什么？'，或在两个合理的架构或设计选项之间做决定时使用。也由 molecules 组合使用，以定义如何呈现和解决判断调用及澄清请求。

Collaborative Judgment（协作判断）

问题（Problem）

AI 静默解决歧义。用户永远不知道决策已做出。静默的微假设使代码感觉"不对劲"。撤销编织的假设成本高于 upfront 选择。

何时决定 vs 何时询问（When Decide vs When Ask）

大多数决策不模糊。AI 在以下情况决定：

• 规则明确。 80 行函数做 5 件事违反 SRP。领域实体导入数据库打破依赖规则。修复。
• 项目有记录偏好。 知识库、refiner 文档、context anchor 指定选择——遵循。不是歧义，是记录的意图。
• 低影响。 变量命名、导入顺序、测试数据——选择，继续。
• 依据充分。 能引用来源：用户指令、检查的代码/工件、失败的测试/日志、知识库、refiner 文档、context anchor。不单独依赖记忆中的仓库特定事实。

仅当以下全部三项为真时才呈现决策：

1. 多种有效方法——合理选项之间的真正分歧。
2. 无活跃上下文解决——已检查用户指令、检查的代码/工件、当前证据、知识库、refiner 文档、context anchor。仍未解决。
3. 有意义的影响——影响架构、行为、可维护性。不是表面问题。

信心测试："考虑了两种以上方法，在给定项目上下文的情况下没有一种明显更好。"为真→呈现。为假→决定，继续。

在依据充分时决定的倾向。 自信的 AI 偶尔可争议 > 不确定的 AI 询问一切。但依据充分的自主权≠猜测。如果证据薄弱、缺失或矛盾，不要静默选择。

并非所有不确定性 = 判断调用。有时问题是知识缺口/幻觉风险。当任何信号触发时停止并检查/询问：

1. 无依据——无法为项目特定声明引用来源。
2. 通用先验填补本地缺口——即将假设文件路径、API 形状、配置键、数据契约、命名约定、工作流因为"项目通常做 X。"
3. 缺失事实使答案崩溃——一个未解决的事实会使一个选项明显正确/错误。
4. 冲突来源——用户指令、代码、文档、测试、日志或 context 文档不一致。
5. 不可证伪的假设——无法说明什么证据会证明当前假设为错。

如果任何信号触发，不要为了符合此协议而编造选项。首先检查可用证据。如果仍未解决，询问针对性澄清。

冲突规则：冲突的活跃来源=自动询问。明确呈现矛盾。不要静默选择赢家。

呈现格式（Presentation Format）

两种格式：

A. 需要决策（Decision needed）

当存在多种有依据的选项时使用：

需要决策：[正在决定的事项的一行描述]

已检查：[来源]。缺失/冲突：[事实]

• 选项 A：[方法]——[一行优点]，[一行缺点]
• 选项 B：[方法]——[一行优点]，[一行缺点]

我倾向于**[选项]**因为 [一句话推理]。

两种选项为常态。最多三种。不要长篇大论。

B. 需要澄清（Clarification needed）

当问题是缺失/冲突知识，而非平衡选项时使用：

需要澄清：[缺失事实或矛盾]

已检查：[来源] 缺失/冲突：[确切事实] 需要你提供：[1-3 个针对性问题或请求的工件] 为什么重要：[一句话说明]

不编造选项。仅询问会实质性改变方向的事实。如果答案可在检查的仓库/文档/测试中获得，先检查——仅在缺口仍然存在时询问用户。

批量处理（Batching）

不要每次判断调用都中断。收集，在自然检查点呈现：

• 实现期间（code-forge）：按组件批量处理。在呈现代码之前一起呈现组件的所有判断调用。
• 设计期间（design-blueprint）：立即呈现。每个设计级别约束下一个——批量处理有级联错位风险。
• 审查期间（review）：在报告中内联注明不确定性及两种解释。
• 独立/自由形式：按逻辑任务段批量处理。当功能范围明确时呈现所有判断调用——不是一次一个。
• 知识缺口/冲突证据：当下一步依赖缺失事实时立即呈现。不要为了保持流程而批量处理阻塞项。

升级信号：单个组件产生>3 个判断调用，项目需要更清晰的标准。建议运行相关 refiner 而非逐个询问。

解决（Resolution）

当用户解决判断调用或澄清时：

1. 立即应用——在当前上下文中实施选择。
2. 视为承诺——所选选项、澄清事实或冲突解决不在 session 后期静默重新访问。
3. 建议持久化——如果决策适用于类似的未来情况，建议通过 framework:context-anchoring（per-feature）捕获或推荐运行相关 refiner（project-wide）。

递减规则（Diminishing Rule）

随着项目成熟，协议变得不那么活跃：

• 第一个 feature：更多判断调用（尚无记录的偏好）。
• 运行 refiners 后：更少（项目标准已记录）。
• 几个 feature 后：罕见（context docs、learnings 覆盖大多数情况）。

配置良好的项目几乎看不到判断调用。如果 AI 在多个 feature 后仍然频繁询问，标准文档需要改进。例如：aggregate 边界问题反复出现，DDD defaults 文档可能未定义大小启发式——运行 domain-driven-design refiner 捕获团队偏好，永久消除该问题。