x-spec

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。

第一性原理产物链路

事实 / 约束 / 不变量 / 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 判定清单