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

2026-03-24 14:21:37 +08:00
parent c43b6be153
commit cfacf55035
9 changed files with 211 additions and 8 deletions
--- a/.cursor/docs/skill-writing-principles.md
+++ b/.cursor/docs/skill-writing-principles.md
@@ -0,0 +1,60 @@
+# Skill 撰写原则（吸收 Anthropic 实践）
+
+> 来源：Thariq Shihipar 分享的 Anthropic 内部 Skills 方法论。本文档供维护 `.cursor/skills/` 时参考。
+
+## 1. 写 Claude 不知道的东西
+
+Claude 对编程已很熟，有默认偏好。好的 Skill 应聚焦**能把 Claude 推出惯性思维**的信息：
+
+- 团队独特规范（如 Soul 三端路由隔离、Toast 禁 alert）
+- 行业或项目不成文惯例
+- 过去踩过的坑、边界条件
+- 与通用实践不同的决策（如为什么用 key 而非 appId）
+
+**避免**：大段重复 Claude 已掌握的通用知识。
+
+## 2. Gotchas 是 Skill 的灵魂
+
+任何 Skill 里**信息密度最高**的就是踩坑清单。应从实际失败中积累，随使用不断更新。
+
+- 格式：陷阱 → 后果 → 正确做法
+- 信号强于「怎么做对」：告诉 AI「千万别这么做」更有效
+- 每次 Claude 踩新坑，就往对应 Skill 的 Gotchas 表追加一行
+
+## 3. 给指令留灵活空间
+
+Skill 高度可复用，写得太死会令 AI 在稍不同情况下手足无措。
+
+- 给**方向与原则**，而非死板步骤
+- 提供必要信息，同时留出根据实际情况灵活应变的余地
+- 检查清单、必守规则是好的；过度细化的「第一步第二步第三步」可酌情简化
+
+## 4. 让 Skill 拥有记忆
+
+通过内部存储实现记忆：
+
+- 追加式日志（如 `sync-log.md`）：记录每次执行摘要，下次可对比增量
+- 进化池（evolution）：经验按日期沉淀，形成团队知识库
+- 理想：Skill 不只干活，还能「记得上次干了什么」
+
+## 5. 给现成的代码与模板
+
+AI 擅长组合与决策，不擅长记公司特有细节。最高效协作方式：
+
+- 提供脚本（如 db-exec、一键-添加经验.bat）
+- 提供模板（evolution 模板、会议纪要模板）
+- 把精力留给 AI 做组合和决策，而不是从零写样板
+
+## 6. Skill 是文件夹，不是单文件
+
+一个 Skill 可包含：
+
+- `SKILL.md`：入口，行为与触发条件
+- `scripts/`：可执行脚本
+- `references/`：参考文档、路径速查
+- `assets/`：模板、配置
+- 日志文件：记忆
+
+## 7. 从简单开始，持续迭代
+
+大多数 Skill 一开始只有几行文字加一条踩坑提醒。随 Claude 遇到新边界情况，再一点一点完善。不追求一步到位。
--- a/.cursor/rules/老板分身-索引.mdc
+++ b/.cursor/rules/老板分身-索引.mdc
@@ -8,6 +8,7 @@ alwaysApply: true
 > **老板分身权限最高**：协调所有智能体（小程序开发工程师、管理端开发工程师、后端工程师、产品经理、开发助理等）。其他 agent 执行任务时遵循本规则；老板分身可调度、协调、指派任一角色。
 > **激活方式**：用户说「老板」「分身」「乘风」「架构」「帮我协调」时，从旁观者转为主动参与。**开会时**：用户说「开会」「开个会」「团队会议」「乘风开会」「需求评审」「方案讨论」等表达开会意图时，**必须先**用 Read 工具读取 `e:\Gongsi\Mycontent\.cursor\skills\team-meeting\SKILL.md` 完整内容，然后由老板分身（乘风）按该协议主持多角色会议，不可仅回复而不执行流程。
 > **会话自检**：仅沿用本项目 `.cursor/` 下的 rules、skills、agent；忽略与本项目无关的全局 rules/skills。
+> **Skill 撰写**：维护或新增 Skill 时参考 `e:\Gongsi\Mycontent\.cursor\docs\skill-writing-principles.md`（写 Claude 不知道的、Gotchas 是灵魂、留灵活空间）。
 > **角色驱动**：Soul 角色与 agent 映射见 `config/paths.py` 的 ROLE_TO_AGENT。

 ### 领域特例优先（含合理性校验）
