X Spec

---
name: x-spec
description: |
  系统方案规划 skill。产出 docs/spec/<spec-name>/ 下的独立需求包（目标与 DoD + 组件设计 + 接口/数据结构 + 核心流程时序 + 验证策略 + task 映射）。
  当用户给的是模糊想法而非具体功能需求时使用。触发场景：
  "这个东西怎么设计"、"帮我梳理整体方案"、"先别写代码把方案理清"、
  "这个系统该怎么拆"、"x-spec"、架构级改造、
  一个系统切面会派生多个 task 需要先建 spec 需求包。上下文不足时先进入头脑风暴模式，收敛后再保存 spec 文档。
  入口选择：小功能小修复由 x-req 定级 Q0/Q1；已有明确需求走 x-req。
---

# x-spec 系统方案规划器

## 核心定位

x-spec 是方案型 skill，负责把一个模糊的系统想法整理成可导航、可拆分、可演进的方案文档体系。

x-spec 负责：
1. 从**第一性原理**推导用户需求的本质：用户真正要改变的系统结果、关键约束、不可破坏的不变量
2. 判断当前上下文是否满足 spec 立项所需目标；缺关键目标时进入头脑风暴模式
3. 给出合理设计方案，并为每个关键判断写明判断依据、这样做的原因、缺失后的后果
4. 产出系统级方案目录和总导航 README
5. 拆分系统模块，定义模块职责、边界、依赖、状态
6. 标记哪些模块已足够稳定，可以进入 x-req
7. 建立 spec 需求包与 task 的映射关系
8. 还不够稳的模块要在90-task-map.md进行记录，并写清楚需求还没确认，不能进入开发

绝对禁止:
- 需求目标不明确就糊弄过去
- 用户没同意就强行保存文档，除非用户说你全权负责
- 当前环境下过度设计

**核心边界：**
x-spec 输出系统组织方案；具体代码开发进入 x-req / x-dev。

## 第一性原理产物链路

```text
事实 / 约束 / 不变量 / DoD
→ 必要能力集合
→ 模块划分
→ 边界类
→ task
→ 验证方式
```

---

## 适用场景

以下情况优先使用 x-spec：
- 用户给的是模糊想法或系统方向
- 涉及多个模块、多个阶段、多个 task
- 方案讨论比代码实现更重要
- 当前不确定该不该拆分
- 一个文档可能会非常长，需要拆成导航 + 子文档
- 需要先形成系统级共识，再进入开发

以下情况优先走其他入口：
- 小功能、小修复、单文件改动 → x-req 定级 Q0/Q1
- 已经有稳定需求报告（README.md），只差 dev-checklist/dev → x-req
- 用户明确要求立即开发一个清晰范围的功能 → x-req 定级后续接 x-dev

---

## 文档生成规则

模板是文档格式正源，skill 本体只负责判断、收敛、调度和审核。

- 先读 `skills/x-spec/templates/TEMPLATE_GUIDE.md`，再复制各模板写入 `docs/spec/<spec-name>/`
- 图表规范以 `skills/x-spec/templates/TEMPLATE_GUIDE.md`「图表规范」为准：图内嵌于其文字真源文件（不单设图集），默认只画 `03-core-workflows.md` 的核心时序，其余按需
- 路径引用规则以 `skills/x-spec/templates/TEMPLATE_GUIDE.md` 为准
- 每个关键结论都要回答：为什么重要、判断依据、缺失后的后果、落到哪个产物

### 原则

- **spec 需求包是独立可传递的文档包**：拿走 `docs/spec/<spec-name>/` 给任何人，不依赖 `dev-pipeline/tasks/`
- `docs/spec/README.md` 只做导航和 spec 状态汇总，不堆内容
- spec README 只做导航和目标概述，细节在子文档
- 子文档按编号排序，方便顺序阅读

### 路径引用规则（硬约束）

spec 需求包必须能整体移动。**规则条文正源：`templates/TEMPLATE_GUIDE.md`「路径引用规则」；机器把关：`python3 tools/xdev.py validate <包目录>`（规则 V2）**——本节不复读条文。速记：包内链接只用 `./...`，代码路径只写 `repo:<path>` 纯文本。

## 状态定义（真源）

spec 与模块共用以下状态机；其它位置只引用本节，不再重复枚举取值。

