系统方案规划 skill。产出 docs/<模块>/<spec>/ 下的文档包（架构图 + 组件设计 + 接口/数据结构 + task 映射），多个 spec 组合成完整模块。 当用户给的是模糊想法而非具体功能需求时使用。触发场景： "这个东西怎么设计"、"帮我整理模块"、"画个架构图"、"帮我梳理整体方案"、"先别写代码把方案理清"、 "给人讲解这个系统需要什么文档"、"这个系统该怎么拆"、"x-spec"、新建多模块系统、架构级改造、 一个模块下会派生多个 task 需要先建模块文档。不适用：小功能小修复（用 x-qdev）、已有明确需求（用 x-req）。
Scanned 5/27/2026
Install via CLI
Skills Directoryopenskills install KtKID/x-dev-pipeline---
name: x-spec
description: |
系统方案规划 skill。产出 docs/<模块>/<spec>/ 下的文档包（架构图 + 组件设计 + 接口/数据结构 + task 映射），多个 spec 组合成完整模块。
当用户给的是模糊想法而非具体功能需求时使用。触发场景：
"这个东西怎么设计"、"帮我整理模块"、"画个架构图"、"帮我梳理整体方案"、"先别写代码把方案理清"、
"给人讲解这个系统需要什么文档"、"这个系统该怎么拆"、"x-spec"、新建多模块系统、架构级改造、
一个模块下会派生多个 task 需要先建模块文档。不适用：小功能小修复（用 x-qdev）、已有明确需求（用 x-req）。
---
# x-spec 系统方案规划器
## 核心定位
x-spec 是方案型 skill，负责把一个模糊的系统想法整理成可导航、可拆分、可演进的方案文档体系。
x-spec 负责：
1. 理解系统目标、价值、约束和边界
2. 判断该需求是否应该拆系统、拆模块、拆 task
3. 产出系统级方案目录和总导航 README
4. 拆分系统模块，定义模块职责、边界、依赖、状态
5. 标记哪些模块已足够稳定，可以进入 x-req
6. 建立模块文档与 task 的映射关系
x-spec 不负责：
- 生成开发清单
- 进入代码实现
- 直接修改业务代码
- 替代 x-req / x-dev
**核心边界：**
x-spec 回答“这个系统整体应该怎么组织”，不回答“现在具体开发哪一项代码”。
---
## 适用场景
以下情况优先使用 x-spec：
- 用户给的是模糊想法，而不是明确功能需求
- 涉及多个模块、多个阶段、多个 task
- 方案讨论比代码实现更重要
- 当前不确定该不该拆分
- 一个文档可能会非常长，需要拆成导航 + 子文档
- 需要先形成系统级共识，再进入开发
以下情况不需要 x-spec：
- 小功能、小修复、单文件改动
- 已经有稳定需求报告（README.md），只差 dev-checklist/dev
- 用户明确要求立即开发一个清晰范围的功能
---
## 目录结构
### 模块/spec 两层模型
spec 采用 `docs/<模块>/<spec>/` 两层目录：
- **模块**：顶层目录，对应系统中一个独立领域（如 `scheduler`、`auth`）
- **spec**：模块下的一个切面/主题，每次 x-spec 运行聚焦一个 spec 产出
多个 spec **组合**成完整的模块描述（如 scheduler 由 cron-parsing + task-dispatch + retry-backoff 三个 spec 组成），同一个 spec 迭代时**原地更新**（不另起目录）。
### 确定输出目录
1. 用户指定或 agent 推断出 `<模块>` 和 `<spec>` 名称
2. 检查 `docs/<模块>/` 是否存在：
- **不存在** → 创建模块目录 + 模块 README + spec 目录 + spec 7 文件
- **已存在** → 检查 `docs/<模块>/<spec>/`：
- spec 不存在 → 创建 spec 目录 + 7 文件，**更新模块 README 导航**
- spec 已存在 → **增量更新已有文件**（原地迭代），更新前告知用户将改动哪些文件
### 目录结构
```text
docs/<模块>/
├── README.md # 模块导航（汇总所有 spec 状态）
├── <specA>/
│ ├── README.md # spec 导航 + 目标
│ ├── 01-goals-and-boundaries.md # 目标 + 完成标准 + 范围
│ ├── 02-module-breakdown.md # 组件设计 + 接口 + 数据结构
│ ├── 04-data-and-state.md # 核心数据模型 + 状态流转
│ ├── 05-validation-and-evolution.md # 验证策略 + 测试 + 演进
│ ├── 90-task-map.md # 组件→task 映射
│ └── architecture.html # 组件依赖图（浏览器双击打开）
├── <specB>/
│ └── ...（同上 7 文件）
```
按需扩展（可选，在 spec 目录下）：
```text
│ ├── 03-core-workflows.md # 核心流程/时序（有明显链路时才加）
```
### 模块 README
模块 README（`docs/<模块>/README.md`）只做导航和状态汇总，模板见 `templates/module-README.md`。每次新增/更新 spec 时同步更新。
---
## 文档生成规则
### 图类型规范
所有图统一用 **mermaid 格式**，嵌入方式分两种：
- **独立 HTML**（浏览器双击看）：`architecture.html`，模板见 `skills/x-req/templates/diagram-template.html`
- **内嵌 markdown**（GitHub/VS Code 渲染）：在 .md 文件里用 ` ```mermaid ` 代码块
| 图类型 | mermaid 类型 | 嵌入位置 | 用途 |
|--------|------------|---------|------|
| **模块依赖图** | `flowchart TD` | `architecture.html`（独立 HTML） | 模块间依赖关系，整体架构 |
| **核心流程图** | `flowchart LR` 或 `flowchart TD` | `03-core-workflows.md` 内嵌 | 业务主链路、数据处理管线 |
| **时序图** | `sequenceDiagram` | `03-core-workflows.md` 内嵌 | 模块间调用顺序、请求响应链 |
| **状态流转图** | `stateDiagram-v2` | `04-data-and-state.md` 内嵌 | 核心对象生命周期 |
| **ER 图** | `erDiagram` | `04-data-and-state.md` 内嵌 | 实体关系、数据库表结构 |
### 苹果风配色（所有图统一）
```
classDef p0 fill:#E8F1FE,stroke:#0071E3,color:#1D1D1F,stroke-width:1.5px
classDef p1 fill:#FFF4E5,stroke:#FF9500,color:#1D1D1F,stroke-width:1.5px
classDef p2 fill:#F2F2F7,stroke:#8E8E93,color:#1D1D1F,stroke-width:1.5px
```
- P0（蓝）= 核心 / 阻塞性
- P1（橙）= 主要 / 必须完成
- P2（灰）= 辅助 / 可选
### 图的写法守则
1. 节点格式：`ID["名称<br/>P0/P1/P2 · 一句话"]:::p{0|1|2}`
2. 实线 `-->`（强依赖）；虚线 `-.->`（弱依赖 / 可选 / 调起）
3. 超 10 个节点用 `subgraph` 分组（按部署单元 / 技术栈 / 层次）
4. 同质重复节点压成 "×N"（如 17 个 adapter 压成一个）
5. 图与文字描述保持一致——增减内容时同步更新
### architecture.html 产出步骤
1. 复制 `skills/x-req/templates/diagram-template.html` 到 `docs/<模块>/<spec>/architecture.html`
2. 替换 title + h1 中的 TASK_NAME 为 spec 名
3. 替换 mermaid 块为 02-module-breakdown.md 中所有组件的依赖图
4. architecture.html 与 02-module-breakdown.md 保持一致——增减组件时同步更新
### 原则
- **docs/ 是独立可传递的文档包**：拿走 `docs/<模块>/` 给任何人，不依赖 `dev-pipeline/tasks/`
- 每个 spec 目录 7 个文件全部必须生成——即使内容少也要有占位
- 模块 README 只做导航和 spec 状态汇总，不堆内容
- spec README 只做导航和目标概述，细节在子文档
- 子文档按编号排序，方便顺序阅读
---
## 工作流程
### 1. 苏格拉底式需求挖掘
**不是问卷调查**——多轮对话，每轮 3-5 个问题一次列出让用户批量答，根据回答决定下一轮问什么。越模糊追越深。
#### 阶段 1：目标（为什么做）
- "这个系统解决什么问题？"
- "谁会用？什么场景下用？"
- "不做会怎样？现在是怎么绕过的？"
- "做完后你怎么判断它成功了？"（→ 直接导出 DoD）
#### 阶段 2：范围 + MVP 路径（做多少）
- "第一版必须有什么？什么能砍？"
- "什么是绝对不做的？"（→ 导出"不包含"）
- "已经有什么可以复用的？（代码/服务/数据）"
- "跟什么已有系统交互？谁是上游谁是下游？"
- "**最简单的一条完整路径是什么？从用户操作到最终结果**"（→ 导出 MVP 链路）
- "**砍掉所有锦上添花的东西，核心链路是什么？**"
- "**哪个模块做完其他模块才能动？**"（→ 导出开发顺序）
- "**有没有可以并行做的部分？**"
#### 阶段 3：约束（受什么限制）
- "技术栈有偏好或硬限制吗？"
- "时间和人力：一个人做 / 团队？几周 / 几月？"
- "数据从哪来？量级多大？有隐私要求吗？"
- "用错了会怎样？容错要求多高？"
#### 阶段 4：收敛确认
综合所有回答产出一份"理解总结"（目标 / MVP 路径 / 范围 / 模块草稿 / 约束 / DoD），用户确认后进入下一步。
#### 追问策略
| 规则 | 说明 |
|------|------|
| 每轮 3-5 个问题 | 一次列出让用户批量答，不要一来一回 |
| 追问深度自适应 | 回答具体 → 不继续追；回答模糊 → 下一轮展开 |
| 最多 3 轮追问 | 超过 3 轮用户会烦。3 轮还不清楚 → 先按已有信息产出，标注"待确认"项 |
| 每个回答立刻归类 | 归到"目标/范围/约束/模块"桶，不要最后才整理 |
| 探索→收敛交替 | 第 1-2 轮开放（"你怎么想？"），第 3 轮收敛（"A 还是 B？"） |
#### 不追问的情况
- 用户给了详细 PRD / 需求文档 → 跳过追问，直接进文档生成
- 用户说"不要问了直接做" → 尊重，按已有信息产出
- 用户输入已经足够具体 → 跳过
#### 追问与文档联动
| 追问阶段 | 回答灌进哪个文件 |
|---------|---------------|
| 阶段 1 目标 | `01-goals-and-boundaries.md` → 系统目标 + DoD |
| 阶段 2 范围 | `01-goals-and-boundaries.md` → 包含/不包含 |
| 阶段 2 MVP 路径 | `README.md` → "最小可用路径" 段 |
| 阶段 2 复用/集成 | `02-module-breakdown.md` → 模块依赖 + 复用标注 |
| 阶段 2 开发顺序 | `90-task-map.md` → 排序依据 |
| 阶段 3 约束 | `01-goals-and-boundaries.md` → 关键约束 |
| 阶段 3 数据 | `04-data-and-state.md` → 核心实体 + 持久化 |
| 阶段 4 收敛总结 | `README.md` → 系统目标 + 模块导航 |
### 2. 现有资源调研（手里有什么牌）
追问完成后、拆模块前，**LLM 主动调研**（不只是问用户）：
- 扫项目代码结构，找已有的可复用模块/函数
- 找已有的相似功能（避免重复造轮子）
- 找已用的第三方依赖（影响技术选型）
- 找已有的数据格式/存储（影响数据结构设计）
- 汇总"可复用清单"给用户确认
如果是全新项目（无已有代码）→ 跳过本步，直接进拆模块。
### 3. 判断是否需要拆系统
满足任意两项，则建议拆模块：
- 涉及多个代码包或层
- 可独立测试的子能力超过 3 个
- 预期会拆成多个 task
- 单文档预计过长
- 模块之间依赖关系明显
- 用户自己也不确定边界
如果不满足，则建议直接进入：
- `x-qdev`：小改动
- `x-req`：单功能但需要澄清与拆解
### 4. 拆分系统模块
每个模块至少定义：
- 模块名称
- 职责
- 包含范围
- 不包含范围
- 依赖
- 数据结构/接口（对外暴露的核心类型）
- 复用/新建标注（步骤 2 的调研结论）
- 风险等级（高/中/低）
- 当前状态
模块状态只使用：
- 探索中
- 方案确认
- 可进入 x-req
- 开发中
- 已完成
### 5. DoD ↔ 模块追溯矩阵
拆完模块后必须建立双向追溯：
```markdown
| DoD 条目 | 需要哪些模块 | 需要哪些 task |
|---------|------------|-------------|
| 条目 1 | 模块 A + 模块 B | task-1 |
| 条目 2 | 模块 C | task-2 |
```
**两个方向都要对得上**：
- DoD 条目没有模块支撑 = 漏了实现 → 补模块或调 DoD
- 模块没有 DoD 条目对应 = scope creep → 砍掉或补 DoD
写入 `01-goals-and-boundaries.md` 的"追溯矩阵"段。
### 6. 风险标注 + PoC 建议
拆完模块后显式检查：
- 哪些模块有技术风险？（不确定能不能做 / 性能扛不扛得住 / 依赖不稳定）
- 需不需要先跑个小实验验证？
- 高风险模块 → task-map 里排到前面先做（先验证最大风险，不要最后才发现做不了）
风险等级写入 `02-module-breakdown.md` 每个模块详情；PoC 建议写入 `90-task-map.md` 备注列。
### 7. 生成文档
产出文件：
- **模块 README**（`docs/<模块>/README.md`）：模板见 `templates/module-README.md`。如果模块目录已存在，更新导航表即可
- **spec 7 文件**（`docs/<模块>/<spec>/` 下）：模板见 `templates/` 下对应文件，将前 6 步的所有结论灌入
spec README 必须包含：
- spec 目标
- **最小可用路径**（MVP 链路，一句话描述核心路径）
- 组件导航 + 状态表
- 文档导航
- 当前建议
模块 README 必须包含：
- 模块职责（一句话）
- spec 导航表（名称 + 状态 + 说明）
### 8. 给出下一步建议
必须给出明确结论：
- 哪些模块继续留在方案层
- 哪些模块可以进入 x-req
- 高风险模块是否建议先 PoC
- 是否建议现在就拆 task
---
## 模板文件
所有模板在 `skills/x-spec/templates/` 下，LLM 产出时复制对应模板并填充内容：
| 模板文件 | 对应产出 | 层级 |
|---------|---------|------|
| `templates/module-README.md` | 模块导航 | `docs/<模块>/README.md` |
| `templates/README.md` | spec 导航 | `docs/<模块>/<spec>/README.md` |
| `templates/01-goals-and-boundaries.md` | 目标 + 完成标准 + 范围 | spec 目录 |
| `templates/02-module-breakdown.md` | 组件设计 + 接口 + 数据结构 | spec 目录 |
| `templates/04-data-and-state.md` | 核心数据模型 + 状态流转 | spec 目录 |
| `templates/05-validation-and-evolution.md` | 验证策略 + 测试 + 演进 | spec 目录 |
| `templates/90-task-map.md` | 组件→task 映射 | spec 目录 |
`architecture.html` 使用 `skills/x-req/templates/diagram-template.html`（苹果风 mermaid 共用模板）。
---
## 输出要求
完成后，必须向用户明确说明：
1. 该模块是否还需要拆更多 spec
2. 当前 spec 的状态（探索中 / 方案确认 / 可进入 x-req）
3. 哪些 spec 适合先进入 x-req
4. 哪些 spec 仍应停留在方案层
5. 文档保存路径：`docs/<模块>/<spec>/`
如果用户仍然很模糊，优先先产出最小 3 文件，不要过早扩展全部文档。
No comments yet. Be the first to comment!
