菜单
把本次踩到的坑写进 .qoder/business-logic/gotchas.md，每条强制 4 段结构（现象 / 根因 / 正确做法 / 反例）。比 /update-context 更窄、更结构化——只管 gotcha 这一类。
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/jackwener/exam-system --skill record-gotcha命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | record-gotcha |
| description | 把本次踩到的坑写进 .qoder/business-logic/gotchas.md，每条强制 4 段结构（现象 / 根因 / 正确做法 / 反例）。比 /update-context 更窄、更结构化——只管 gotcha 这一类。 |
发现以下任一情况后立刻用：
/hunt 找到 root cause 后，确认这是会重复出现的问题不适用的场景（用 /update-context 而不是本 Skill）：
让"我刚刚花 30 分钟才找出来的根因"变成"未来任何人/Agent 5 秒就能避开的指南"。这是 Compounding Engineering 最具体的实现——一次踩坑、永久免疫。
| 坑的性质 | 写到哪 |
|---|---|
| 通用 / 跨领域 | .qoder/business-logic/gotchas.md（不存在就新建） |
| 评分 / 题型相关 | 追加到 grading-pipeline.md 或 question-types.md 的 "Known Gotchas" 段 |
| 鉴权相关 | 追加到 admin-auth.md |
每条 gotcha 必须有这 4 段，缺一不可：
## <一句话标题，描述现象>
### 现象
（观察到了什么——可粘贴 / 复现的报错、行为）
### 根因
（为什么会这样——技术 / 业务 / 配置上的解释）
### 正确做法
（以后遇到类似情况该怎么做——可粘贴的代码 / 命令 / 步骤）
### 反例（可选但强烈推荐）
（曾经被尝试但行不通的做法 + 为什么行不通）
正确做法里如果涉及代码，精确到文件:行号：
### 正确做法
用 `lib/grading.ts:438` 的 `regradeFailedQuestions` 而不是自己重新评分。
不要写"参考 grading.ts 里的某个函数"——一是不可点，二是函数名漂移后引用失效。
每条末尾加：
> 沉淀于 2026-05-12，来自 #task-2 实施过程；下次 review 时间 2026-08-12
3 个月后未被触发 / 复读的 gotcha 可考虑删除（避免积累成噪音池）。
/update-context 的"待整理"将以下内容追加到 `.qoder/business-logic/gotchas.md`（位置：文档末尾，或某个相关章节后）：
---
## payment_succeeded webhook 可能重复发送
### 现象
线上发现少数订单的 `total_paid` 字段是预期值的 2-3 倍。检查日志发现，
同一个 `payment_id` 收到了多次 `payment_succeeded` webhook。
### 根因
第三方支付平台的 retry 机制——我们处理慢（> 5s）或返回非 2xx 时，对方会
按指数退避重试。这是 webhook 的标准行为，不是 bug。
### 正确做法
所有 webhook 入口必须基于 `event.id` 做幂等：
```ts
// lib/webhook/idempotency.ts:42
if (await isProcessed(event.id)) return ack();
用 order 当前状态作为幂等依据是错的——状态可能因为并发请求已经变化。
沉淀于 2026-05-12，来自 task-2 实施过程；下次 review 时间 2026-08-12
## 与其他 Skill 的关系
- 通常由 [`/hunt`](../hunt/SKILL.md) 找到根因后**立即**触发
- 范围比 [`/update-context`](../update-context/SKILL.md) 窄——后者还能写决策 / 模块说明 / 进度
- 沉淀好后的 gotcha 会被 [`/think`](../think/SKILL.md) 在"影响范围分析"阶段自动读到
- 任务结束的总结（[`/summary`](../summary/SKILL.md)）可以引用本次 record 的 gotcha