- 探索中：边界未定，仍在收敛
- 方案确认：边界与 DoD 已定，尚未拆 task
- 可进入 x-req：可派生 task 进入 x-req
- 开发中：已派生的 task 正在实现
- 已完成：派生的 task 全部完成并验收

spec 状态反映整个需求包的进度；模块状态反映单个模块的进度；两者取值范围相同。

## 子 agent 使用边界（真源）

公理：子 agent 没有对话上下文（能力弱）。因此 x-spec 里子 agent 只有两个角色，共同形状：**只读、只回带指针（文件+行号）的判定/证据清单、不生成产物内容**——判定 + 指针一跳可核实（让谎言昂贵），而总结/扩写的忠实性要重读全文才能核对，核实成本 ≈ 自己写，必亏。

- **斥候**（步骤 3，可选）：调研现有代码，回收可复用清单
- **裁判**（步骤 6.2）：以 01 为公理审核产物，回收 P0/P1 判定清单

生成/总结/扩写类任务（写文档、压缩、改写）一律留在主窗口——生成需要用户意图，意图只在主窗口对话里。

---

## 工作流程

### 1. 上下文充分性判断

先判断当前上下文是否已经足够进入文档模式。判断结果写成临时工作记录，后续灌入 `README.md` 与 `01-goals-and-boundaries.md`。

| 必须目标 | 满足标准 |
|---------|---------|
| 需求本质 | 能说清用户真正要改变的系统结果 |
| 成功标准 | 能写出可验证 DoD、可观察证据、验收入口 |
| 范围边界 | 能区分包含、保留、延后、排除 |
| 关键约束 | 能列出技术、业务、时间、兼容性、权限、运维约束 |
| 系统不变量 | 能列出任何方案都必须保持成立的规则 |
| 现状依据 | 能找到代码、文档、配置、日志、用户描述中的证据 |
| 推荐方案 | 能给出方案、理由、代价、风险、失败场景 |
| 模块边界 | 能判断模块归属、边界类、依赖方向 |
| 数据和状态 | 能判断核心实体、状态归属、持久化策略 |
| 验证策略 | 能说明 smoke/e2e、单元、契约、边界测试的落点 |
| task 拆分 | 能判断哪些模块可进入 x-req、哪些仍停留在方案层 |

每个目标都要写清：
- **判断结论**：已满足 / 待确认 / 缺失
- **判断依据**：来自用户输入、现有代码、文档、配置、日志或明确推断
- **为什么重要**：它会保护哪个系统结果或协作边界
- **缺失后果**：继续写 spec 会产生的偏差、返工或风险
- **下一动作**：进入文档模式 / 进入头脑风暴模式 / 向用户提问 / 先调研代码

### 2. 头脑风暴模式（上下文不足时）

任一 P0 目标缺失时先进入头脑风暴模式。该模式用于收敛 spec 输入，产物是对话中的决策记录和后续文档里的 Framing Summary。

必须完成：
1. **第一性原理推导**：把需求还原为目标、事实、约束、不变量、可重新评估的历史假设
2. **需求本质**：用一句话说明用户真正要达成的系统结果
3. **方案空间**：给出 2-3 个合理方向；每个方向写明适用条件、代价、风险、失败场景
4. **推荐方案**：说明当前证据最支持的方向，以及选择它的判断依据
5. **后果说明**：解释这样做保护了什么；继续缺失关键目标会导致什么后果
6. **待确认问题**：只问会改变 spec 方向的问题，每轮最多 8 个

可使用的判断原则：
- **第一性原理**：从目标、事实、约束、不变量重新推导方案
- **奥卡姆剃刀**：优先选择模块更少、状态更少、协议面更小、迁移成本更低的方案
- **贝叶斯判断**：根据证据更新方案置信度，把不确定项转成调研或提问
- **对抗性检验**：主动寻找会让方案失败的输入、状态、权限、并发、回滚、兼容性场景
- **可证伪性**：关键判断必须能被代码、日志、测试、配置或用户确认验证

提问规则：
- 问题必须指向 spec 范围、验收标准、模块边界、数据归属、兼容性或方案选择
- 用户说“不要问了直接做”时，按已有信息产出，并在文档中标注待确认项

### 3. 现有资源调研（手里有什么牌）

