메뉴
当需要设计API规范时使用。API设计规范产出，从PRD自动设计RESTful/GraphQL接口契约、安全策略和认证鉴权方案，生成OpenAPI 3.0规范。内建合规检查确保API安全合规。产出经人类审查后，交由api-design-impl生成代码。关键词：API设计、接口契约、OpenAPI、RESTful、GraphQL、API安全、认证鉴权、JWT、OAuth2、RBAC、写接口、接口文档。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | api-design-spec |
| description | 当需要设计API规范时使用。API设计规范产出，从PRD自动设计RESTful/GraphQL接口契约、安全策略和认证鉴权方案，生成OpenAPI 3.0规范。内建合规检查确保API安全合规。产出经人类审查后，交由api-design-impl生成代码。关键词：API设计、接口契约、OpenAPI、RESTful、GraphQL、API安全、认证鉴权、JWT、OAuth2、RBAC、写接口、接口文档。 |
| metadata | {"module":"后端架构与开发","sub-module":"API设计","type":"pipeline","version":"4.0","domain_tags":["电商","SaaS","金融","通用"],"trigger_examples":["设计API接口","写接口文档","定义接口规范","接口安全防护","做登录认证","设计权限系统"],"interaction_mode":"ai_suggest_human_approve"} |
🤖→👤 AI建议人类审批
| 输入项 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
| PRD | markdown | 是 | output/pm-design/design-prd/prd.md | 产品需求文档 |
| PRD结构化数据 | JSON | 是 | output/pm-design/design-prd/prd.json | PRD机器可消费版本，包含features[]/entities[]，供API设计编程式消费 |
| 数据模型 | JSON | ○ | output/backend-data-architecture/data-architecture-spec/er_model.json | 数据实体和关系定义（API设计阶段通常未就绪，从PRD推导） |
| 业务流程 | JSON | ○ | output/pm-design/design-userflow/userflow.json | 用户流程定义 |
| 安全等级 | string | 是 | 用户提供 | 标准 / 高安全（金融/医疗） |
| 合规要求 | string | ○ | 用户提供 | GDPR / 等保 / PCI-DSS |
| 多租户需求 | string | ○ | 用户提供 | 是否需要多租户隔离 |
| 前端页面数据需求 | JSON | ○ | output/ui-frontend/page-builder/pages.json | 前端页面数据获取需求，确保API与前端对齐 |
从PRD和数据模型中识别API资源：
资源命名规范：
/courses 而非 /course/courses/{id}/lessons/user-groups 而非 /userGroups为每个资源设计标准接口：
| 操作 | Method | Path | 说明 |
|---|---|---|---|
| 列表查询 | GET | /resources | 分页+筛选+排序 |
| 详情查询 | GET | /resources/{id} | 单个资源详情 |
| 创建 | POST | /resources | 创建新资源 |
| 全量更新 | PUT | /resources/{id} | 替换整个资源 |
| 部分更新 | PATCH | /resources/{id} | 更新指定字段 |
| 删除 | DELETE | /resources/{id} | 删除资源 |
定义统一的请求响应格式、错误码体系和版本策略。
阶段卡口：每个资源有CRUD定义+错误码体系
按敏感度对接口分级：
| 级别 | 接口类型 | 访问控制 | 审计要求 |
|---|---|---|---|
| L1-公开 | 健康检查、公开文档 | 无鉴权 | 无 |
| L2-认证 | 用户个人信息、业务查询 | Token鉴权 | 查询日志 |
| L3-授权 | 写操作、管理功能 | Token+权限校验 | 操作日志+变更记录 |
| L4-敏感 | 支付、密钥、数据导出 | Token+权限+二次验证 | 全量审计+告警 |
设计限流策略、数据安全（加密/脱敏/输入校验）、CORS和安全头。
阶段卡口：100%接口有安全级别+限流规则，L4接口安全策略完整
根据业务场景选择认证方案（JWT/OAuth2/SSO），设计权限模型（RBAC/ABAC），多租户隔离和会话管理。
阶段卡口：认证方案+权限模型+会话管理完整
内建隐私合规评估：
阶段卡口：合规检查无P0问题
元数据输出：output/backend-api-design/api-design-spec/
输出文件：
| 条件 | 决策 |
|---|---|
| 资源间多对多关系 | 创建关联资源 |
| 查询条件≥5个 | 考虑提供GraphQL端点 |
| 安全等级=高安全 | L3+接口全部请求签名+全量审计 |
| 角色数≤10且固定 | 使用RBAC |
| 角色数>10或频繁变化 | 使用RBAC+权限组 |
| 多租户+租户数>100 | 共享数据库+tenant_id |
| 涉及个人隐私数据 | 强制脱敏+加密存储+合规检查 |
| 合规要求含GDPR | 数据导出接口+数据删除接口 |
| 缺失的上游输入 | 降级方案 | 输出影响 |
|---|---|---|
| 数据模型缺失 | 从PRD推导核心实体 | 资源定义基于推导，标注"待数据模型确认" |
| 业务流程缺失 | 仅设计CRUD接口 | 缺少跨资源的业务接口 |
| PRD缺失 | 无法设计API | 输出为空 |
| 安全等级未指定 | 默认标准等级 | 可能不满足高安全要求 |
| 前端页面数据需求缺失 | 仅基于PRD设计API | 可能与前端实际需求不完全匹配 |
| 上游变更 | 影响范围 | 响应策略 |
|---|---|---|
| PRD功能点增删 | API端点增删 | 标注受影响的API端点，生成变更清单 |
| 数据模型变更 | API请求/响应结构 | 标注受影响的字段，评估向后兼容性 |
| API变更类型 | 兼容性 | 通知范围 | 通知方式 |
|---|---|---|---|
| 新增端点 | 向后兼容 | api-design-impl | 标记新增端点，实现Skill可增量生成 |
| 删除端点 | 破坏性变更 | api-design-impl | 必须人类确认，提供迁移方案 |
| 修改字段类型 | 破坏性变更 | api-design-impl | 必须人类确认，提供兼容方案 |
当需要评估获客渠道或优化获客漏斗时使用。用户获取指挥官，调度 acquisition-analysis（获客分析一体化），实现从渠道评估到漏斗优化的闭环。关键词：用户获取、获客渠道、漏斗优化、渠道评估、获客策略、acquisition-analysis、拉新、获客。
当需要识别和工程化Aha Moment时使用。Aha Moment自动工程化Pipeline，分析留存数据和行为数据，自动识别Aha Moment候选，测量到达率，识别最短路径，输出Onboarding优化建议。关键词：Aha Moment、激活时刻、用户激活、到达率、Onboarding优化、什么时候觉得好用、体验核心价值、爽点在哪。
当需要优化用户Onboarding流程时使用。Onboarding自动优化Pipeline，分析Onboarding数据和用户分群，自动生成个性化引导策略，设计A/B测试方案。关键词：Onboarding、新用户引导、引导优化、个性化引导、用户激活、新手引导、上手快、引导太长。
当需要识别Aha Moment或设计Onboarding流程时使用。用户激活指挥官，调度activation-aha/onboarding。关键词：用户激活、Aha Moment、Onboarding、新用户引导、新手引导、激活率。
当需要管理Sprint周期或追踪敏捷执行时使用。敏捷执行指挥官，调度 agile-sprint-planning、agile-daily-sync、agile-review 子Skill执行。agile-review 已合并 retrospective-auto 的自动回顾能力。关键词：敏捷执行、Sprint规划、每日站会、Sprint评审、敏捷管理、Sprint复盘、迭代复盘、敏捷开发、复盘报告、自动回顾。
当需要自动化Sprint评审和复盘报告时使用。Sprint评审与复盘报告一体化，Step 1完成Sprint评审（产出清单整理、Demo准备清单、反馈收集分类、数据收集、问题识别、改进建议生成），Step 2生成完整复盘报告（Sprint目标达成分析、交付质量评估、团队速率趋势、改进行动项、下一Sprint建议），Step 3完成上线复盘（效果复盘、工程质量复盘、过程复盘、改进行动项生成）。关键词：Sprint Review、Sprint Retro、迭代评审、迭代回顾、敏捷复盘、评审会、复盘报告、Sprint复盘、改进行动项、做得怎么样、上线复盘、发布复盘、效果评估、持续改进。