X Spec3

---
name: x-spec3
description: |
  在开发方案已经讨论清楚、需要固化保存时使用。也适用于用户明确要求保存方案、编写规格文档，或希望在开发前明确目标、边界、约束和验收标准的场景。将已确认的方案整理成可供后续任务拆解、开发和验证共同使用的规格文档。
---

# x-spec3

x-spec3 产出最小完整开发契约。每段内容都服务于实现决策、测试设计或事实验证；同一事实只保留一个权威落点。

## 产物

在 `docs/spec/<spec-name>/` 中只生成 `spec.md`。完整读取 `templates/spec.md` 后填充，并删除注释、占位符、空表示例。

`spec.md` 固定包含：

1. 任务目标与可观察成功结果。
2. 非目标，限定本次实现范围。
3. 影响边界：目标模块、上游、下游、相关模块、主要风险及其不变量。
4. 判断依据：只记录会改变实现或验收的事实、规范、推断和待确认项。
5. 建模覆盖声明：数据流、状态、时序、资源、不变量、故障六项逐一声明，无则写'无'，禁止捏造事实。
6. 验收清单：单元测试、Smoke 测试、按需 E2E 测试及其判定依据。
7. 测试驱动开发顺序。
8. 可执行的 GIVEN/WHEN/THEN Scenarios。

## 工作流

### 1. 建立证据边界

读取任务描述与相关代码、测试、接口、配置和既有文档。先确定：

- 需要改变的可观察系统结果。
- 本次明确排除的工作。
- 直接修改模块、调用它的上游、消费其结果的下游。
- 每个受影响模块最可能发生的事故；新模块重点参考同类模块的常见事故。
- 这些模块在修改前后都应成立的不变量。
- 边界、竞态、故障和资源生命周期中的隐蔽失败路径。

证据缺口会实质改变方案时，把它写成待确认判断；其余可逆细节采用最小合理默认并注明推断。

### 2. 压缩为单一契约

使用 `templates/spec.md`。采用明确目标状态描述行为；关键边界同时给出紧凑可判定断言。判断理由集中放在 J-ID 表中，由边界、验收或 Scenario 引用。

写入前做一次契约一致性检查，只在生成过程使用，不增加 spec.md 章节：

1. 从用户任务提取带有“必须、不得、只、每个、全部、错误、顺序、阈值、所有权”等约束的句子，视为硬约束。
2. 逐条检查目标、非目标、J-ID、边界不变量和 Scenario。LLM 推断只能补足任务未定义的空白，不能放宽、收窄或覆盖硬约束；类型字段可选、零值可用等接口形状本身不产生额外业务语义。
3. 对全称、否定和错误规则构造一个最小反例，优先代入空集合、缺失节点、嵌套边界、覆盖/删除/恢复、共享引用、并发和乱序。若该输入满足当前 spec 却违反用户原句，立即修正判断并补上可判定 Scenario。
4. `待确认` 只用于来源确实没有定义且不同答案会改变实现或验收的事项。任何待确认项存在时，spec 保持草案状态并停止交接 x-req3。

影响边界表覆盖：

- 目标模块的职责变化与公开契约。
- 上游提供的输入、调用顺序、重试或并发方式。
- 下游依赖的输出、错误、持久化或副作用。
- 每个模块由本次变化引入或放大的主要风险。
- 相关模块中必须保持的不变量。

风险写成具体的“触发条件 → 事故 → 影响”，只保留最可能或损失最高的项。新模块至少预判一个同类模块常见事故，已有模块关注回归和不变量破坏。风险必须由不变量、验收项或 Scenario 承接。

四个参考例子：

1. 定时或轮询模块默认每 1 秒扫描一次，在任务量增长或多实例部署时可能造成数据库/接口压力、任务重叠和重复执行；需要明确频率、并发与幂等约束。
2. Agent 审批模块按前缀或关键词匹配命令，允许 `bash ls` 时可能把所有 `bash` 命令一并放行；需要按命令与参数精确限定授权范围。
3. 重试或消息处理模块在超时后重复执行，缺少幂等键时可能造成重复写入、重复发送或重复扣费；需要验证去重和副作用边界。
4. 多线程或多 goroutine 同时读写共享状态，在“检查后执行”窗口或缺少同步保护时可能造成重复处理、丢失更新和状态覆盖；需要明确数据所有权、原子性或锁策略，并用并发测试和 race detector 验证。

建模覆盖声明逐项给出当前文档锚点。某项确实不适用时写出与本任务相关的具体理由。

### 3. 先写验收，再写场景

验收清单固定包含单元测试和 Smoke 测试。E2E 按跨进程、跨服务、真实基础设施或用户链路风险决定，并明确写“需要”或“省略”及依据。

测试驱动顺序按风险展开：

1. 将每个 Scenario 映射为会先失败的测试。
2. 先覆盖核心语义，再覆盖边界、错误、并发和资源路径。
3. 实现满足测试的最小代码。
4. 重构后复跑单元、Smoke 和已选择的 E2E。

### 4. 直接列出 Scenarios

每个 Scenario 标题使用 `### Scenario SC_01: <可判定行为名称>`。ID 固定为 `SC_` 加两位十进制数，从 `SC_01` 开始按文档顺序连续递增。同一 spec 内 ID 禁止重复，新 Scenario 使用当前最大 ID 加一，已有 ID 禁止复用或重编号。语义名称可修改，checklist 和 verify 只按 ID 对账。

每个 Scenario 只表达一个可判定行为，包含：

- **GIVEN**：输入、初始状态与关键边界。
- **WHEN**：唯一触发动作。
- **THEN**：可观察结果、错误、状态或副作用。
- 测试层：`unit`、`smoke` 或 `e2e`。
- 依据：相关 J-ID；直接任务契约可写“用户任务”。

场景集合优先覆盖高损失边界：递归/嵌套输入、空值与删除、并发交错、重复/乱序、超时/失败、所有权与不可变性、确定性、容量和性能阈值。每项只在与任务相关时出现。

### 5. 自审并交接

完成规格后做语义自审：

- 每条用户硬约束都能定位到目标、不变量或 Scenario，且没有 J-ID、非目标或 Scenario 与其冲突。
- 每条全称、否定和错误规则都经过最小反例检查；发现的新行为边界已经进入 Scenario。
- 每个目标都有 Scenario 和验收项。
- 每个受影响模块都有具体主要风险；新模块包含同类常见事故预判。
- 每个边界不变量都有可观察验证。
- Scenario ID 均为 `SC_01` 格式，按顺序递增且没有重复；新增或修改场景保持已有 ID 稳定。
- 每个 Scenario 能直接转成测试，THEN 避免“正确处理”等不可判定措辞。
- 单元、Smoke、E2E 的职责清晰，E2E 决策有依据。
- 判断依据有消费者，建模覆盖没有空洞锚点。
- 重复说明已经合并，背景材料没有进入执行上下文。

交接时报告 spec 路径、契约一致性检查结果、待确认判断、测试层选择和最高风险 Scenario。存在待确认项时明确报告“spec 草案，阻断 x-req3”；全部判断确认后，x-req3 依据该单文档拆解开发任务，verify 依据 Scenario 测试层复跑事实证据。