x-spec2

x-spec2

x-spec2 负责把系统意图建模成稳定需求与模块边界。task 拆解属于 x-req；x-spec2 通过准确的 Requirement、Scenario 和模块映射保护后续拆解方向。

产物

在 docs/spec/<spec-name>/ 中生成：

• spec.md：必需。需求说明、原子用户要求追溯、判断依据、六元组覆盖、Requirement/Scenario 验收。
• modules.md：必需。模块职责、依赖、接口、风险、关键决策、状态及 Requirement 回指。
• design.md：按需。跨模块数据、状态、时序、资源或故障动态模型。

保持包内只有这 2+1 件。不要生成 README、task-map、diagram、task.md、tasks.md 或 dev-checklist；x-req 根据稳定 spec 拆 task。

模板位于 templates/。生成前完整读取对应模板，填充内容后删除 HTML 注释和占位符。

工作流

1. 收敛需求

从用户对话与仓库证据提取：

• 需求本质：用户真正要改变的系统结果。
• 范围：包含、排除、延后。
• 约束：技术、业务、兼容、权限、时间与运维边界。
• 不变量：任何实现都必须持续成立的规则。
• 用户原话：按单一意图拆成原子要求，保留原意；一句同时包含行为要求和结构指定时拆成两条 U。
• 验收：每条 Requirement 至少一个可判定 Scenario。

影响系统目标、范围或不变量的缺口需要先向用户确认。用户授权全权处理时，记录推断依据与待确认项后继续。

2. 调研现状

读取相关代码、文档、配置、日志与既有 spec，确认可复用模块、事实源、现有边界和约束。新项目可跳过代码复用调查。

3. 写 spec.md 并确认

使用 templates/spec.md：

1. 每条原子用户要求分配唯一 U-ID 并填写对应目标和包内落实锚点：行为型 U 回指唯一 Requirement；用户直接指定模块边界的结构型 U 回指 modules.md 中的模块。
2. Requirement 名保持唯一；每条 Requirement 至少一个 Scenario。
3. Scenario 包含 WHEN、THEN 与独立一行 验证: auto|manual；GIVEN 按需。
4. Requirement 或关键决策需要用户原话之外的事实、外部规范、LLM 推断、暂定默认或待确认项时，按需拉出唯一 J-ID 写入“判断依据”，并从消费位置引用。不要预枚举无消费者的 J。
5. 每个 J 写明判断、来源类型、可定位证据或明确推断说明、确认状态；直接用户要求复用 U，不复制成 J。
6. 六元组逐项填写有效的 文件#段落锚点 或具体的不适用理由。
7. 需求本质、系统目标、范围或不变量发生变化时，先让用户确认新的意图。

用户确认 spec.md 后再稳定模块设计，防止模块反向塑造需求。

4. 写 modules.md

使用 templates/modules.md。模块来自 Requirement 所需能力的聚合，每个模块至少回指一个 Requirement，每个 Requirement 至少被一个模块承接。

modules.md#关键决策 是 D-ID 的唯一真源。模块拆分、依赖方向、边界类、数据归属、协议或迁移存在合理备选，或选择会显著约束未来修改时，创建 D，记录最终选择、至少一个 U/J 依据、选择理由、真实备选与否决原因、重评条件。design.md 只消费 D，不定义 D。

模块总览的“决策回指”只使用：

• U-ID：用户直接指定该模块边界，且该 U 的对应目标就是本模块。
• D-ID：模块拆分、依赖、边界类或数据归属由方案设计产生。

每个模块写清职责、依赖、边界类或对外契约、核心接口/数据、风险和状态。字段与当前需求无关时写简短理由，避免展开通用设计教材。

状态只使用：

• 探索中：目标或边界仍待确认。
• 方案确认：边界与验收已定，仍未开放给 x-req。
• 可进入 x-req：可以派生 task。
• 开发中：x-req 已派生 task 并进入实现。
• 已完成：派生 task 已完成验收。

处于探索中或方案确认的模块属于不稳定模块，交接时明确禁止进入 x-req。

5. 判断 design.md

出现以下任一动态关系时，使用 templates/design.md 生成 design.md：

• 数据跨模块产生、转换、传递或持久化。
• 实体具有多状态流转、状态所有者或恢复状态。
• 调用顺序、并发、重试、超时或事件先后影响结果。
• 资源具有生命周期、容量、配额、锁或释放责任。
• 依赖失败、部分失败、补偿、回滚或恢复路径影响结果。