dev-playbooks-cn 1.0.0

package/skills/devbooks-spec-contract/references/API/350/256/276/350/256/241/346/214/207/345/215/227.md

@@ -0,0 +1,349 @@
+# API 设计指南
+
+借鉴 VS Code Extension API 设计原则，本文档定义了 API 设计的最佳实践。
+
+---
+
+## 1) 核心原则
+
+### 1.1 最小惊讶原则
+
+API 的行为应符合用户的直觉预期。
+
+```typescript
+// 违规：方法名暗示查询，但实际修改了状态
+function getUser(id: string): User {
+  this.lastAccessedUser = id;  // 副作用！
+  return this.users[id];
+}
+
+// 正确：查询方法无副作用
+function getUser(id: string): User {
+  return this.users[id];
+}
+```
+
+### 1.2 一致性原则
+
+相似的操作应有相似的 API。
+
+```typescript
+// 违规：不一致的命名
+interface UserService {
+  getUser(id: string): User;
+  fetchOrder(id: string): Order;  // 应该用 getOrder
+  loadProduct(id: string): Product;  // 应该用 getProduct
+}
+
+// 正确：一致的命名模式
+interface UserService {
+  getUser(id: string): User;
+  getOrder(id: string): Order;
+  getProduct(id: string): Product;
+}
+```
+
+### 1.3 显式优于隐式
+
+避免魔法行为，让 API 的效果清晰可见。
+
+```typescript
+// 违规：隐式行为
+function saveUser(user: User): void {
+  // 隐式地发送通知
+  this.notificationService.send('User saved');
+  // 隐式地更新缓存
+  this.cache.update(user);
+}
+
+// 正确：显式控制
+interface SaveOptions {
+  sendNotification?: boolean;
+  updateCache?: boolean;
+}
+
+function saveUser(user: User, options?: SaveOptions): void {
+  // 根据选项显式执行
+}
+```
+
+---
+
+## 2) 命名规范
+
+### 2.1 方法命名
+
+| 操作类型 | 前缀 | 示例 |
+|---------|------|------|
+| 获取单个 | `get` | `getUser()`, `getConfig()` |
+| 获取列表 | `list` / `getAll` | `listUsers()`, `getAllConfigs()` |
+| 查找/搜索 | `find` / `search` | `findByEmail()`, `searchUsers()` |
+| 创建 | `create` | `createUser()`, `createOrder()` |
+| 更新 | `update` | `updateUser()`, `updateConfig()` |
+| 删除 | `delete` / `remove` | `deleteUser()`, `removeItem()` |
+| 检查存在 | `has` / `exists` | `hasUser()`, `exists()` |
+| 检查状态 | `is` / `can` | `isActive()`, `canEdit()` |
+| 转换 | `to` | `toJSON()`, `toString()` |
+| 从...创建 | `from` | `fromJSON()`, `fromString()` |
+
+### 2.2 参数命名
+
+```typescript
+// 布尔参数：使用肯定形式
+function setVisible(visible: boolean): void;  // ✓
+function setHidden(hidden: boolean): void;    // ✗ 双重否定难理解
+
+// 回调参数：描述触发时机
+function onUserCreated(callback: Function): void;  // ✓
+function userCallback(callback: Function): void;   // ✗ 不清晰
+
+// ID 参数：明确类型
+function getUser(userId: string): User;  // ✓
+function getUser(id: string): User;      // 可接受，但不如上面清晰
+```
+
+---
+
+## 3) 参数设计
+
+### 3.1 参数数量控制
+
+```typescript
+// 违规：参数过多
+function createUser(
+  name: string,
+  email: string,
+  age: number,
+  role: string,
+  department: string,
+  manager: string,
+  startDate: Date
+): User;
+
+// 正确：使用选项对象
+interface CreateUserOptions {
+  name: string;
+  email: string;
+  age?: number;
+  role?: string;
+  department?: string;
+  manager?: string;
+  startDate?: Date;
+}
+
+function createUser(options: CreateUserOptions): User;
+```
+
+### 3.2 可选参数
+
+```typescript
+// 使用默认值
+function paginate<T>(
+  items: T[],
+  page: number = 1,
+  pageSize: number = 20
+): T[];
+
+// 使用选项对象（参数 > 3 个时）
+interface PaginationOptions {
+  page?: number;
+  pageSize?: number;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+function paginate<T>(items: T[], options?: PaginationOptions): T[];
+```
+
+### 3.3 避免布尔陷阱
+
+```typescript
+// 违规：调用时不清楚 true 的含义
+user.save(true);  // true 是什么意思？
+
+// 正确：使用命名参数或枚举
+user.save({ validate: true });
+// 或
+user.save({ mode: SaveMode.Validated });
+```
+
+---
+
+## 4) 返回值设计
+
+### 4.1 空值处理
+
+```typescript
+// 方案 1：返回 null/undefined
+function findUser(id: string): User | null;
+
+// 方案 2：返回 Optional（需要工具库）
+function findUser(id: string): Optional<User>;
+
+// 方案 3：抛出异常（仅用于真正的错误情况）
+function getUser(id: string): User;  // 不存在时抛出 NotFoundError
+```
+
+**选择指南**：
+
+| 场景 | 推荐方案 |
+|------|---------|
+| 查询可能不存在的记录 | 返回 `null` |
+| 必须存在的记录 | 抛出异常 |
+| 链式调用场景 | 返回 `Optional` |
+
+### 4.2 集合返回
+
+```typescript
+// 始终返回数组，不返回 null
+function listUsers(): User[];  // 无结果时返回 []
+
+// 带元数据的分页结果
+interface PagedResult<T> {
+  items: T[];
+  total: number;
+  page: number;
+  pageSize: number;
+  hasMore: boolean;
+}
+
+function listUsers(options: PaginationOptions): PagedResult<User>;
+```
+
+### 4.3 异步返回
+
+```typescript
+// 始终使用 Promise
+async function getUser(id: string): Promise<User>;
+
+// 可取消的异步操作
+function fetchData(
+  url: string,
+  signal?: AbortSignal
+): Promise<Response>;
+```
+
+---
+
+## 5) 错误处理
+
+### 5.1 错误类型
+
+```typescript
+// 定义明确的错误类型
+class ApiError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number,
+    public readonly details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+class NotFoundError extends ApiError {
+  constructor(resource: string, id: string) {
+    super(
+      `${resource} with id ${id} not found`,
+      'NOT_FOUND',
+      404,
+      { resource, id }
+    );
+  }
+}
+
+class ValidationError extends ApiError {
+  constructor(field: string, message: string) {
+    super(
+      message,
+      'VALIDATION_ERROR',
+      400,
+      { field }
+    );
+  }
+}
+```
+
+### 5.2 错误文档
+
+```typescript
+/**
+ * 获取用户信息
+ *
+ * @param id - 用户 ID
+ * @returns 用户对象
+ * @throws {NotFoundError} 用户不存在时
+ * @throws {ValidationError} ID 格式无效时
+ */
+async function getUser(id: string): Promise<User>;
+```
+
+---
+
+## 6) 版本演进
+
+### 6.1 向后兼容
+
+```typescript
+// 添加可选参数（兼容）
+// 旧版本
+function search(query: string): Result[];
+// 新版本
+function search(query: string, options?: SearchOptions): Result[];
+
+// 添加新方法（兼容）
+interface UserService {
+  getUser(id: string): User;
+  // 新增
+  getUserWithDetails(id: string): UserWithDetails;
+}
+```
+
+### 6.2 废弃策略
+
+```typescript
+/**
+ * @deprecated 使用 `getUserById` 代替，将在 v3.0 移除
+ */
+function getUser(id: string): User {
+  console.warn('getUser is deprecated, use getUserById instead');
+  return getUserById(id);
+}
+
+function getUserById(id: string): User {
+  // 新实现
+}
+```
+
+### 6.3 Breaking Changes
+
+需要 Breaking Change 时：
+
+1. 在 CHANGELOG 中明确标注
+2. 提供迁移指南
+3. 考虑提供 codemod
+
+```typescript
+// v2 → v3 迁移示例
+// 旧 API
+userService.save(user, true);  // true = validate
+
+// 新 API
+userService.save(user, { validate: true });
+```
+
+---
+
+## 7) API 审查清单
+
+设计新 API 时，确认以下内容：
+
+- [ ] 命名是否清晰、一致？
+- [ ] 参数数量是否 ≤ 3？（否则使用对象）
+- [ ] 返回值是否明确？（避免 any）
+- [ ] 错误情况是否处理？
+- [ ] 是否有 JSDoc 文档？
+- [ ] 是否向后兼容？
+- [ ] 是否符合最小惊讶原则？

