su-plan

SU 规划与协商

触发条件

• 用户提出新的实现需求、重构需求或勘探需求。
• 当前任务尚未形成可派工的 spec。
• 现有设计冲突，需要回到方案层重新整理。

输入

• 用户需求描述。
• 项目索引：docs/.ccb/index/*.yaml 与 docs/.catalog.yaml。
• 按需读取的需求、架构、计划文档。

执行流程

Step 0：项目上下文就绪检查

0. 检查 docs/.ccb/index/project.yaml 是否存在。
   • 若不存在（空项目初始化后首次运行），自动扫描项目结构并生成。
   • 若存在，读取项目事实作为后续分析的基础。

Step 1：需求分析

1. 判断任务复杂度是简单、中等还是复杂。
2. 明确是否需要输出需求文档；简单任务可直接进入 spec，复杂任务先写需求或设计文档。
3. 自动发起协商：通过 ask <provider> --foreground 向 Codex 发起 mode: consult 协商请求，收集对代码现状的意见和可行性分析。
4. 等待用户确认需求（🔴 必审门）。

Step 2：技术设计

5. 通过索引定位架构与模块信息。
6. 自动发起协商：通过 ask <provider> --foreground 向 Codex 发起技术方案协商，收集实现可行性、技术最优解、风险评估。
7. 根据 Codex 回复中的 analysis_depth_hint 自动触发 SuperClaude 深度分析。
8. 进行方案对比、风险分析与关键决策说明。
9. 等待用户确认设计（🔴 必审门）。

Step 3：任务切片

10. 判断模式是实施、半开放实施还是勘探。
11. 将任务拆成可验收切片，写出 20-50 行的精简 spec。
12. 生成面向 su-dispatch 的派工摘要。

多轮协商机制

协商触发时机

• Step 1 需求分析：当需求涉及代码现状理解、可行性判断时自动触发
• Step 2 技术设计：当需要方案对比、架构影响评估时自动触发

协商轮次控制

• soft_max_rounds = 3：大多数情况足够收敛
• hard_max_rounds = 5：架构权衡可能需要 4-5 轮
• Claude 把控轮次，不由 Codex 或用户控制

自动停止条件

Claude 在以下任一条件满足时终止协商：

• Codex 返回 status=blocked
• 所有决策关键问题已回答
• 连续两轮：status=answered + 无新 findings + 无新 open_questions + recommendation 稳定
• 达到 hard_max_rounds
• 剩余开放问题均为低影响可逆决策

到达上限后的行为

场景	动作
低风险、可逆、局部决策	Claude 带假设冻结设计
高影响、跨模块、契约/模式/流程决策	升级给用户
上下文不足	升级给用户或要求更多源材料

协商产出归档

• 默认：Claude 生成结构化摘要，嵌入 Step 1/2 设计文档
• 重大决策：额外写入 ADR（.ccb/decisions/）
• 摘要包含：讨论主题、考虑的选项、Codex 建议、Claude 最终决策、理由、未解决风险

上下文传递规则

• 每轮传递滚动结构化摘要，不传完整历史
• confirmed_conclusions：上限 5-8 条
• open_questions：仅当前未解决项
• delta_since_last_round：round > 1 时必填

SuperClaude 集成

必须触发

• 进入 Step 2 技术设计的协商前，触发 /sc:design [目标摘要]

条件触发（由 Codex 回复中的 analysis_depth_hint 驱动）

Codex hint	SC 命令	触发规则
sc-brainstorm	/sc:brainstorm	Step 1，需求仍模糊/目标冲突/范围未拆解
sc-design	/sc:design	架构边界/模块拆分/接口设计需深度推理
sc-analyze + security	/sc:analyze --focus security	安全风险高影响且影响设计选择
sc-analyze + performance	/sc:analyze --focus performance	性能在关键路径
sc-spec-panel	/sc:spec-panel	≥2 个可行设计 + 权衡高影响或跨模块
sc-estimate	/sc:estimate	需要规模估算来决定拆分/顺序/资源
sc-troubleshoot	/sc:troubleshoot	协商主题是故障诊断
sc-research	/sc:research	缺失信息是仓库和文档之外的外部信息
human-decision	不触发 SC	升级给用户，SC 不替代用户权威

建议触发

• 方案需多专家审查时：/sc:spec-panel [spec 路径]
• 任务复杂需结构化工作流时：/sc:workflow [PRD 路径]
• 需要工作量评估时：/sc:estimate [任务描述]

输出格式

• 需求理解摘要。
• 协商结论摘要（如有协商轮次）。
• 技术方案摘要。
• 任务模式与切片说明。
• 精简 spec 路径或草案正文。

停止条件

• 用户已确认需求与设计。
• 当前任务已有可派工 spec。
• 每个切片都具备清晰的边界与验收标准。

升级条件（回抛给用户）

• 需求仍然模糊，无法描述到"可编码"。
• 方案对比后仍无法确定关键方向。
• 出现高影响决策需要用户兜底确认。
• 协商达到 hard_max_rounds 且仍有高影响未决问题。