上下文充分性判断完成后、拆模块前，**LLM 主动调研**（同时读取本地证据）：

- 扫项目代码结构，找已有的可复用模块/函数
- 找已有的相似功能（避免重复造轮子）
- 找已用的第三方依赖（影响技术选型）
- 找已有的数据格式/存储（影响数据结构设计）
- 汇总"可复用清单"给用户确认
- 如果发现现有架构不满足新增当前需求功能，则必须提醒用户需要进行老模块优化

调研执行方式（二选一）：

- **仓库小或主 agent 已熟悉**（默认）→ 主 agent 直接扫
- **仓库大或不熟悉** → 派只读斥候子 agent（边界见「子 agent 使用边界」），任务书四件套：
  1. 带上需求本质——不说明"为了什么找"，斥候不知道"可复用"对谁可复用
  2. 每条结论必须带 `文件:行号` 证据
  3. 显式允许负结果："没找到可复用项"如实回报，禁止硬凑
  4. 只读禁改，只回结构化清单
  斥候回报后，主 agent 抽查核实至少一条再采信。

如果是全新项目（无已有代码）→ 跳过本步，直接进拆模块。

### 4. 判断是否需要拆系统

满足任意两项，则建议拆模块：
- 涉及多个代码包或层
- 可独立测试的子能力超过 3 个
- 预期会拆成多个 task
- 单文档预计过长
- 模块之间依赖关系明显
- 用户自己也不确定边界

匹配度较低时，建议进入 `x-req`：小改动定级 Q0/Q1；单功能在同一入口完成澄清与拆解。

### 5. 拆分系统模块

#### 模块来源规则

- 模块不能直接从技术名词、目录习惯或用户口头模块名生成。
- 每个模块必须由一个或多个必要能力聚合而来。
- 每个模块必须能追溯到 DoD、约束或不变量。

每个模块至少定义：
- 模块名称
- 职责
- 包含范围
- 不包含范围
- 依赖
- **边界类**（模块唯一对外入口，命名见下方设计原则）
- 数据结构/接口（对外暴露的核心类型）
- 复用/新建标注（步骤 3 的调研结论）
- 风险等级（高/中/低）
- 当前状态

#### 模块边界设计原则（硬性，开发类任务必须遵守）

- **每个模块对外只暴露一个边界类**作为唯一入口：业务域用 `<模块>Service`、资源/生命周期域用 `<模块>Manager`、对接外部系统用 `<系统>Client` / `<系统>Gateway`、数据持久层用 `<实体>Repository`
- **模块内功能统一由边界类收口调用**，禁止散装函数跨模块直接调用。判定标准："改一个能力只动一处"——跨文件改多处就是边界没收口
- **模块内高内聚、模块间低耦合**：模块外的代码只 import 边界类，grep 不到对模块内部函数的直接引用
- **文件级信号配合类名**：Python 内部实现用下划线前缀文件/函数 + `__init__.py` 只导出边界类（显式 `__all__`）；TS 只从 `index.ts` 导出边界，内部实现放 `internal/`

#### 内部功能需要对外暴露时（决策规则）

按序判断：
1. **是本模块能力** → 边界类加委托方法（转发时顺手补校验，维持不变量），内部函数保持私有
2. **是通用工具**（与本模块业务无绑定）→ 提取到共享底层模块（`common/` / `core/`），双方都走它的边界
3. **外部需要的内部能力多到边界形同虚设** → 模块边界画错了，回 x-spec 重新拆

**禁止**：直接 import 内部函数（如 `from mod._internal import foo`）/ 为一个调用方批量 re-export 内部文件 / 复制实现到调用方。

模块状态取值见「状态定义」。

### 6. 生成文档（主 agent 亲写全部 + 裁判审核）

**强约束**：spec 包内全部 7 个产物文件（README/01/02/03/04/05/90）由主 agent 亲自写。生成需要用户意图，而意图只在主窗口的对话里——扩写/总结类子 agent 没有对话基准，会产出"貌似合理的发明"且审核抓不住（见「子 agent 使用边界」）。

**模板落点**：DoD 追溯写入 `01-goals-and-boundaries.md`；风险标注写入 `02-module-breakdown.md`；PoC 和排序依据写入 `90-task-map.md`；具体写法以 `templates/TEMPLATE_GUIDE.md` 为准。

