用途：在 API 设计阶段使用，规划新端点或修改现有契约、定义请求/响应模式、统一分页/过滤/排序、设计一致错误格式、规划版本与弃用策略、评审契约一致性、编写前后端协作文档。若存在 plan.md 或 architecture.md 会先读取作为上下文，否则直接依据用户请求。输出写入 api-design.md，并提示运行 /task-decomposition 或 /python-backend-expert。
主要能力：URL 命名约定（集合用复数名词、多词用 kebab-case、按 ID 用单数、最多两层嵌套、URL 不含动词、过滤排序分页用查询参数）；HTTP 方法语义表（GET/POST/PUT/PATCH/DELETE 的用途、请求体、成功状态码与幂等性，POST 201 应带 Location 头，GET 可用 ETag/If-None-Match）；Pydantic v2 模式命名（{Resource}Create/Update/Patch/Response/ListResponse/Filter），响应不暴露内部字段、包含 id 与时间戳，PATCH 用 model_dump(exclude_unset=True)；默认游标分页（cursor、limit 默认 20 最大 100，返回 items、next_cursor、has_more，游标对客户端不透明，取 limit+1 判断 has_more），需要跳页时用偏移分页；过滤与排序约定（精确、范围、q 搜索、多值 OR；sort 前缀 - 表示降序）；统一错误响应（detail、code、field_errors）及 400/401/403/404/409/422/429/500 映射；URL 前缀版本策略（/v1 起步、仅破坏性变更升版本、最多同时支持两个版本、Deprecation/Sunset/Link 头弃用流程）；OpenAPI 文档约定（summary、description、responses、tags、response_model）。
边界情况：批量操作用 POST /v1/users/bulk，部分成功返回 207；文件上传用 multipart/form-data，超限返回 413；长任务返回 202 与 status_url 供轮询；嵌套超两层时改用顶层资源加过滤。
限制：不用于编写实现代码、系统级架构决策、端点测试或前端数据获取实现。具体收费、平台与效果资料暂未提供。