devbooks-spec-contract

name	devbooks-spec-contract
description	devbooks-spec-contract：定义对外行为规格与契约（Requirements/Scenarios/API/Schema/兼容策略/迁移），并建议或生成 contract tests。合并了原 spec-delta 和 contract-data 的功能。用户说"写规格/spec/契约/OpenAPI/Schema/兼容策略/contract tests"等时使用。 Use when this capability is needed.
metadata	{"author":"darkbluelr"}

DevBooks：规格与契约（Spec & Contract）

渐进披露

基础层（必读）

目标：明确本 Skill 的核心产出与使用范围。 输入：用户目标、现有文档、变更包上下文或项目路径。 输出：可执行产物、下一步指引或记录路径。 边界：不替代其他角色职责，不触碰 tests/。 证据：引用产出物路径或执行记录。

进阶层（可选）

适用：需要细化策略、边界或风险提示时补充。

扩展层（可选）

适用：需要与外部系统或可选工具协同时补充。

推荐 MCP 能力类型

• 代码检索（code-search）
• 引用追踪（reference-tracking）
• 影响分析（impact-analysis）

本 skill 合并了原 devbooks-spec-delta 和 devbooks-contract-data 的功能，减少选择困难。

前置：配置发现（协议无关）

• <truth-root>：当前真理目录根
• <change-root>：变更包目录根

执行前必须按以下顺序查找配置（找到后停止）：

1. .devbooks/config.yaml（如存在）→ 解析并使用其中的映射
2. dev-playbooks/project.md（如存在）→ Dev-Playbooks 协议，使用默认映射
3. project.md（如存在）→ template 协议，使用默认映射
4. 若仍无法确定 → 停止并询问用户

关键约束：

• 如果配置中指定了 agents_doc（规则文档），必须先阅读该文档再执行任何操作
• 禁止猜测目录根
• 禁止跳过规则文档阅读

---

产物落点

产物类型	落点路径
规格 delta	<change-root>/<change-id>/specs/<capability>/spec.md
契约计划	<change-root>/<change-id>/design.md（Contract 章节）或独立 contract-plan.md
Contract Test IDs	写入 verification.md 的追溯矩阵
隐式变更报告	<change-root>/<change-id>/evidence/implicit-changes.json

---

使用场景判断

场景	需要做什么
只有行为变化（无 API/Schema）	只输出 spec.md（Requirements/Scenarios）
有 API/Schema/事件变化	输出 spec.md + 契约计划 + Contract Test IDs
有兼容性风险	额外输出兼容策略、弃用策略、迁移方案
依赖/配置/构建变更	运行隐式变更检测

---

执行方式

标准流程

1. 先阅读并遵守：~/.claude/skills/_shared/references/AI行为规范.md
2. 规格部分：按 references/规格变更提示词.md 输出 Requirements/Scenarios
3. 契约部分：按 references/契约与数据定义提示词.md 输出契约计划
4. 隐式变更检测（按需）：references/隐式变更检测提示词.md

输出结构（一次性产出）

## 规格 Delta（Spec）

### Requirements
- REQ-XXX-001: <需求描述>

### Scenarios
- SC-001: <场景描述>
  - Given: ...
  - When: ...
  - Then: ...

---

## 契约计划（Contract）

### API 变更
- 新增/修改端点：`POST /api/v1/orders`
- OpenAPI diff 位置：`contracts/openapi/orders.yaml`

### 兼容策略
- 向后兼容：是/否
- 弃用策略：<如有>
- 迁移方案：<如有>

### Contract Test IDs
| Test ID | 类型 | 覆盖场景 |
|---------|------|----------|
| CT-001 | schema | REQ-XXX-001 |
| CT-002 | behavior | SC-001 |

---

脚本

• 隐式变更检测：scripts/implicit-change-detect.sh <change-id> [--base <commit>] [--project-root <dir>] [--change-root <dir>]

---

上下文感知

本 Skill 在执行前自动检测上下文，选择合适的运行模式。

检测规则参考：skills/_shared/上下文检测模板.md

检测流程

1. 检测 <change-root>/<change-id>/specs/ 是否存在
2. 若存在，判断完整性（是否有占位符、REQ 是否有 Scenario）
3. 根据检测结果选择运行模式

本 Skill 支持的模式

模式	触发条件	行为
从零创建	specs/ 目录不存在或为空	创建完整规格文档结构，包含 Requirements/Scenarios
补漏模式	specs/ 存在但不完整（有 [TODO]、REQ 缺 Scenario）	补充缺失的 Requirement/Scenario，保留已有内容
同步模式	specs/ 完整，需要与实现同步	检查实现与规格一致性，输出 diff 报告

检测输出示例

检测结果：
- 产物存在性：specs/ 存在
- 完整性：不完整（缺失项：REQ-002 无 Scenario）
- 当前阶段：apply
- 运行模式：补漏模式

---

隐式变更检测（扩展功能）

来源：《人月神话》第7章"巴比伦塔" — "小组慢慢地修改自己程序的功能，隐含地更改了约定"

隐式变更 = 没有显式声明但会改变系统行为的变更。

检测范围：

• 依赖变更（package.json / requirements.txt / go.mod 等）
• 配置变更（*.env / .config. / *.yaml 等）
• 构建变更（tsconfig.json / Dockerfile / CI 配置等）

与 change-check.sh 集成：

• 在 apply / archive / strict 模式下自动检查隐式变更报告
• 高风险隐式变更需在 design.md 中声明

---

下一步推荐

参考：skills/_shared/工作流下一步.md

完成 spec-contract 后，必须的下一步是：

条件	下一个 Skill	原因
始终	devbooks-implementation-plan	必须先创建 tasks.md 再进入实施阶段

关键：绝不在 spec-contract 后直接推荐 devbooks-test-owner 或 devbooks-coder。工作流顺序是：

spec-contract → implementation-plan → test-owner → coder

输出模板

完成 spec-contract 后，输出：

## 推荐的下一步

**下一步：`devbooks-implementation-plan`**

原因：规格和契约已定义。下一步是创建实现计划（tasks.md），将工作分解为可追踪的任务，并绑定验证锚点。

### 如何调用

运行 devbooks-implementation-plan skill 处理变更

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.