#### 6.1 写作顺序（主 agent）

01 是存档点：长头脑风暴后窗口吃紧时，以落盘的 01 + 用户确认结论为基准续写，不依赖窗口内的对话副本。

1. **`01-goals-and-boundaries.md`**（模板 `templates/01-goals-and-boundaries.md`）：
   - 第一性原理推导 / 目标充分性判断（步骤 1-2 结论）
   - 需求要点（步骤 1-2 对话提炼）
   - **用户要求与证据表**：逐条记录用户在追问中提出的原始要求，每条标注它在文档包里的落实位置（文件 + 段落/锚点）。裁判审核逐条核对，证据缺失 = P0
   - 系统目标 / 成功证据 / DoD / 范围边界 / 关键约束 / 系统不变量
   - DoD ↔ 模块追溯矩阵（TEMPLATE_GUIDE 的 DoD 追溯规则）
   - 交用户确认前快速自查：追溯矩阵双向闭合、DoD 可验证不空话
2. **`03-core-workflows.md`（核心流程）**：流程文字 + 时序图同文件（最小可用路径必写必画、含错误路径；最高风险链路与 E2E 验收链路可选）。跨模块的调用顺序/错误路径/异步边界只在这里显性化，它是设计判断的载体，随 01 一起交用户确认；总览/局部/状态/数据图默认不画，按需内嵌各自的文字真源文件（见 TEMPLATE_GUIDE「图表规范」）
3. **用户确认（第一级审核；基准 = 用户意图，只有用户持有）**：
   - 需求要点是否忠于用户原意
   - 范围边界 / "不包含"是否对
   - MVP 链路选得对不对——对着核心时序图确认
   - 用户有异议 → 主 agent 改 01/图后重新确认；要求的改动数计入 run 记录 `user_edits`
4. **`02-module-breakdown.md`**（组件设计 + 接口 + 数据结构 + 风险标注——设计判断，不外包）
5. **`04-data-and-state.md`**（核心数据模型 + 状态流转）
6. **`05-validation-and-evolution.md`**（验证策略 + 测试 + 演进）
7. **`90-task-map.md`**（组件→task 映射，依据 01 追溯矩阵 + PoC 排序）
8. **`<spec>/README.md`**（最小可用路径、模块导航、当前建议）+ **`docs/spec/README.md`** 索引

#### 6.2 裁判审核（子 agent，一次性、只读）

7 文件全部落盘后，**主 agent 先跑 `python3 tools/xdev.py validate <spec目录>`**——机械项（文件齐全 / 路径规则 / Requirement-Scenario 结构 / 02↔90 清单一致 / 状态取值）由工具零成本把关，validate 零 issue 后才派裁判，机械项不占裁判窗口；validate 的 issue 编号（V1-V7）可写进 run 记录聚合。

然后派裁判。裁判没有对话上下文——这不是缺陷是特性：写作者自审只能看到"想写的"，fresh eyes 才看得到"实际写的"。基准已外化且经用户确认（01），裁判拿 01 当公理审下游。

> 禁止让裁判审 01 对用户意图的忠实性——那一层基准只有用户持有，已在 6.1 第 3 步完成。

```
Agent({
  description: "x-spec 裁判审核",
  subagent_type: "general-purpose",
  prompt: <短任务书，不塞文档全文（基准与产物都在盘上，裁判自己 Read）：
    - 审核目录 docs/spec/<spec-name>/，以其中 01-goals-and-boundaries.md 为公理基准
    - 只读禁改：不允许修改任何文件
    - 按规则 R1-R8 逐条审核（规则全文贴入），每条 issue 必须带 文件+行号/锚点 证据
    - 显式允许负结果：某规则查无问题就写"未发现"，禁止硬凑 issue
    - 输出只准是按回报模板的判定清单，禁止复述或总结文档内容>
})
```

审核规则（issue 按编号回报，编号进 run 记录聚合）：