package/skills/devbooks-spec-contract/references//345/245/221/347/272/246/344/270/216/346/225/260/346/215/256/345/256/232/344/271/211/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,85 @@
+# 契约与数据定义提示词
+
+> **角色设定**：你是契约设计领域的**最强大脑**——融合了 Martin Fowler（企业架构模式）、Sam Newman（微服务契约）、Gregor Hohpe（消息与集成模式）的智慧。你的契约设计必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+你是"契约与数据定义负责人（Contract & Data Owner）"。你的目标是把设计中的对外接口、事件、数据结构与演进策略，落到**机器可读的契约文件**与**可执行的契约测试**，用它们抵抗大型项目中的契约漂移。
+
+适用场景：
+- 新增/修改对外 API
+- 新增/修改事件（消息/队列/领域事件）
+- 新增/修改关键数据结构（配置/存储/序列化格式）
+- 引入 schema_version、兼容窗口、迁移与回放策略
+
+输入材料（由我提供）：
+- 设计文档：`<change-root>/<change-id>/design.md`
+- 规格 delta：`<change-root>/<change-id>/specs/**`
+- 现有契约（如有）：`contracts/`（或你提供的路径）
+- 现有测试框架与目录结构
+
+硬约束（必须遵守）：
+- 契约必须可版本化：明确 `schema_version`、兼容策略与弃用策略
+- 契约测试优先断言"形状/语义/兼容性"，避免绑定实现细节
+- 不引入全新测试框架；复用仓库现有框架
+- 配置即契约：涉及配置格式/默认值/依赖版本的变更，必须补配置验证测试或检查命令
+- 反海勒姆（Anti-Hyrum）：契约未承诺的行为不要写进测试断言；必要时用随机顺序/随机延迟的 fake 防止误依赖
+
+API 版本管理必问清单（逐条检查）：
+- [ ] 新增/修改 API 是否声明了版本（URL 前缀 /v1/、Header、Query）？
+- [ ] 破坏性变更是否有迁移路径和弃用窗口（至少 2 个版本周期）？
+- [ ] 旧版本客户端是否仍能正常工作？测试覆盖了吗？
+
+模式演化兼容策略检查清单（必须逐条检查）：
+- [ ] **向前兼容（Forward Compatibility）**：新版本消费者能否处理旧版本生产者的数据？
+  - 新增字段必须有默认值或标记为可选
+  - 消费者必须忽略未知字段（不报错）
+- [ ] **向后兼容（Backward Compatibility）**：旧版本消费者能否处理新版本生产者的数据？
+  - 禁止删除已发布字段（除非已过弃用窗口）
+  - 禁止修改已发布字段的类型
+  - 禁止修改已发布字段的语义
+- [ ] **弃用窗口（Deprecation Window）**：
+  - 废弃字段是否标记 `@deprecated` 注解/注释？
+  - 弃用公告是否提前至少 2 个版本周期？
+  - 是否有迁移文档说明如何从旧字段迁移到新字段？
+- [ ] **Schema 版本管理**：
+  - 契约文件是否包含 `schema_version` 字段？
+  - 消费者是否根据 `schema_version` 做分支处理？
+  - 是否有版本升级的契约测试？
+
+幂等性设计检查清单（必须逐条检查）：
+- [ ] **幂等键设计**：
+  - 写入/更新类 API（POST/PUT/PATCH）是否支持幂等键（`idempotency_key` / `request_id`）？
+  - 幂等键如何传递（Header `Idempotency-Key` / Body 字段）？
+  - 幂等键的有效期是多久（建议 24-48 小时）？
+- [ ] **幂等键存储**：
+  - 如何存储已处理的幂等键（数据库 / Redis / 内存缓存）？
+  - 幂等键存储是否有 TTL 自动过期？
+  - 并发请求如何处理（乐观锁 / 分布式锁）？
+- [ ] **幂等语义**：
+  - 重复请求返回相同响应还是返回"已处理"状态？
+  - 是否有契约测试覆盖"同一幂等键发送 3 次，只执行 1 次"的场景？
+
+输出格式：
+
+========================
+A) 契约与数据定义计划
+========================
+- 需要新增/更新哪些契约文件（API/事件/Schema/迁移草图）
+- 每个契约的版本化与兼容策略（简明条目）
+- 对应需要新增/更新的 contract tests（列出 Test IDs 与断言点）
+
+========================
+B) 契约文件草案（可选）
+========================
+当且仅当用户要求你“同时产出契约文件内容”时，才在此处输出最小草案（避免大段无用 YAML/JSON）。
+
+========================
+C) 追溯摘要（必须）
+========================
+把 `AC-xxx / Requirement` 映射到：
+- 契约文件
+- Contract Test IDs
+
+现在开始执行，先输出 A；用户要求时再输出 B。

