菜单
API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用；要求先冻结消费者契约，再设计实现与验证。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/devcodex-labs/devcodex --skill api-contract-architecture命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | api-contract-architecture |
| description | API 契约架构专家 Owner — 当任务涉及 public API、HTTP/SDK/CLI 契约、版本兼容、错误模型、分页过滤、幂等、Schema、类型、迁移或消费者影响时使用；要求先冻结消费者契约，再设计实现与验证。 |
本 Skill 负责 API 契约 Owner 视角。它确保方案先回答“谁消费、契约是什么、如何兼容、如何验证”，再进入实现细节。
| 场景 | 是否触发 |
|---|---|
| 新增或调整 HTTP API、SDK API、CLI 参数、Hook payload、MCP tool/resource、事件、配置 Schema 或 public types | 必须 |
| 涉及版本兼容、迁移、错误码、分页、过滤、幂等、鉴权响应或消费者文档 | 必须 |
| 修复会影响调用方行为或示例用法 | 必须 |
| 纯内部实现且不改变任何公开输入/输出/错误/类型 | N/A + skipReason |
| Gate | 要求 | 证据 |
|---|---|---|
ApiContractArchitectureGate | 公开契约必须有消费者、输入、输出、错误、兼容和验证矩阵 | consumerSurface、contractInventory |
ConsumerSurfaceGate | 先列真实消费者，避免首个实现反向定义公共契约 | README、types、examples、route、SDK |
ErrorModelGate | 错误结构、错误码、detail 和恢复路径必须稳定 | errorModel、docs |
CliJsonContractGate | 机器可读 CLI 必须冻结 envelope 字段、成功/失败互斥、错误码、nextStep 与 native exit code | DevCodexCliEnvelopeV1、spawn fixtures |
VersionCompatibilityGate | 兼容、弃用、迁移和 breaking change 必须明确 | versionCompatibility |
ReleaseAuthorityBeforeCompatibilityGate | 先证明契约是否已发布并形成稳定消费者，再决定兼容、迁移或直接收敛 | publishedState、consumerEvidence、authoritySources、decision |
ConfigurationErgonomicsGate | 公开配置 Schema 必须证明最小任务、字段必要性、复杂度预算和可选字段省略行为 | MinimalTaskConfig、FieldNecessityMatrix、OptionalFieldOmissionProbe |
ContractVariantIsolationMutationGate | discriminated union/tool/event/state 合同必须拒绝 sibling variant 字段，并验证完成态必需证据不能被删除或反转 | ContractVariantIsolationMatrix、CompletionEvidenceDeletionMatrix |
IdempotencyPaginationGate | 写操作、分页、过滤、排序和重试场景必须定义语义 | idempotencyPagination |
ReleaseAuthorityBeforeCompatibilityGate：核对 tag/registry/release note/public docs/实际消费者；已发布才进入兼容评估，未发布且无稳定消费者默认直接收敛，未发布但存在产品取舍则交用户决策，事实不明时不得编造兼容义务。.http / .cjs、types、runtime probe。## ApiContractArchitectureGate
| 字段 | 内容 |
|------|------|
| consumerSurface | 消费者列表和调用入口 |
| contractInventory | 当前/目标输入、输出、错误、类型、配置 |
| versionCompatibility | 兼容、弃用、迁移、breaking change |
| releaseAuthority | publishedState、consumerEvidence、authoritySources 与兼容决策 |
| errorModel | 错误码、detail、恢复路径 |
| cliJsonContract | envelope、字段互斥、错误码、nextStep、exit map 与默认人读兼容 |
| idempotencyPagination | 幂等、分页、过滤、排序、重试语义 |
| sdkDocsImpact | SDK、README、examples、public types、文档影响 |
| evidenceMatrix | 判断 -> 代码 / 类型 / 文档 / 测试 / 运行时证据 |
| contractMutationMatrix | variant isolation、completion evidence deletion/reversal、schema/semantic/docs/runtime 结论 |
| 反模式 | 修正 |
|---|---|
| 先写实现，再让消费者适配输出 | 先冻结 contractInventory 和 consumerSurface |
| 只写 happy path，没有错误模型 | 补 errorModel 和失败恢复 |
| 首个 provider 字段反向定义公共 API | 区分业务契约与 provider payload |
| 用单个示例证明兼容 | 抽样 public types、README、tests 和 runtime |
| 未发布候选也默认背负历史兼容层 | 先做 ReleaseAuthorityBeforeCompatibilityGate；无稳定消费者时直接收敛 canonical contract |
| JSON 错误只写 message 或以 exit 0 返回 | 冻结稳定 errorCode/nextStep，并用原生退出码区分合同错误与检查失败 |
developer-experience-architecture：API 示例、错误信息和迁移路径共同影响 DX。backend-domain-architecture：领域不变量和权限策略必须映射到 API 契约。test-router：API 变更触发 .http / .cjs、types、runtime 或 docs sync 验证。