القائمة
把本次踩到的坑写进 .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
扮演方案的"反对方"，挑刺、找隐藏问题、戳过度自信的假设。/think 给出 plan 后强烈建议立刻跑一次 /challenge——让方案在落地前先经过一轮自我对抗。
session 结束时总结本次做了什么 / 没做完什么 / 关键决策 / 下一步从哪继续。用于写 commit body、更新 spec progress.md、交接给下一个 session。每个有产出的 session 结束前都该跑一次。
任务完成后的 diff 审查。完成代码改动后必须执行：看 git diff、对照原始目标、跑验证命令、输出审查报告。不允许"看起来 OK"就宣称完成。