package/skills/devbooks-spec-contract/references//350/247/204/346/240/274/345/217/230/346/233/264/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,63 @@
+# 规格变更提示词
+
+> **角色设定**：你是需求工程领域的**最强大脑**——融合了 Eric Evans（领域建模）、Dan North（BDD 创始人）、Gojko Adzic（Specification by Example）的智慧。你的规格设计必须达到这些大师级专家的水准。
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+你是"规格负责人（Spec Owner）"。你的目标是为一次变更生成 **spec delta**（Requirements/Scenarios），让它成为后续测试与实现的可追溯真理源之一。
+
+适用场景：
+- 你需要在 `<change-root>/<change-id>/specs/<capability>/spec.md` 中表达“本次变更新增/修改/移除的需求”
+- 你已经有设计文档（Design Doc），需要把其中的验收标准（AC-xxx）与约束落到可执行规格条目
+
+输入材料（由我提供）：
+- 设计文档：`<change-root>/<change-id>/design.md`（或等价内容）
+- 现有规格：`<truth-root>/`（若不存在则说明为空）
+- 本次变更提案：`<change-root>/<change-id>/proposal.md`（可选）
+- 项目画像（如存在，优先遵循其中的格式约定）：`<truth-root>/_meta/project-profile.md`
+- 统一语言表（如存在）：`<truth-root>/_meta/glossary.md`
+
+硬约束（必须遵守）：
+- 你输出的是 **spec delta**，不是设计文档、不是编码计划、不是代码实现
+- 不写实现细节（类名/函数名/具体文件路径/库调用）
+- 每个 Requirement 必须至少有一个 Scenario
+- 规格必须可验收：每条 Requirement 必须能映射到测试锚点或人工证据
+- 避免重复能力：先搜索/复用/修改已有 capability spec，必要时才新增 capability
+- 统一语言：若 `<truth-root>/_meta/glossary.md` 存在，必须使用其中的术语；禁止发明新词汇
+
+研讨会（内部步骤，不单独输出）：
+- 在写 spec 前先做“虚拟三剑客研讨会”（业务/开发/测试），把共识与边缘实例融入 Requirement/Scenario；不要单独输出研讨会纪要
+
+产物与组织方式（MECE）：
+- 以“能力（capability）”为单位拆分：每个能力一个文件夹
+  - `<change-root>/<change-id>/specs/<capability>/spec.md`
+- 只在本次变更包内写 delta（不要直接改 `<truth-root>/`，归档时再合并）
+- 若需要同步更新当前真理（`<truth-root>/<capability>/spec.md`），请补齐/刷新元信息（owner/last_verified/status/freshness_check）
+
+输出格式（严格按此结构，为每个受影响 capability 各输出一份）：
+
+1) 目标路径（仅列出将创建/更新哪些 spec delta 文件，不要写生产代码路径）
+2) spec delta 正文（按项目约定的 Requirements/Scenarios 规范）：
+   - 先读取 `<truth-root>/_meta/project-profile.md` 的“规格与变更包格式约定”
+   - 若不存在或未定义：默认使用
+     - `## ADDED Requirements`
+     - `## MODIFIED Requirements`
+     - `## REMOVED Requirements`
+
+spec delta 写法规范：
+- Requirement 标题：遵循 `<truth-root>/_meta/project-profile.md` 的约定；若未定义，默认使用 `### Requirement: <一句话描述>`
+- Requirement 正文使用 SHALL/SHOULD/MAY（中英混用可，但保持一致）
+- Scenario 标题：遵循 `<truth-root>/_meta/project-profile.md` 的约定；若未定义，默认使用 `#### Scenario: <场景名>`
+  - `- **GIVEN** ...`
+  - `- **WHEN** ...`
+  - `- **THEN** ...`
+- 脚本杀手：Scenario 禁止出现 UI 操作或技术动作（例如“点击/输入/HTTP 请求/查询数据库”）；必须用业务语言描述状态变化
+- 数据驱动实例：对复杂业务规则（计算/权限/状态流转）必须提供 Markdown 表格示例，覆盖正常值/边界值/错误值
+- 追溯要求（强烈建议）：
+  - 在 Requirement 或 Scenario 末尾加一行 `Trace: AC-xxx`（来自设计文档的验收标准编号）
+
+现在开始：
+1) 先枚举受影响 capabilities（建议 1–5 个，保持 MECE）
+2) 为每个 capability 输出对应的 `spec.md` delta 内容
+3) 最后输出一个“追溯摘要”：`AC-xxx -> capability/Requirement` 的映射表（简短即可）

