tomevault-io DevBooks：规格与契约（Spec & Contract）
渐进披露
基础层（必读）
目标：明确本 Skill 的核心产出与使用范围。 输入：用户目标、现有文档、变更包上下文或项目路径。 输出：可执行产物、下一步指引或记录路径。 边界：不替代其他角色职责，不触碰 tests/。 证据：引用产出物路径或执行记录。
进阶层（可选）
适用：需要细化策略、边界或风险提示时补充。
扩展层（可选）
适用：需要与外部系统或可选工具协同时补充。
推荐 MCP 能力类型
- 代码检索（code-search）
- 引用追踪（reference-tracking）
- 影响分析（impact-analysis）
本 skill 合并了原
devbooks-spec-delta和devbooks-contract-data的功能，减少选择困难。
前置：配置发现（协议无关）
<truth-root>：当前真理目录根<change-root>：变更包目录根
执行前必须按以下顺序查找配置（找到后停止）：
.devbooks/config.yaml（如存在）→ 解析并使用其中的映射dev-playbooks/project.md（如存在）→ Dev-Playbooks 协议，使用默认映射project.md（如存在）→ template 协议，使用默认映射- 若仍无法确定 → 停止并询问用户
关键约束：
- 如果配置中指定了
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 |
| 有兼容性风险 | 额外输出兼容策略、弃用策略、迁移方案 |
| 依赖/配置/构建变更 | 运行隐式变更检测 |
执行方式
标准流程
- 先阅读并遵守：
~/.claude/skills/_shared/references/AI行为规范.md - 规格部分：按
references/规格变更提示词.md输出 Requirements/Scenarios - 契约部分：按
references/契约与数据定义提示词.md输出契约计划 - 隐式变更检测（按需）：
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
检测流程
- 检测
<change-root>/<change-id>/specs/是否存在 - 若存在，判断完整性（是否有占位符、REQ 是否有 Scenario）
- 根据检测结果选择运行模式
本 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.