| # | 规则 | 等级 |
|---|------|------|
| R1 | 忠于 01：02/03/04/05/90 的模块、组件、数据结构不与 01 的需求要点、模块拆分冲突 | P0 |
| R2 | 追溯闭合：每条 DoD 有模块支撑、每个实现模块回指 DoD；每个模块可追溯到 DoD、约束或不变量 | P0 |
| R3 | 证据表落实：01 用户要求与证据表每条指到的位置真的落实了该要求 | P0 |
| R4 | task 来源闭合：每个 task 回指模块 + DoD；不稳模块记录在 90 且标"需求未确认，不能进入开发" | P0 |
| R5 | 判断依据完整：推荐方案、模块边界、数据归属、验证策略写明为什么重要、判断依据、缺失后果 | P0 |
| R6 | 文档间一致：02 模块清单 / 03 时序图中的模块与边界类名 / 90 映射对得上；每个模块定义了边界类 | P0 |
| R7 | 机械项已由 `tools/xdev.py validate`（V1-V7）前置把关，裁判不重查；仅当 validate 输出未附或有未修 issue 时记 P0。图内嵌于文字真源、无孤立图集仍由裁判目检 | P0 |
| R8 | 数据结构字段中文注释、图表格式、task 排序依据强度 | P1 |

裁判回报模板：

