X Spec2

---
name: x-spec2
description: |
  精简的系统方案建模 skill。把模糊或跨模块需求收敛成可交给 x-req 的 V2 spec 包，固定产出 spec.md、modules.md，并在跨模块数据流、状态、时序、资源生命周期或故障恢复出现时按需产出 design.md。用户提到 x-spec2、新版 x-spec、系统方案、架构级改造、多个模块或多个后续 task 时优先使用；现有架构归属、状态模型或模块边界尚未闭合时也应使用。
---

# 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：

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

局部静态接口和关键决策留在 modules.md，不变量留在 spec.md。无动态模型时省略 design.md，即使 modules.md 含 D。生成 design.md 后，把对应六元组落点指向其中的真实段落；动态段落可回指相关 D。

### 6. 校验与审核

运行：

```bash
python3 tools/xdev.py validate docs/spec/<spec-name>
```

修复至零 issue，再做语义审核：

1. 混合用户原话已拆为原子 U；行为型 U → Requirement、结构型 U → 模块的目标真实且唯一。
2. J 由 Requirement/D 拉出且都有消费者；来源、证据/推断和确认状态真实。
3. 每个 D 至少引用一个 U/J，选择、理由、备选、否决原因和重评条件完整；模块通过 U/D 回指真实边界来源。
4. Requirement ↔ 模块双向闭合。
5. Requirement → Scenario 可验收。
6. 六元组的适用判断、落点和不适用理由真实。
7. design.md 的生成或省略只由动态模型触发，design.md 未定义 D。
8. 模块状态与证据一致，不稳定模块未开放给 x-req。

明确缺失或矛盾列为 P0。语义证据不足时降低严重度并记录待确认，避免把不确定判断升级成确定错误。发现 P0 后修复并重新运行 validate。

### 7. 交接 x-req

输出需求包路径、产物列表、可进入 x-req 的模块、不稳定模块及其阻塞原因、validate 结果。x-req 从 spec.md 的 Requirement/Scenario 和 modules.md 的边界、依赖、状态拆解 task。

## 更新纪律

更新已有 V2 包时同时检查两个方向：

- 修改 Requirement：同步用户追溯、Scenario、模块回指与六元组落点。
- 修改模块：先读取相关 U/J/D 的来源、理由、备选与重评条件，再同步 Requirement 覆盖、决策记录、依赖、状态与相关 design 动态模型。

仓库事实、推断、暂定默认或关键决策变化，且需求本质、系统目标与不变量保持稳定时，在原包更新相关 J/D 及引用。更新后删除失去消费者的 J/D，并重新运行 validate。

需求本质、系统目标或不变量改变属于意图变化，应新建 spec 包。措辞、证据、边界细化属于原地更新。保持现有包外文件和旧版 `skills/x-spec/` 原样。