API工程师技能 - API设计规范、版本控制、错误处理、并发安全、性能优化、文档。当你新建/修改任何API端点、路由、控制器、HTTP请求处理、响应格式、中间件时必须使用此技能。即使用户只是说"加个接口"或"改下返回值"，也应触发。
API工程师技能 - API设计规范、版本控制、错误处理、并发安全、性能优化、文档。当你新建/修改任何API端点、路由、控制器、HTTP请求处理、响应格式、中间件时必须使用此技能。即使用户只是说"加个接口"或"改下返回值"，也应触发。
npx skills add https://github.com/yuexueyu/anna-agent-skills --skill api-design复制此命令并粘贴到 Claude Code 中以安装该技能
Apple原生开发技能 - Swift/SwiftUI/AppKit/UIKit原生组件、API选择、权限配置、图标规格、Liquid Glass、上架规则、macOS/iOS平台特性。当你涉及Swift/SwiftUI/AppKit/UIKit原生开发、Apple平台特性、Xcode配置、权限entitlements、图标资源、App Store上架、Liquid Glass效果时必须使用此技能。即使用户只是说"用原生的"或"加个SwiftUI视图"，也应触发。
后端资深工程师技能 - 架构设计、服务端开发、中间件、错误处理、日志、配置管理、部署运维。当你涉及后端服务开发、Go/Python/Node/Java/PHP后端代码、中间件配置、服务间通信、配置管理、日志策略、进程管理、交叉编译、部署流程时必须使用此技能。即使用户只是说"写个接口"或"后端加个功能"，也应触发。
代码审计技能 - 安全审计、代码质量审查、漏洞挖掘。当你涉及安全检查、漏洞修复、权限/认证逻辑修改、密钥管理、输入验证、OWASP相关问题时必须使用此技能。即使用户只是说"检查下安全"或"加个权限判断"，也应触发。
数据库工程师技能 - Schema设计、索引优化、并发安全、数据库审计。当你涉及数据库表/字段/索引/SQL/迁移/MCP数据库操作、建表改表、写查询时必须使用此技能。即使用户只是说"加个字段"或"查下数据"，也应触发。
Flutter跨端开发技能 - Dart语言、Widget组件、状态管理、平台通道(MethodChannel/EventChannel/Pigeon/FFI)、硬件对接(BLE/传感器/USB)、性能优化、常见坑、打包发布。当你涉及Flutter/Dart代码开发、跨平台UI、平台通道、原生插件、硬件通信、Flutter打包发布时必须使用此技能。即使用户只是说"Flutter加个功能"或"跨端开发"，也应触发。
Git工作流技能 - 提交规范、分支策略、冲突解决、提交验证。当你涉及git commit、git push、分支操作、合并、提交信息编写、代码提交时必须使用此技能。即使用户只是说"提交一下"或"git"，也应触发。
| name | api-design |
| description | API工程师技能 - API设计规范、版本控制、错误处理、并发安全、性能优化、文档。当你新建/修改任何API端点、路由、控制器、HTTP请求处理、响应格式、中间件时必须使用此技能。即使用户只是说"加个接口"或"改下返回值"，也应触发。 |
[API核心清单] ① 资源用名词复数+≤2层嵌套，❌动词URL ② 统一
{code,data,message}响应，列表必须分页(默认20最大100) ③ 新端点默认需认证，CRUD必须验资源所有权 [幂等三条] POST用Idempotency-Key防重复，PUT/DELETE天然幂等，支付类必须服务端去重 [安全三禁] ❌直接返回DB模型(用DTO) ❌返回密码hash/内部ID ❌500返回堆栈
写/改API端点时，强制遵守：
/users)，嵌套≤2层，❌禁止动词URL(/getUser)（动词URL破坏REST语义，导致端点爆炸且无法统一缓存/权限策略）{code, data, message}，列表带分页(默认20最大100)，空列表返回[]非null新增端点前：Grep确认无重复端点 → 确认命名风格一致 → 确认已加认证中间件
扫描所有API端点（Grep路由定义/Controller/Handler）：
检查API一致性：
URL设计：
/users不是/getUser或/user/users/{id}/orders（不超过2层嵌套）/users?status=active&sort=-created_at/getUsers//deleteUser)、深层嵌套(>2层)、无意义ID暴露（动词破坏统一性，深嵌套增加耦合度，暴露内部ID助力枚举攻击）HTTP方法：
状态码规范：
| 状态码 | 含义 | 使用场景 |
|---|---|---|
| 200 | 成功 | GET/PUT/PATCH/DELETE成功 |
| 201 | 已创建 | POST创建成功 |
| 204 | 无内容 | DELETE成功且无返回体 |
| 400 | 请求错误 | 参数验证失败、格式错误 |
| 401 | 未认证 | 未登录、Token过期 |
| 403 | 无权限 | 已认证但无权访问该资源 |
| 404 | 不存在 | 资源不存在 |
| 409 | 冲突 | 资源已存在、版本冲突 |
| 422 | 无法处理 | 参数合法但业务逻辑不允许 |
| 429 | 请求过多 | 速率限制 |
| 500 | 服务器错误 | 未预期的内部错误 |
请求规范：
page+page_size或cursor+limit，有最大值限制响应格式（全局统一）：
// 成功
{
"code": 0,
"data": { ... },
"message": "success"
}
// 列表（带分页）
{
"code": 0,
"data": {
"items": [ ... ],
"total": 100,
"page": 1,
"page_size": 20
}
}
// 错误
{
"code": 40001,
"message": "用户友好的错误描述",
"details": [
{ "field": "email", "reason": "格式不正确" }
]
}
[]不是nullundefined0不是null（除非null有语义意义）认证规范：
@public显式标记授权规范：
GET /users/{id}/orders → 必须验证当前用户有权查看该用户的订单| 层级 | 处理方式 | 示例 |
|---|---|---|
| 参数验证层 | 返回400+具体字段错误 | 邮箱格式错误 |
| 业务逻辑层 | 返回422+业务原因 | 余额不足 |
| 权限层 | 返回401/403 | 未登录/无权限 |
| 基础设施层 | 返回503+重试提示 | 数据库连接失败 |
| 未知错误层 | 返回500+错误ID | 便于日志追踪 |
- 每个500错误必须生成唯一ID，日志中可追踪
- 生产环境500不返回堆栈，只返回错误ID
- 第三方服务失败：返回503而非500，告知客户端可重试
12. 幂等性设计： - POST创建：用幂等键(Idempotency-Key)防重复创建 - PUT/DELETE：天然幂等（重复执行结果相同） - 支付/转账类：必须有幂等键+服务端去重 - ❌ 禁止：POST创建无去重机制（网络重试=重复数据）
并发安全：
UPDATE ... WHERE version = ?），冲突返回409性能规范：
缓存策略：
版本策略：
/v1/users、/v2/users向后兼容规则：
文档规范：
测试覆盖：
## API审查报告
### 端点清单
| 方法 | 路径 | Handler | 认证 | 状态 |
### 设计规范违规
| # | 端点 | 问题类型 | 描述 | 修复建议 | 严重度 |
### 安全问题
| # | 端点/文件:行号 | 问题 | 攻击场景 | 修复建议 | 严重度 |
### 性能风险
| # | 端点 | 问题 | 影响 | 优化方案 | 优先级 |
### 一致性问题
| 类别 | 当前状态 | 建议统一方案 |
### 缺失项
| 类别 | 缺失内容 | 建议 | 优先级 |