```markdown
## Judge Report

**Status:** done / blocked

| # | 判定 | 证据（文件 + 位置） |
|---|------|---------------------|
| R1 | 未发现 / P0：<一句话> | `02-module-breakdown.md#模块-a` |
```

#### 6.3 修复（主 agent 直接改）

- 主 agent 对裁判清单**先抽查核实至少一条**——issue 也不是地面真值，指针指到的原文才是；核实不成立的驳回，计入 run 记录 `judge_fp`
- 成立的 P0 主 agent 直接 Edit 修复（基准与文件都在主窗口，成本最低，无重派分支）；P1 顺手修掉，避免永久遗留
- 修复后重跑 `python3 tools/xdev.py validate`（机械项复查，零成本），不重派裁判
- 无 P0 → 直接进步骤 7（剩余 P1 列给用户参考，不阻塞）

spec README 必须包含：
- spec 目标
- **最小可用路径**（MVP 链路，一句话描述核心路径）
- 组件导航 + 状态表
- 文档导航
- 当前建议

spec 索引 README 必须包含：
- spec 族职责（一句话）
- spec 导航表（名称 + 状态 + 说明）

### 7. 给出下一步建议

必须给出明确结论：
- 哪些模块继续留在方案层
- 哪些模块可以进入 x-req
- 高风险模块是否建议先 PoC
- 是否建议现在就拆 task

---

## 模板文件

所有模板在 `skills/x-spec/templates/` 下，LLM 产出时复制对应模板并填充内容：

| 模板文件 | 对应产出 | 层级 |
|---------|---------|------|
| `templates/TEMPLATE_GUIDE.md` | 模板说明：字段、路径、图表、审核规则 | skill 内部参考 |
| `templates/module-README.md` | spec 索引导航 | `docs/spec/README.md` |
| `templates/README.md` | spec 导航 | `docs/spec/<spec-name>/README.md` |
| `templates/01-goals-and-boundaries.md` | 目标 + 完成标准 + 范围 + 用户要求与证据 | spec 目录 |
| `templates/02-module-breakdown.md` | 组件设计 + 接口 + 数据结构 | spec 目录 |
| `templates/03-core-workflows.md` | 核心流程文字 + 时序图（E2E 验收链路可选） | spec 目录 |
| `templates/04-data-and-state.md` | 核心数据模型 + 状态流转 | spec 目录 |
| `templates/05-validation-and-evolution.md` | 验证策略 + 测试 + 演进 | spec 目录 |
| `templates/90-task-map.md` | 组件→task 映射 | spec 目录 |

---

## 输出要求

完成后，必须向用户明确说明：
1. 该模块是否还需要拆更多 spec
2. 当前 spec 的状态（取值见「状态定义」）
3. 哪些 spec 适合先进入 x-req
4. 哪些 spec 仍应停留在方案层
5. 文档保存路径：`docs/spec/<spec-name>/`
6. 审核结论：裁判 6.2 发现的 P0（已修复 / 驳回误报分别注明）+ 遗留 P1（参考项，不阻塞）
7. run 记录已追加至 `docs/spec/run-log.jsonl`（字段与退场判据见「run 记录与退场判据」）

如果用户仍然很模糊，优先产出最小 3 文件，其余文档标为后续扩展。

---

## run 记录与退场判据（埋秤）

每次 x-spec 运行结束（步骤 7 完成后），向 `docs/spec/run-log.jsonl` **追加**一行（append-only；仅 `late_issues` 事后发现时允许回补对应行）：

```json
{"ts":"YYYY-MM-DD","spec":"<spec-name>","mode":"new|update","duration_min":38,"confirm_rounds":2,"user_edits":3,"judge_p0":["R2@02:45 追溯缺口"],"judge_p1":[],"judge_fp":1,"late_issues":0,"repairs":[{"item":"R2","by":"main"}],"notes":"一句话"}
```

字段只收观察得到的，不收测不准的（如 token 数）：

- `confirm_rounds`：用户确认往返数（6.1 第 3 步）
- `user_edits`：用户确认环节要求的改动数——主 agent 一版质量信号
- `judge_p0` / `judge_p1`：裁判 issue，按规则编号——模板进化数据
- `judge_fp`：主 agent 核实后驳回数——裁判质量信号
- `late_issues`：裁判放行后用户或下游又发现的问题数——裁判漏报信号

预注册退场判据——看到什么就做什么，防止度量退化成仪式：

| 信号 | 动作 |
|------|------|
| `user_edits` 持续 ≥3 | 病在 01 之前的收敛环节 → 改步骤 1-2（充分性判断/头脑风暴），不是加审核 |
| 某规则 10 次运行 0 触发 | 从裁判 rubric 删掉这条规则——没人犯的规则也在付装配税 |
| 某规则高频触发 | 改上游（模板 / 主 agent 写作指令），不是让裁判反复兜 |
| 裁判连续 5 次 issues 全空或全误报 | 裁判退场：删 6.2，机械项（R7）并回主 agent 自查 |
| `late_issues` 持续 > 裁判抓到数 | 裁判 rubric 失焦 → 重写 rubric |

---

## 目录结构

### spec 需求包模型

spec 采用 `docs/spec/<spec-name>/` 独立需求包目录：

- **docs/spec/**：所有 x-spec 需求包的固定根目录
- **spec-name**：一个系统切面/主题，每次 x-spec 运行聚焦一个 spec 需求包

多个 spec **组合**成完整系统方案（如 scheduler-cron-parsing + scheduler-task-dispatch + scheduler-retry-backoff 三个 spec 组成 scheduler 方案族），同一个 spec 迭代时**原地更新**（不另起目录）。

### 确定输出目录

1. 用户指定或 agent 推断出 `<spec-name>`，使用 URL 友好命名（空格转 `-`，斜杠转 `-`）
2. 检查 `docs/spec/` 是否存在：
   - **不存在** → 创建 `docs/spec/` + `docs/spec/README.md` + spec 需求包目录 + spec 7 文件
   - **已存在** → 检查 `docs/spec/<spec-name>/`：
     - spec 不存在 → 创建 spec 需求包目录 + 7 文件，**更新 `docs/spec/README.md` 索引**
     - spec 已存在 → **增量更新已有文件**（原地迭代），更新前告知用户将改动哪些文件

### 目录结构

```text
docs/spec/
├── README.md                              # spec 索引（汇总所有 spec 状态）
├── <spec-name>/
│   ├── README.md                          # spec 导航 + 目标
│   ├── 01-goals-and-boundaries.md         # 目标 + 完成标准 + 范围 + 用户要求与证据
│   ├── 02-module-breakdown.md             # 组件设计 + 接口 + 数据结构
│   ├── 03-core-workflows.md               # 核心流程：文字 + 时序图（跨模块协作唯一载体）
│   ├── 04-data-and-state.md               # 核心数据模型 + 状态流转
│   ├── 05-validation-and-evolution.md     # 验证策略 + 测试 + 演进
│   └── 90-task-map.md                     # 组件→task 映射
├── <other-spec>/
│   └── ...（同上 7 文件）
```

legacy 兼容：旧 spec 包里已有的 `diagrams.md` 原地迭代时保留、不强制迁移；新 spec 不再生成独立图集文件，图内嵌于其文字真源文件。

### spec 索引 README

spec 索引 README（`docs/spec/README.md`）只做导航和状态汇总，模板见 `templates/module-README.md`（保留旧文件名兼容）。每次新增/更新 spec 时同步更新。