更新多个技能文档，新增常见陷阱（Gotchas）部分，提供开发过程中需避免的错误及其解决方案，提升开发团队的规范性和效率。同时，更新描述以更清晰地指引使用场景，确保文档内容的准确性和实用性。

.cursor/skills/api-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: soul-api-dev
-description: Soul 创业派对后端 API 开发规范。在 soul-api/ 下编辑时必遵循。Go、Gin、GORM、路由分组 miniprogram/admin/db、响应格式。Use when editing soul-api, 后端, API, Go.
+description: Trigger when 编辑 soul-api、后端、API、Go、Gin、GORM、新增接口、路由分组 时必读。按使用方挂载 miniprogram/admin/db，严禁混用。
 ---
 # Soul 创业派对 - API 开发 Skill（soul-api）
 
@@ -99,7 +99,23 @@ description: Soul 创业派对后端 API 开发规范。在 soul-api/ 下编辑
 
 ---
 
-## 7. 何时使用本 Skill
+## 7. 常见陷阱（Gotchas）
+
+> 从实际失败中积累，持续补充。**千万别这么做**——对 AI 信号更强。
+
+| 陷阱 | 后果 | 正确做法 |
+|------|------|---------|
+| 管理端专用接口挂到 miniprogram 组 | 小程序误调、鉴权混乱 | 仅 admin/db 用 → 只挂 admin 或 db |
+| 小程序专用接口挂到 admin 组 | 管理端误调、鉴权不符 | 仅 miniprogram 用 → 只挂 miniprogram |
+| 新增接口未明确使用方就开写 | 路径混用、两端互窜 | 先判断小程序/管理端/两端共用 → 再挂 Group |
+| handler 内混用「管理端路径」与「小程序路径」语义 | 逻辑混乱、难以维护 | 同一 handler 可两处注册，路径必须显式分开 |
+| 新增表/字段后未执行迁移 | 线上报错、字段缺失 | 编写 scripts/add-xxx.sql → 执行 `node .cursor/scripts/db-exec/run.js -f soul-api/scripts/add-xxx.sql` |
+| 新增 model 未 AutoMigrate | 表不存在、启动失败 | 在 `internal/database/database.go` 中 `AutoMigrate(&model.Xxx{})` |
+| 业务逻辑直接 `os.Getenv` | 配置分散、难维护 | 仅通过 `internal/config` 的 `Load()` 读环境变量 |
+
+---
+
+## 8. 何时使用本 Skill
 
 - 在 **soul-api/** 下新增或修改路由、handler、model、config、wechat 时。
 - 新增任何 HTTP 接口时（必须先明确使用方再挂路由）。