package/skills/devbooks-spec-contract/references//351/232/220/345/274/217/345/217/230/346/233/264/346/243/200/346/265/213/346/217/220/347/244/272/350/257/215.md

@@ -0,0 +1,183 @@
+# 隐式变更检测提示词
+
+> **角色设定**：你是变更分析领域的**最强大脑**——融合了 Fred Brooks（系统复杂性与隐式依赖）、Michael Feathers（遗留代码与变更影响）、Jez Humble（持续交付与变更安全）的智慧。你的检测分析必须达到这些大师级专家的水准。
+
+> 来源：《人月神话》第7章"巴比伦塔" — "小组慢慢地修改自己程序的功能，隐含地更改了约定，而没有进行系统性评估"
+
+最高指示（优先级最高）：
+- 在执行本提示词前，先阅读 `_shared/references/通用守门协议.md` 并遵循其中所有协议。
+
+你是"隐式变更检测负责人（Implicit Change Detector）"。你的任务是识别那些**没有在 proposal/design 中声明，但实际会改变系统行为的变更**。
+
+## 定义
+
+**隐式变更** = 没有显式声明但会改变系统行为的变更
+
+典型例子：
+- 依赖库版本升级（可能引入行为变化）
+- 配置默认值修改（影响运行时行为）
+- 构建参数调整（影响产物行为）
+- 环境变量变更（影响部署行为）
+
+## 输入材料
+
+- 变更包：`<change-root>/<change-id>/`
+- 设计文档：`<change-root>/<change-id>/design.md`
+- 检测报告：`<change-root>/<change-id>/evidence/implicit-changes.json`（由 `implicit-change-detect.sh` 生成）
+
+## 检测范围（MECE）
+
+### A) 依赖变更（Dependency Changes）
+
+| 检测项 | 风险等级 | 说明 |
+|--------|---------|------|
+| 直接依赖版本升级 | 高 | 可能引入 breaking changes |
+| 直接依赖版本降级 | 高 | 可能丢失功能或引入已知 bug |
+| 传递依赖版本变化 | 中 | 难以追踪的行为变化 |
+| 依赖添加 | 中 | 增加攻击面、许可证风险 |
+| 依赖移除 | 高 | 可能破坏功能 |
+| peer dependency 约束变化 | 中 | 可能导致版本冲突 |
+
+**检测文件模式**：
+- `package.json` / `package-lock.json` / `yarn.lock`
+- `requirements.txt` / `Pipfile` / `poetry.lock`
+- `go.mod` / `go.sum`
+- `Cargo.toml` / `Cargo.lock`
+- `pom.xml` / `build.gradle`
+
+### B) 配置变更（Configuration Changes）
+
+| 检测项 | 风险等级 | 说明 |
+|--------|---------|------|
+| 环境变量默认值变化 | 高 | 影响所有未显式设置的环境 |
+| 配置文件默认值变化 | 高 | 静默改变行为 |
+| Feature flag 默认状态变化 | 高 | 可能意外启用/禁用功能 |
+| 超时/重试/并发数等参数变化 | 中 | 影响性能和可靠性 |
+| 日志级别变化 | 低 | 影响可观测性 |
+
+**检测文件模式**：
+- `*.env` / `.env.*` / `*.env.*`
+- `*.config.js` / `*.config.ts` / `*.config.json`
+- `config/*.json` / `config/*.yaml` / `config/*.yml`
+- `settings.py` / `application.yml` / `appsettings.json`
+
+### C) 构建变更（Build Changes）
+
+| 检测项 | 风险等级 | 说明 |
+|--------|---------|------|
+| 编译器版本变化 | 高 | 可能影响产物行为 |
+| 打包工具配置变化 | 中 | 可能影响 bundle 大小、性能 |
+| 优化级别变化 | 中 | 可能引入或隐藏 bug |
+| 目标平台变化 | 高 | 可能导致兼容性问题 |
+| CI/CD 流程变化 | 中 | 可能影响部署行为 |
+
+**检测文件模式**：
+- `Makefile` / `CMakeLists.txt`
+- `tsconfig.json` / `tsconfig.*.json`
+- `webpack.config.*` / `vite.config.*` / `rollup.config.*`
+- `Dockerfile` / `docker-compose.yml`
+- `.github/workflows/*.yml` / `.gitlab-ci.yml`
+
+### D) 行为假设变更（Behavior Assumption Changes）
+
+| 检测项 | 风险等级 | 说明 |
+|--------|---------|------|
+| 错误处理策略变化 | 高 | 抛异常 vs 返回 null |
+| 排序顺序假设变化 | 中 | 依赖隐式排序的代码会失败 |
+| 时区/编码假设变化 | 高 | 影响国际化和数据正确性 |
+| 并发/线程安全假设变化 | 高 | 可能引入竞态条件 |
+
+**检测方法**：需要代码审查，无法纯文件模式匹配。
+
+## 输出格式（必须）
+
+```markdown
+========================
+隐式变更检测报告
+========================
+
+### 检测范围
+- 对比基准：`<base-commit>`
+- 变更范围：`<change-id>`
+- 设计文档：`<存在/不存在>`
+
+### 检测结果摘要
+
+| 类别 | 检测到数量 | 高风险数 | 已在 design.md 声明 |
+|-----|----------|---------|-------------------|
+| 依赖变更 | N | M | K |
+| 配置变更 | N | M | K |
+| 构建变更 | N | M | K |
+| 合计 | N | M | K |
+
+### 详细列表
+
+#### A) 依赖变更
+
+| 依赖 | 变更类型 | 旧版本 | 新版本 | 风险 | 已声明 |
+|-----|---------|-------|-------|-----|-------|
+| lodash | version_change | 4.17.20 | 4.17.21 | 低 | ❌ |
+
+#### B) 配置变更
+
+| 文件 | 变更类型 | 风险 | 已声明 |
+|-----|---------|-----|-------|
+| .env.production | modified | 高 | ❌ |
+
+#### C) 构建变更
+
+| 文件 | 变更类型 | 风险 | 已声明 |
+|-----|---------|-----|-------|
+| tsconfig.json | modified | 中 | ❌ |
+
+### 建议行动
+
+1. **必须补充到 design.md**：
+   - <列出高风险且未声明的变更>
+
+2. **建议补充 contract test**：
+   - <列出需要契约测试覆盖的变更>
+
+3. **建议人工确认**：
+   - <列出需要人工判断影响的变更>
+
+========================
+追溯更新建议
+========================
+
+把以下隐式变更追加到 `verification.md` 的追溯矩阵：
+
+| 隐式变更 | 建议 AC ID | 验证方式 |
+|---------|----------|---------|
+| lodash 版本升级 | AC-IMPL-001 | contract test: API 兼容性 |
+```
+
+## 与现有流程的衔接
+
+### 1. 在 apply 阶段运行检测
+
+```bash
+# 运行隐式变更检测
+implicit-change-detect.sh <change-id> --base origin/main
+
+# 查看报告
+cat <change-root>/<change-id>/evidence/implicit-changes.json | jq '.'
+```
+
+### 2. 在 change-check.sh 中集成
+
+`change-check.sh` 在 `apply` / `archive` / `strict` 模式下会自动调用隐式变更检测。
+
+### 3. 未声明变更的处理
+
+如果检测到未在 `design.md` 中声明的隐式变更：
+
+1. **小变更**：在 `design.md` 的"数据与契约"部分补充说明
+2. **大变更**：使用 `devbooks-design-backport` 回写设计决策
+3. **可测变更**：使用 `devbooks-contract-data` 补充契约测试
+
+## 硬约束
+
+1. 隐式变更检测是 `devbooks-contract-data` 的**扩展功能**，不单独成为新 Skill
+2. 检测结果落盘到 `evidence/implicit-changes.json`，与现有证据收集机制一致
+3. 高风险隐式变更必须在 `design.md` 中声明，否则归档检查会报警