API Designer 是一个面向 AI 消费的参考技能，优化供 Claude 在执行过程中阅读。其人类可读说明指向 docs/architecture/HIERARCHICAL_PLANNING.md 或 docs/getting-started/ 下的相关文档。该技能的目标是帮助设计一致、RESTful 的 API，并涵盖版本控制、文档与错误处理。
用途 该技能用于在 API 设计阶段提供统一的约定与检查清单，确保端点命名、响应结构、状态码、分页、过滤排序、版本控制和文档保持一致。
主要能力
- RESTful 约定：以表格形式列出方法、端点、用途与响应，例如 GET /users 用于列表返回 200 + 数组，GET /users/:id 获取单个返回 200/404，POST /users 创建返回 201 + 创建结果，PUT /users/:id 替换返回 200/404，PATCH /users/:id 更新返回 200/404，DELETE /users/:id 删除返回 204/404，并支持嵌套如 GET /users/:userId/orders。
- 命名规范：资源使用复数名词（/users、/orders）；查询参数使用 snake_case（page_size）；请求/响应体使用 camelCase；版本控制推荐使用 URL 路径 /api/v1/...。
- 响应格式：成功为 { "data": {...}, "meta": {...} }；列表在 meta 中增加 { page, pageSize, total, totalPages }；错误为 { "error": { "code": "VALIDATION_ERROR", "message": "...", "fields": {...} } }。
- 状态码：200 用于成功的 GET/PUT/PATCH，201 用于成功的 POST，204 用于成功的 DELETE，400/422 用于无效输入/验证，401/403 用于无认证/无权限，404/409 用于未找到/冲突，429 用于限流，500 用于意外错误。
- 分页：偏移量方式 ?page=2&page_size=20（简单，大数据集较慢）；游标方式 ?cursor=abc&limit=20（一致、快速、不支持跳页）。
- 过滤与排序：示例 GET /users?status=active&sort=created_at:desc&q=john&page=1&page_size=20。
使用方式 该技能提供设计工作流：1. 定义资源与关系；2. 选择版本控制策略；3. 使用 RESTful 命名定义端点；4. 指定响应/错误模式；5. 添加分页、过滤、排序；6. 使用 OpenAPI 编写文档；7. 添加限流头。同时提供检查清单：RESTful 命名、一致的响应格式、正确的状态码、列表分页、错误码、版本控制、OpenAPI 文档、限流头。
适用场景 适用于需要设计或审查 RESTful API 的场合，尤其是希望统一命名、响应格式、错误处理、分页与版本控制策略的项目。
限制 该技能为 AI 消费的参考文档，具体实现细节需结合项目实际。相关规则文件包括 rules/agent/api-design-rules.md（执行检查清单）、rules/core/simplicity-over-complexity.md（倾向扁平资源而非嵌套层级，当 REST 适用时拒绝过早引入 GraphQL，不添加推测性的“面向未来”字段）、rules/agent/structured-data-schema.md（跨端点一致的模式）、rules/agent/error-handling-standard.md（统一错误封装）。