| name | record-bug-fix-memory |
| description | 当用户要求在 bug 已经定位并修复后，记录排错经验、事故结论、AI 记忆更新、复盘摘要或本地 MCP 记忆时使用。这个技能只负责沉淀"发生了什么、为什么会发生、如何修好、以后要记住什么"，不要把它用于实际修复 bug。 |
| metadata | {"template-version":"2.0.0"} |
记录 Bug 修复记忆
1. 概述
使用这个技能，把已经完成的排错结果沉淀成可复用的长期记忆。
目标是保存根因、有效修复路径、错误假设和验证证据，让后续 agent 不再重复同样的弯路。
核心原则：记录决策链，不记录流水账。
2. 存储架构
本技能采用双层存储架构：
- SKILL.md：只放流程指导 + 案例摘要索引（保持精简，不超过 150 行流程指导）
- 独立案例文件：每条详细事故记录写成独立的
YYYY-MM-DD-{slug}.md 文件，与 SKILL.md 同目录
禁止将完整事故记录正文内嵌到 SKILL.md 中。SKILL.md 中只保留摘要索引。
2.1. 目录结构
.claude/skills/fix-bug/record-bug-fix-memory/
├── SKILL.md
├── 2026-06-07-vitepress-element-plus-style-conflict.md
└── ...
2.2. 案例文件命名规范
- 格式：
YYYY-MM-DD-{slug}.md
- slug 使用小写英文 + 短横杠，简明描述事故主题
- 示例：
2026-06-07-vitepress-element-plus-style-conflict.md
2.3. 案例文件必填结构
# YYYY-MM-DD {事故简述}
## 1. 问题现象
{从用户视角看，哪里坏了}
## 2. 实际根因
{真正出错的地方}
## 3. 关键误导点
{哪个错误假设或误导信号浪费了时间}
## 4. 有效修复
{真正解决问题的改动}
## 5. 验证方式
{证明修复成功的证据}
## 6. 后续约束
{未来 agent 必须先检查什么、避免什么}
2.4. 摘要索引格式
### {事故简述}（YYYY-MM-DD）
- 详细案例：`YYYY-MM-DD-{slug}.md`
- 适用场景：{一句话描述触发条件}
- 关键约束：{一句话核心教训}
3. 何时使用
在以下场景使用这个技能：
- 用户要求更新 AI 记忆文档、记录经验教训、补充事故记录、编写复盘摘要。
- bug 已经完成复现，且有效修复路径已经明确。
- 这条经验是仓库特有知识，应该对未来 agent 可见。
- 需要把结论同步到本地 MCP 记忆，例如 Memorix。
以下情况不要使用这个技能：
- bug 还在调查中，根因没有确认。
- 用户要求的是修复实现，而不是经验沉淀。
- 你手里只有猜测、片段证据或临时绕过方案。
4. 前置输入
开始写记忆前，必须能回答下面六个问题：
- 对用户来说，表面现象是什么？
- 实际根因是什么？
- 哪个错误假设或误导信号浪费了时间？
- 最终是哪一个具体改动修好了问题？
- 用什么验证证明修复成立？
- 这条记忆应该写到哪里？
如果有任何一个问题答不上来，先完成排错，不要提前写记忆。
5. 写到哪里
- 详细案例：写到本技能目录下的独立 md 文件（默认落点）
- 摘要索引：同步更新 SKILL.md 的"案例索引"章节
- 跨会话的本地记忆：写到 Memorix，类型用
gotcha、decision 或 problem-solution
- 仓库级规则：只有当经验会影响整个仓库的未来 agent 时，才同步写入根级
CLAUDE.md、AGENTS.md、GEMINI.md
6. 记录流程
- 先确认 bug 已经理解清楚并且修复完成。
- 把结果压缩成 4 到 6 条高信号事实。
- 创建独立案例文件
YYYY-MM-DD-{slug}.md，按必填结构写入详细内容。
- 在 SKILL.md 的"案例索引"章节追加一条摘要索引。
- 如果经验影响整个仓库，同步更新根级 AI 记忆文档。
- 用同样的结论更新 Memorix，并选对记忆类型。
- 回读一遍文本，删掉瞬时噪音、猜测和低价值命令历史。
- 如果用户还要求提交 commit，把提交动作交给单独的 git 工作流处理。
7. 验证证据写法
未来写事故记录时，优先记录可重复验证的证据，而不是模糊措辞。
- 好的写法：
pnpm exec tsc --noEmit 输出中相关错误为 0
- 好的写法：
fresh dev.stderr 为空
- 好的写法：
修复文件均无类型错误输出
- 好的写法：
pnpm install 后依赖版本一致，peer dependency 无冲突
- 不好的写法：
应该没问题了
- 不好的写法：
看起来像是好了
8. 不要写成什么
- 大段命令执行流水
- 与当前仓库无关的泛化 debug 理论
- 逐条罗列所有试错过程
- 把某一次临时绕过方案包装成永久规则
- 用"必须执行这些命令"代替"应该记录哪些结论"
- 把完整事故记录正文写进 SKILL.md 而不是独立案例文件
9. 好记忆的特征
- 解释清楚"为什么会坏"，而不是只写跑了什么命令
- 明确指出第一条可信线索，说明它如何打破错误假设
- 用可复用的方式描述最终修复
- 写出未来 agent 可以重复执行的验证动作
- 让下一次排错明显更短
10. 常见错误
- 根因还没确认，就开始写猜测性结论
- 写成很长的 debug 日记，而不是可复用结论
- 仓库级经验写到了错误的位置
- 没把导致绕路的错误假设写出来
- 把修复说明和记忆沉淀混在一起
- 忘了同步本地 MCP 记忆
- 只因为仓库记忆文件声明"有 Memorix"，就跳过当前会话工具可用性核对
11. 边界
这个技能只负责记忆沉淀和总结。
它不能替代调试、实现、测试和修复工作流。如果 bug 还没修好，先使用合适的调试或实现技能，等结果稳定后再回到这个技能做经验沉淀。
12. 案例索引
VitePress 文档站内 Element Plus 组件的样式冲突（2026-06-07）
- 详细案例：
2026-06-07-vitepress-element-plus-style-conflict.md
- 适用场景：在 VitePress markdown 页面中使用 Element Plus 的 ElTable、ElPagination、ElPopover 等组件时出现样式污染。
- 关键约束：优先用
<ClientOnly> + vp-raw + scoped :deep() 重置，teleport 弹层用 popper-class + 非 scoped style。
WorkBuddy 内 memorix MCP 启动失败（2026-06-30）
- 详细案例：
docs/ruan-cat-notes/docs/memorix/2026-06-30-workbuddy-memorix-mcp-failure-report.md
- 适用场景：在 WorkBuddy 中配置 stdio MCP（如 memorix）后，出现
MCP error -32000: Connection closed 且子进程因 Node ABI 不匹配或 NODE_OPTIONS 不兼容而崩溃。
- 关键约束：在
~/.workbuddy/mcp.json 中显式指定兼容的 node.exe 绝对路径，清空不兼容的全局 NODE_OPTIONS；修改配置后若主线程未重新加载，可临时添加不影响 server hash 的字段触发 refreshAndSync。
13. 本仓库落点覆盖
- 本仓库的 bug 经验优先记录在当前技能目录：
.claude/skills/fix-bug/record-bug-fix-memory/*.md
- 根级
CLAUDE.md、AGENTS.md、GEMINI.md 只在用户明确要求同步 AI 记忆文档时才更新
