update-context

name	update-context
description	任务结束后沉淀团队记忆。把本次发现的边界 case、踩坑、隐性约束、有效技巧写入 .qoder/business-logic/gotchas.md（或更新对应业务文档），让下次会话不再踩同一个坑。

/update-context · 沉淀本次发现到团队记忆

使用场景

任务完成后（/check 通过之后）必须执行。即便任务很简单，也要快速 review 一下"这次有没有学到值得沉淀的东西"——5 秒确认无 → 跳过。

目标

把"本次 session 里发现的事"从临时聊天历史转化成仓库里的长期资产。这是 Compounding Engineering 的最小实践——同一个坑不应该被踩两次。

不沉淀的发现 = 浪费的注意力。下一次会话不会知道这次踩了什么坑。

必须步骤

1. 自问：本次有什么值得沉淀？

走一遍下面的 checklist：

• 隐性约束：发现某个字段 / 函数 / 配置必须以特定方式使用，但代码读不出？
• 踩坑：自己（Agent / 用户）踩了一个坑，未来其他人 / 其他 Agent 会同样踩？
• 业务规则：发现一条文档里没写的业务规则（"X 状态下不能调 Y"）？
• 有效模式：找到一种解决某类问题的好方法（"遇到 X 类问题用 Y 工具"）？
• API / 命令的非显然用法：某个命令 / API 必须特定顺序调用 / 特定参数组合？

任一答 yes → 进入下一步。全 no → 跳过本 Skill。

2. 决定写到哪

类型	目标文件
通用踩坑（不属于某个业务域）	.qoder/business-logic/gotchas.md（不存在就建）
评分 / 题型相关	更新 .qoder/business-logic/grading-pipeline.md 或 question-types.md
鉴权相关	更新 .qoder/business-logic/admin-auth.md
Rule 级别的发现（要约束 Agent 行为）	提议加新 Rule 到 .qoder/rules/
工作流 / 流程级（不只是知识）	更新对应 Skill 的 SKILL.md

3. 写入条目

每条沉淀至少包含：

• 现象：你观察到了什么
• 根因 / 规则：为什么是这样
• 正确做法：以后遇到类似问题应该怎么做
• 代码位置引用（如果适用）：lib/xxx.ts:42

例：

## payment_succeeded 事件可能重复发送

**现象**：同一个支付订单可能收到多次 payment_succeeded webhook。

**根因**：第三方支付平台的 retry 机制——如果我们处理慢或返回非 2xx，对方会重试。

**正确做法**：所有 webhook 处理必须基于 `event.id` 幂等。见 `lib/webhook/idempotency.ts:42`。

**反例**：用 order 当前状态作为幂等依据是错的——状态可能因为并发更新已经变化。

4. 更新 Spec 的 progress.md

如果当前任务有对应的 specs/2026-xx-task-N/progress.md，把本次完成 + 沉淀的内容记进去。下次 session 恢复时这就是入口。

5. （可选）建议升级到 Rule

如果发现"这种坑应该用 Rule 约束 Agent 行为"——比如"以后看到 X 就必须做 Y"——提议给用户加一条 Rule，不要默默加。

禁止事项

• ❌ 不允许把"本次具体调试过程"写进 business-logic——那是日志，不是知识
• ❌ 不允许写"未来可能有用"的猜测——只写实际验证过的发现
• ❌ 不允许在 gotchas 里堆 100 条琐碎条目——优先 dedup、合并、删过期
• ❌ 不允许把个人偏好（"我喜欢这样写"）写成团队规则

输出格式

## 本次沉淀

写入 `.qoder/business-logic/grading-pipeline.md`（追加段落）：

> ### 重评失败题的失败识别口径
> 必须用 `feedback?.includes("评分失败")` 而非 `score === 0`，
> 因为客观题答错 / 主观未作答都是 0 分但不是"评分失败"...

## 已更新文件
- `.qoder/business-logic/grading-pipeline.md`（+12 行）
- `specs/2026-05-task-2-regrade/progress.md`（更新到 "Task 2 完成"）

## 未沉淀（已判断不必）
- "Tailwind v4 的 token 用法" → 这是公开知识，不是项目特有

与其他 Skill 的关系

• 通常在 /check 通过后跑
• 沉淀出来的内容下次会被 /think 读到（影响范围分析时）
• /hunt 找到根因 → 用 /update-context 记下防止再踩