--- a/.cursor/skills/admin-dev/SKILL.md
+++ b/.cursor/skills/admin-dev/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: soul-admin-dev
-description: Soul 创业派对管理端开发规范。在 soul-admin/ 下编辑时必遵循。React、Vite、client.ts、/api/admin/*、/api/db/*、Radix UI、鉴权。Use when editing soul-admin, 管理端, React 管理后台.
+description: Trigger when 编辑 soul-admin、管理端、React 后台、调用 admin/db 接口 时必读。React、Vite、client.ts、/api/admin/*、/api/db/*、Radix UI、Toast、禁止 alert。
 ---
 # Soul 创业派对 - 管理端开发 Skill

@@ -145,10 +145,28 @@ alert('保存失败')

 ---

-## 8. 何时使用本 Skill
+## 8. 常见陷阱（Gotchas）
+
+> 从实际失败中积累，持续补充。**千万别这么做**——对 AI 信号更强。
+
+| 陷阱 | 后果 | 正确做法 |
+|------|------|---------|
+| 调用 `/api/miniprogram/*` | 路由互窜、鉴权混乱 | 仅用 `/api/admin/*`、`/api/db/*` |
+| 使用 `alert()`、`window.alert()` | 用户反馈不规范、阻断流程 | 统一用 `@/utils/toast`（success/error/info） |
+| 在 input/textarea 自身上设 padding | 光标截断、布局异常 | 外边包 div，padding 写在容器，input 设 `width:100%` |
+| 可选字段（T 或 undefined）直接赋给必填 T | TS2322 类型错误 | 用 `?? defaultValue` 兜底，如 `t.appId ?? ''` |
+| 接口缺字段但 API 已返回 | 运行时取不到、展示异常 | 在 interface 补 `field?: Type`（如 `isPinned?: boolean`） |
+| useState 的 setter 传 undefined | setter 类型错误 | 传 `value ?? null` 而非裸 `value` |
+| API 映射时 `p.token` 等可能 undefined | 流入 state 导致异常 | `id: p.token ?? p.personId ?? ''`，`label: p.label ?? ''` |
+| 新增管理页忘记加路由/菜单 | 404 或菜单不可见 | 在 `App.tsx` 加 Route，在 `AdminLayout` 的 `menuItems` 加菜单项 |
+
+---
+
+## 9. 何时使用本 Skill

 - 在 **soul-admin/** 下新增或修改页面、组件、API 调用时。
 - 在管理端新增任何网络请求时（必须仅使用 admin/db 等管理端路径）。
 - 做提现、用户、订单、内容、配置等后台功能时。

 遵循本 Skill 可保证管理端只与 soul-api 的管理端路由对接，避免与小程序接口混用或误用 next-project 接口。
+
--- a/.cursor/skills/api-dev/SKILL.md
+++ b/.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 接口时（必须先明确使用方再挂路由）。
--- a/.cursor/skills/assistant-doc-sync/SKILL.md
+++ b/.cursor/skills/assistant-doc-sync/SKILL.md
@@ -1,5 +1,5 @@
 ---
-description: 开发团队文档同步与经验升级。小橙、橙子、讨论完毕、吸收经验、任务完成、会议收尾。Use when 小橙, 橙子, 橙橙, 讨论完毕, 记录一下, 同步文档, 吸收经验, 升级skills, 记录经验, 保存开发进度, 更新项目索引, 记录开发进度, 任务完成, 搞定了, 完成了, 会议结束, 散会.
+description: Trigger when 小橙/橙子/讨论完毕/记录一下/同步文档/吸收经验/升级skills/任务完成/搞定了/会议结束/散会 时必读。文档同步、经验入库、会议收尾、项目索引更新。
 ---
 # SKILL - 助理橙子（小橙/橙子/橙橙/🍊）

@@ -16,6 +16,11 @@ description: 开发团队文档同步与经验升级。小橙、橙子、讨论
 | **任务完成、搞定了、完成了** | **同上**，自动更新项目索引（口语化触发） |
 | **会议结束、散会、会开完了** | **会议收尾**：纪要 + 经验入库 |

+## 记忆机制（sync-log）
+
+- **执行前**：可读取 `skills/assistant-doc-sync/sync-log.md`，了解上次以来发生的变化，只汇报增量或聚焦未闭环项
+- **执行后**：在 `sync-log.md` 末尾**追加**一行，格式 `- YYYY-MM-DD {动作}：{简要摘要}`（如：讨论完毕、会议收尾、吸收经验、保存进度）
+
 ## 执行流程

 ### 1. 提炼讨论要点
@@ -68,7 +73,8 @@ description: 开发团队文档同步与经验升级。小橙、橙子、讨论
 3. **更新项目索引**：各参会角色对应的 `agent/开发助理/项目索引/{索引名}.md` 开发进度表追加一行，写日期
 4. **更新会议记录索引**：`e:\Gongsi\Mycontent\.cursor\meeting\README.md` 索引表追加
 5. **Skill 升级**（若有影响开发规范的决议）：更新对应 SKILL-xxx.md
-6. **回复**：会议收尾已完成，纪要见 `meeting/YYYY-MM-DD_主题.md`
+6. **更新 sync-log**：在 `sync-log.md` 末尾追加 `- YYYY-MM-DD 会议收尾：{主题}`
+7. **回复**：会议收尾已完成，纪要见 `meeting/YYYY-MM-DD_主题.md`

 ### 5. 经验吸收与 Skills 升级（开发团队经验库）

@@ -126,6 +132,28 @@ description: 开发团队文档同步与经验升级。小橙、橙子、讨论

 6. **回复**：已吸收经验并升级 Skills，详见 `agent/{角色}/evolution/YYYY-MM-DD.md` 与 `经验清单.md`

+7. **更新 sync-log**：在 `skills/assistant-doc-sync/sync-log.md` 末尾追加一行，格式：`- YYYY-MM-DD 吸收经验：{角色} {简短摘要}`
+
+## 模板（按需取用）
+
+| 用途 | 路径 |
+|------|------|
+| evolution 经验条目 | `skills/assistant-doc-sync/assets/evolution-template.md` |
+| 会议纪要 | `meeting/_模板.md` |
+
+## 可执行脚本（按需调用）
+
+| 脚本 | 路径 | 用途 |
+|------|------|------|
+| 一键-添加经验 | `agent/开发助理/script/一键-添加经验.bat` | 用户双击执行，将 JSON 经验写入 evolution |
+| 一键-执行进化 | `agent/开发助理/script/一键-执行进化.bat` | 执行 evolution 流程 |
+| 一键-列出经验池 | `agent/开发助理/script/一键-列出经验池.bat` | 列出各角色经验文件 |
+| 一键-全部 | `agent/开发助理/script/一键-全部.bat` | 聚合执行 |
+
+无法写文件时，可输出 JSON 并提示用户双击 `一键-添加经验.bat`。
+
+**渐进式揭露**：详细路径见 `references/paths.md`，AI 可按需读取。
+
 ## 文档结构速查

 ```
--- a/.cursor/skills/assistant-doc-sync/assets/evolution-template.md
+++ b/.cursor/skills/assistant-doc-sync/assets/evolution-template.md
@@ -0,0 +1,21 @@
+# {角色名} 经验记录 - YYYY-MM-DD
+
+## {主题/场景简短描述}
+
+### 问题
+
+（若为 bug 修复）具体问题描述、报错、复现条件。
+
+### 解决方案
+
+（可选）表格或列表说明解决步骤、关键代码、配置变更。
+
+### 规则提炼
+
+（可选）从本次经验提炼的可复用规则，便于升级 Skill 或 Gotchas。
+
+---
+
+## {第二个经验点}
+
+（同上结构，可重复多个）
--- a/.cursor/skills/assistant-doc-sync/references/paths.md
+++ b/.cursor/skills/assistant-doc-sync/references/paths.md
@@ -0,0 +1,31 @@
+# 助理橙子 - 关键路径速查
+
+> 供 AI 按需读取，不必一次加载全部。
+
+## 经验与索引
+
+| 角色 | evolution 目录 | 项目索引文件 |
+|------|----------------|-------------|
+| 小程序 | `agent/小程序开发工程师/evolution/` | `agent/开发助理/项目索引/小程序.md` |
+| 管理端 | `agent/管理端开发工程师/evolution/` | `agent/开发助理/项目索引/管理端.md` |
+| 后端 | `agent/后端工程师/evolution/` | `agent/开发助理/项目索引/后端.md` |
+| 产品 | `agent/产品经理/evolution/` | `agent/开发助理/项目索引/产品.md` |
+| 测试 | `agent/软件测试/evolution/` | `agent/开发助理/项目索引/测试.md` |
+| 助理橙子 | `agent/开发助理/evolution/` | `agent/开发助理/项目索引/助理橙子.md` |
+| 团队/安全 | `agent/团队/evolution/` | `agent/开发助理/项目索引/团队.md` |
+
+## 需求与文档
+
+- 需求主文件：`开发文档/1、需求/` 下日期最新的 `YYYY-MM-DD-需求.md`
+- 需求索引：`开发文档/1、需求/索引.md`
+- 界面基准：`开发文档/1、需求/以界面定需求.md`
+- 运营变更：`开发文档/10、项目管理/运营与变更.md`
+- 落地推进表：`开发文档/10、项目管理/项目落地推进表.md`
+- 经验清单：`agent/开发助理/经验清单.md`
+
+## 会议
+
+- 纪要目录：`meeting/`
+- 纪要索引：`meeting/README.md`
+- 模板：`meeting/_模板.md`
+- 会议收尾流程：`skills/team-meeting/SKILL.md` 第 4 节
--- a/.cursor/skills/assistant-doc-sync/sync-log.md
+++ b/.cursor/skills/assistant-doc-sync/sync-log.md
@@ -0,0 +1,11 @@
+# 助理橙子同步记录
+
+> **记忆机制**：记录每次文档同步、经验入库、会议收尾的摘要。下次执行时可先读取此文件，对比「上次以来有什么变化」，只汇报增量或聚焦未闭环项。
+>
+> 格式：日期 + 动作类型 + 摘要（一行）。由助理橙子在每次执行后**追加**，不覆盖。
+
+---
+
+## 2026-03-24
+
+-  Skill 优化：assistant-doc-sync 新增 sync-log 记忆机制、assets 模板、Skill 撰写原则
--- a/.cursor/skills/miniprogram-dev/SKILL.md
+++ b/.cursor/skills/miniprogram-dev/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: soul-miniprogram-dev
-description: Soul 创业派对小程序开发规范。在 miniprogram/ 下编辑时必遵循。WXML/WXSS/JS、app.request、/api/miniprogram/*、scene、支付、权限。Use when editing miniprogram, 小程序, 微信原生.
+description: Trigger when 编辑 miniprogram、小程序、微信原生、C 端、调用 miniprogram 接口、支付/提现/推荐 时必读。WXML/WXSS、app.request、仅用 /api/miniprogram/*。
 ---
 # Soul 创业派对 - 小程序开发 Skill

@@ -123,7 +123,24 @@ description: Soul 创业派对小程序开发规范。在 miniprogram/ 下编辑

 ---

-## 12. 何时使用本 Skill
+## 12. 常见陷阱（Gotchas）
+
+> 从实际失败中积累，持续补充。**千万别这么做**——对 AI 信号更强。
+
+| 陷阱 | 后果 | 正确做法 |
+|------|------|---------|
+| 调用 `/api/admin/*`、`/api/db/*` | 路由互窜、鉴权不符 | 仅用 `/api/miniprogram/*` |
+| 页面里直接 `wx.request` 写死 baseUrl | 配置分散、难切换环境 | 统一 `getApp().request(url, options)` |
+| 在 input/textarea 自身上设 padding | 光标截断、布局异常 | 外边包 view，padding 写在 view，input `width:100%` |
+| button 包裹目标元素做 chooseAvatar | 原生样式干扰（灰框、边框） | button 绝对定位覆盖，同级关系，透明背景 |
+| 分享链路（支付/领取/代付）不判断单页模式 | 朋友圈打开能力受限、报错 | `wx.getSystemInfoSync()?.mode === 'singlePage'` 时引导「前往小程序」 |
+| 支付前不校验头像/昵称 | 超级个体开通后资料为默认 | 支付前校验，不通过则 `navigateTo('/pages/avatar-nickname/avatar-nickname')` |
+| app.onLaunch 中集中请求隐私授权 | 平台合规风险、审核不通过 | 按需授权，用户**实际触发功能时**再请求 |
+| 用 `selectable` 做文本复制 | 已废弃 | 用 `<text user-select>...</text>`（基础库 2.12.1+） |
+
+---
+
+## 13. 何时使用本 Skill

 - 在 **miniprogram/** 下新增或修改页面、组件、utils 时。
 - 在小程序内新增或修改任何网络请求路径时（必须保持 `/api/miniprogram/...`）。