x-spec 系统方案规划器

核心定位

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

x-spec 负责：

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

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

工作流程

1. 上下文充分性判断

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

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

每个目标都要写清：

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

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

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

必须完成：

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

可使用的判断原则：

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

提问规则：

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

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

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

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

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

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

斥候回报后，主 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/

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

按序判断：

是本模块能力 → 边界类加委托方法（转发时顺手补校验，维持不变量），内部函数保持私有
是通用工具（与本模块业务无绑定）→ 提取到共享底层模块（common/ / core/），双方都走它的边界
外部需要的内部能力多到边界形同虚设 → 模块边界画错了，回 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 + 用户确认结论为基准续写，不依赖窗口内的对话副本。

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

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

7 文件全部落盘后，主 agent 先跑 python3 tools/xdev.py validate <spec目录>——机械项（文件齐全 / 路径规则 / Requirement-Scenario 结构 / 02↔90 清单一致 / 状态取值）由工具零成本把关，validate 零 finding 后才派裁判，机械项不占裁判窗口；validate 的 finding 编号（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 逐条审核（规则全文贴入），每条 finding 必须带 文件+行号/锚点 证据
    - 显式允许负结果：某规则查无问题就写"未发现"，禁止硬凑 finding
    - 输出只准是按回报模板的判定清单，禁止复述或总结文档内容>
})

审核规则（finding 按编号回报，编号进 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 输出未附或有未修 finding 时记 P0。图内嵌于文字真源、无孤立图集仍由裁判目检 | P0 | | R8 | 数据结构字段中文注释、图表格式、task 排序依据强度 | P1 |

裁判回报模板：

## Judge Report

**Status:** done / blocked

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

x-spec

Como adicionar

Cole no README do seu repo

Skills relacionadas

frontend-design

mcp-builder

webapp-testing

web-artifacts-builder

Receba novas skills de Design e Frontend toda segunda