メニュー
REST API 设计规范——URL 用复数+kebab、HTTP 方法/状态码语义化、单资源直返不包 data、集合带 items/meta/links 分页、错误码 A-BBB-CCCC 结构化、版本管理与限流。触发：设计/审查 API 端点与契约、实现分页/过滤/排序、设计错误响应、规划 API 版本。跳过：GraphQL/gRPC/事件流（非 REST）、内部 RPC 协议、纯前端路由。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
本地 ultrareview——多代理、对抗验证、只读的 PR 级 review；默认 base=main；并发 5 个 finder（质量/安全/简洁/鲁棒性/文档同步），每条 🔴/🟡 发现交 3 个独立怀疑视角对抗验证、多数决去留；可选追加本次 review 重点，注入每个 finder 优先关注（不替代其他维度）。触发：/review、给当前分支做深度审查、PR 前 ultrareview。跳过：不在 git 仓库、当前分支=base。
产出修订（诊断→定向修正→回归验证）——对 spec→plan→exec 偏差做根因归类：spec-defect / impl-defect / requirement-change；先诊断再修正、改代码必先 Red 测试、最小影响只改必须改的层；已完成 plan 是历史审计快照禁止回改；启动先 worktree 感知定位修复现场（主仓库停在 main 时自动定位到进行中的 worktree）。触发：/revise、有 bug、结果不对、和预期不符、产出需要优化、review 发现违规需修复。跳过：纯新增需求（→/spec→/plan）、还没有 spec/plan/代码可对照。
本地 ultrareview——跨模型、多代理、对抗验证、只读的 PR 级 review（依赖 Workflow 工具，Claude Code ≥2.1.154）；默认 base=main；并发 6 个 finder（质量/安全/简洁/鲁棒性/文档同步/Codex 跨模型），每条 🔴/🟡 发现交 3 个独立怀疑视角对抗验证、多数决去留；可选追加本次 review 重点，注入每个 finder 优先关注（不替代其他维度）。触发：/review、给当前分支做深度审查、PR 前 ultrareview。跳过：无 Workflow 工具、不在 git 仓库、当前分支=base。
产出修订（诊断→定向修正→回归验证）——对 spec→plan→exec 偏差做根因归类：spec-defect / impl-defect / requirement-change；先诊断再修正、改代码必先 Red 测试、最小影响只改必须改的层；已完成 plan 是历史审计快照禁止回改；启动先 worktree 感知定位修复现场（主仓库停在 main 时自动定位到进行中的 worktree）。触发：/revise、有 bug、结果不对、和预期不符、产出需要优化、review 发现违规需修复。跳过：纯新增需求（→/spec→/plan）、还没有 spec/plan/代码可对照。
Git 开发流程纪律——禁 main 直接提交；新任务前扫工作区根，有 workspace 标记走多 repo 工作区，否则 `question` 工具 询问 worktree（默认）或切分支；worktree 一律落 `~/.bb-spec/worktrees/` 下、禁嵌套当前 repo / 禁放 sibling 目录；本地 commit 不立即 push、整功能验证完才推；合并后清理本地+远程。触发：开始改代码、提到开分支、要求 commit/push/开 PR、PR 合并后清理。跳过：纯咨询/阅读、极小打字纠错。
前端技术栈强制约束——默认 Vue 3 + TS + Vite + Tailwind；bun 是默认包管理器（新项目强制），既有项目跟随 lockfile 不迁移。触发：新建前端项目；编辑 package.json/vite.config/tailwind.config/.vue/.ts/.tsx；用户提到前端/vue/vite/tailwind。跳过：纯后端/CLI/工具项目；用户明确说用 React/Nuxt/Svelte 等。
| name | api-design |
| description | REST API 设计规范——URL 用复数+kebab、HTTP 方法/状态码语义化、单资源直返不包 data、集合带 items/meta/links 分页、错误码 A-BBB-CCCC 结构化、版本管理与限流。触发：设计/审查 API 端点与契约、实现分页/过滤/排序、设计错误响应、规划 API 版本。跳过：GraphQL/gRPC/事件流（非 REST）、内部 RPC 协议、纯前端路由。 |
设计新 API 端点、审查 API 契约、实现分页/过滤/排序、处理 API 错误、规划版本策略。
/api/v1/team-members/api/v1/users/:id/ordersPOST /api/v1/orders/:id/cancel/getUsers）、单数资源名、snake_case| Method | 幂等 | 用途 |
|---|---|---|
| GET | 是 | 读取 |
| POST | 否 | 创建、触发动作 |
| PUT | 是 | 整体替换 |
| PATCH | 否* | 部分更新 |
| DELETE | 是 | 删除 |
成功：200（GET/PUT/PATCH）、201+Location（POST 创建）、204（DELETE/无 body） 客户端错误：400 校验失败、401 未认证、403 无权限、404 不存在、409 冲突、422 语义无效、429 限流 服务端错误：500 内部错误（不暴露细节）、502 上游失败、503 暂不可用（带 Retry-After）
禁止：200 包一切（{"success":false}）、500 表示校验错误。
单资源：直接返回资源对象，禁止 data 包装。
{ "id": "abc", "name": "...", "created_at": "..." }
集合（带分页）：
{
"items": [...],
"meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 },
"links": { "self": "...", "next": "...", "last": "..." }
}
错误：
{
"error": {
"code": "1-001-0001",
"message": "Request validation failed",
"details": [{ "field": "email", "message": "Must be valid" }]
}
}
错误码格式 A-BBB-CCCC：A = 来源（1 用户端 / 2 系统 / 3 第三方），BBB = 三位模块号，CCCC = 四位模块内编号。error.code 只允许此格式；禁止自由格式（validation_error 等语义字符串）、跨模块复用编号、两套错误码体系并存。
| 场景 | 方式 |
|---|---|
| 后台管理、小数据集 (<10K) | Offset：?page=2&per_page=20 |
| 无限滚动、大数据集、公共 API | Cursor：?cursor=xxx&limit=20（多查一条判断 has_next） |
?status=active&price[gte]=10&price[lte]=100?sort=-created_at,price（- 前缀降序）?q=wireless+headphones?fields=id,name,emailAuthorization: Bearer <token>X-API-Key: sk_live_xxx响应头：X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset
超限返回 429 + Retry-After。
| 层级 | 限额 | 维度 |
|---|---|---|
| 匿名 | 30/min | Per IP |
| 认证用户 | 100/min | Per user |
| 付费 | 1000/min | Per API key |
| 内部服务 | 10000/min | Per service |
推荐 URL 路径版本：/api/v1/users。最多维护 2 个活跃版本。
非破坏性变更（不需要新版本）：新增响应字段、新增可选参数、新增端点。 破坏性变更（需要新版本）：删除/重命名字段、改类型、改 URL 结构、改认证方式。
error.code 用 A-BBB-CCCC）