状态稳定
类型原子 Skill
领域软件测试
生命周期测试设计
适合角色QA / DEV
语言中文 / 英文
评测有评测 ✓
同步日期2026-09-15
解决什么问题
它把当前 Skill 的方法整理成可以直接执行、评审和复用的质量输入。
- 不执行 API、调用外部服务或声称安全、兼容、性能测试已通过。
- 不从一个样例补造所有字段、错误、权限、限流、幂等或版本规则。
- 每条 API-## 至少包含 operation、来源/证据、影响、兼容风险、责任角色、待决策问题和验证方式。
- 把一个成功响应样例当成完整 OpenAPI 契约。
适用场景
推荐使用
- 需要检查 operation、输入输出、错误、权限和兼容演进是否可验证。
- 需要在多个消费者、版本或迁移方案之间发现契约缺口。
- 需要识别样例不完整、未定义边界和缺少运行证据的 API 风险。
常见误区
- 把一个成功响应样例当成完整 OpenAPI 契约。
- 只看状态码，不看错误体、权限、重试、幂等和消费者行为。
- 把文档版本号或工具 lint 通过当成兼容性测试通过。
输入
最低输入
- 阅读 `prompts/api-design-quality-review.md`，审计 API 目标、版本、消费者、范围和证据。
推荐输入
- 项目目标
- 测试范围
- 约束条件
可选上下文
- 相关代码或配置
- 历史结果
- 日志与指标
输出
输出会围绕该 Skill 的方法形成可执行结果，并明确事实、假设、风险和下一步。
不安装也能判断输出价值
- 01已审计 operation、版本、消费者、范围和证据
- 02已检查输入输出、错误、鉴权、幂等、分页、状态码、演进和迁移影响
- 03每个 API-## 有最小证据、影响、责任角色和验证方式
- 04已区分样例、设计声明与真实执行证据
查看完整输出结构
- 05没有替团队作兼容策略、风险接受或发布批准
工作原理
- 01阅读 prompts/api-design-quality-review.md，审计 API 目标、版本、消费者、范围和证据。
- 02将材料归入 known、missing、conflicting、stale、out_of_scope、assumptions。
- 03按 operation 和稳定字段建立设计覆盖矩阵，使用 API-## 绑定来源、证据、影响和验证方法。
- 04分离契约事实、证据推断、建议和 Human 决策；明确兼容性、鉴权和错误处理仍需什么证据。
- 05信息不完整时给出受限初版，不能把请求响应样例当成完整契约。
安装与快速开始
安装命令 / SHELL
npx skills add \
https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/api-design-quality-review
-gapi-design-quality-review.prompt
@skill api-design-quality-review
结合当前项目上下文，按该 Skill 的要求给出可执行结果。
补充上下文：
[粘贴项目背景或需求]---
name: api-design-quality-review
description: Use this skill when an API, OpenAPI, or consumer contract needs a quality review before implementation or versioning; triggers include API 设计质量评审, API design review, and contract readiness review.
---
# API 设计质量评审
在实现前评审 API 设计、OpenAPI/契约、请求响应样例、错误模型、鉴权授权、幂等、分页、状态码、版本演进和消费者影响。输出 `API-##` 发现与验证准备，不执行 API，也不批准最终版本策略。
## 何时使用
- 需要检查 operation、输入输出、错误、权限和兼容演进是否可验证。
- 需要在多个消费者、版本或迁移方案之间发现契约缺口。
- 需要识别样例不完整、未定义边界和缺少运行证据的 API 风险。
不适用于直接发请求、压测、执行安全测试或替团队决定最终 API 版本策略。
## 输出格式选项
- 默认输出 Markdown；用户要求表格、CSV 或 JSON 时，保留相同的证据、状态、影响、责任角色和验证字段。
- 不把结构化格式或静态清单写成执行、通过、批准或发布证据。
## 如何使用
1. 先读取本 Skill 的主 Prompt，并提供目标、范围、材料、环境和已有证据。
2. 按 Prompt 的输入审计和输出合同执行；缺少信息时交付带边界的初版。
3. 对每条发现保留来源、证据状态、影响、责任角色、关闭条件和验证方法。
## 工作方式
1. 阅读 `prompts/api-design-quality-review.md`，审计 API 目标、版本、消费者、范围和证据。
2. 将材料归入 `known`、`missing`、`conflicting`、`stale`、`out_of_scope`、`assumptions`。
3. 按 operation 和稳定字段建立设计覆盖矩阵，使用 `API-##` 绑定来源、证据、影响和验证方法。
4. 分离契约事实、证据推断、建议和 Human 决策；明确兼容性、鉴权和错误处理仍需什么证据。
5. 信息不完整时给出受限初版，不能把请求响应样例当成完整契约。
## 核心约束
- 不执行 API、调用外部服务或声称安全、兼容、性能测试已通过。
- 不从一个样例补造所有字段、错误、权限、限流、幂等或版本规则。
- 每条 `API-##` 至少包含 operation、来源/证据、影响、兼容风险、责任角色、待决策问题和验证方式。
- 未提供执行身份、时间、环境、输入和原始结果时，运行状态只能是 `unverified`、`unexecuted` 或 `unassessed`。
## 参考文件
- 每次产出前必须阅读 `prompts/api-design-quality-review.md`。
- 回归时读取 `evals/eval.yaml` 与用例；结构通过不等于 API 行为通过。
- 触发检查使用 `evals/trigger-prompts.csv` 和 `evals/local-rules.json`；selection trace 缺失时报告 `BLOCKED`。
## 最佳实践
- 优先处理高影响且可验证的缺口，使用最小实验或补证动作降低不确定性。
- 将事实、证据支持的推断、建议和 Human 决策分开，避免把假设升级为结论。
## 交付前自检
- [ ] 已审计 operation、版本、消费者、范围和证据
- [ ] 已检查输入输出、错误、鉴权、幂等、分页、状态码、演进和迁移影响
- [ ] 每个 `API-##` 有最小证据、影响、责任角色和验证方式
- [ ] 已区分样例、设计声明与真实执行证据
- [ ] 没有替团队作兼容策略、风险接受或发布批准
## 常见误区
- 把一个成功响应样例当成完整 OpenAPI 契约。
- 只看状态码，不看错误体、权限、重试、幂等和消费者行为。
- 把文档版本号或工具 lint 通过当成兼容性测试通过。