ProjectAGiPrompt/1-AgentSkills/designing-contracts/SKILL.md

name, description, allowed-tools, argument-hint

name	description	allowed-tools	argument-hint
designing-contracts	Guides API contract design, event schema definition, and version compatibility management for RMDC system. Triggered when defining new APIs, modifying request/response structures, designing MQTT message schemas, or planning breaking changes. Keywords: API versioning, backward compatibility, schema evolution, OpenAPI, event contract, MQTT payload, breaking change.	Read Glob Grep Bash	$ARGUMENTS: <contract-type> [module] — contract-type: api|event|schema|breaking-change

designing-contracts

概述

本 Skill 指导 RMDC 系统的契约设计，包括 API 接口、事件消息、数据 Schema 的定义与版本管理。

动态上下文注入

查找现有 API 定义

!grep -rn "router\.\(GET\|POST\|PUT\|DELETE\)" --include="*.go" | head -30

查找 MQTT topic 定义

!grep -rn "topic\|Topic\|MQTT" --include="*.go" | head -20

---

Plan（规划阶段）

契约变更类型判定

类型	影响范围	兼容性要求
新增字段（可选）	低	向后兼容
新增必填字段	高	Breaking Change
修改字段类型	高	Breaking Change
删除字段	高	Breaking Change
修改字段语义	高	Breaking Change

决策点

• 是否为 Breaking Change？
• 是否需要版本化（v1 -> v2）？
• 影响哪些下游模块/客户端？
• 是否需要过渡期（同时支持新旧版本）？

---

Verify（验证清单）

API 契约检查

• 新增字段有默认值
• 必填字段未被删除
• 字段类型未变更
• 错误码向后兼容
• 响应结构保持一致

事件契约检查

• Topic 命名遵循规范
• Payload 字段向后兼容
• 消息版本字段存在
• 消费者兼容新字段

验证命令

# 对比 API 变更
git diff HEAD~1 --name-only | grep -E "handler|router"

# 检查 breaking change
./scripts/verify-api-compatibility.sh

---

Execute（执行步骤）

新增 API

1. 定义请求/响应结构体
2. 添加字段校验规则
3. 注册路由
4. 更新 API 文档
5. 通知下游模块

Breaking Change 处理

1. 创建新版本路由（/v2/...）
2. 保留旧版本兼容期
3. 添加废弃警告
4. 通知所有消费者
5. 设定旧版本下线时间

---

Pitfalls（常见坑）

1. 删除字段未通知下游：前端/其他模块仍在使用该字段，导致解析失败。
2. 修改字段类型：如 string 改 int，JSON 解析会失败。
3. 错误码语义变更：下游按错误码做分支处理，语义变更会导致逻辑错误。
4. MQTT payload 无版本字段：无法做向后兼容处理。
5. 必填字段无默认值：旧客户端无法正常调用。

---

相关文件

用途	路径
版本策略	reference/api-versioning-policy.md
事件规则	reference/event-schema-rules.md
Breaking Change 清单	reference/breaking-change-checklist.md