api-contract-testing

API 契约测试

适用场景

• 需要验证提供方与消费者之间的 API 契约，涵盖架构、语义、兼容性和演进时，使用此技能。
• 使用此技能审查现有计划、结果或证据集，并提出可执行的改进建议。
• 上下文不完整，但仍有必要进行有限范围的初步审查时，使用此技能。

输出格式选项

• 默认使用 Markdown 进行审查、执行和迭代优化。
• 用户要求表格、CSV、JSON 或工单字段时，保留风险、证据、优先级和边界信息。
• 对于机器处理的输出，先确认架构、枚举值和必填字段。

使用方法

1. 阅读并遵循 prompts/api-contract-testing.md，包括其中的输入契约、执行规则、最低覆盖要求和输出顺序。
2. 仅补充会影响决策的上下文：范围、环境、版本、约束、证据和成功标准。
3. 审核输入，然后区分已确认事实、工作假设和待解决问题。
4. 根据风险和证据强度排序，并产出可直接执行或审查的成果。
5. 如果信息缺失，提供有限范围的初步审查，并说明哪些结论缺乏依据。

参考文件

• 始终阅读 prompts/api-contract-testing.md；它是此技能的完整执行规范。
• 对于评估或回归，阅读 evals/eval.yaml 和 evals/cases/ 下的相关用例。
• 仅当这些目录存在且任务需要时，加载 references/、examples/、scripts/ 或 output-formats.md。

核心约束

• 契约包括语义和错误行为，而不仅是架构。
• 不要根据示例推断完整契约。
• 破坏性变更必须提供迁移路径。
• 切勿编造证据中未包含的系统行为、字段、数据、指标或根本原因。
• 将重要结论关联到证据；将缺乏支持的结论标记为假设，并说明验证方法。
• 根据业务影响、可能性或可检测性说明优先级。

交付检查清单

• 已覆盖：字段和类型、必填与可空规则、枚举值、状态码、错误正文、兼容性、版本演进、消费者影响。
• 已区分事实、假设、缺口和建议。
• 为高风险事项标注了优先级、证据依据、负责人或后续行动。
• 制定了可验证的决策标准，而非泛泛建议。
• 未执行未经授权的生产写入或破坏性操作。

常见陷阱

• 列出检查项，却未说明前置条件、预期结果或证据。
• 将所有事项都标为高优先级，回避权衡。
• 用工具名称或泛泛的理论代替领域推理。
• 因输入不完整而拒绝处理，或假装不完整的证据足以支撑确定结论。

最佳实践

• 优先检查最可能造成业务损失、安全问题或发布受阻的路径。
• 通过最小化且可验证的实验减少不确定性，并记录复现条件。
• 确保成果可执行，并可由另一位工程师独立审查。