# Record Bug Fix Memory

> 当用户要求在 bug 已经定位并修复后，记录排错经验、事故结论、AI 记忆更新、 复盘摘要或本地 MCP 记忆时使用。这个技能只负责沉淀 "发生了什么、为什么会发生、如何修好、以后要记住什么"， 不要把它用于实际修复 bug。

- Skill: `ruan-cat/record-bug-fix-memory-5` (Agent Skill, multi-file: 36 files)
- Install (CLI): `npx get-skill add ruan-cat/record-bug-fix-memory-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruan-cat/record-bug-fix-memory-5/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ruan-cat (https://skillmd.com/u/ruan-cat)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ruan-cat/record-bug-fix-memory-5

---


# 记录 Bug 修复记忆

## 1. 概述

使用这个技能，把已经完成的排错结果沉淀成可复用的长期记忆。

目标是保存根因、有效修复路径、错误假设和验证证据，让后续 agent 不再重复同样的弯路。

核心原则：记录决策链，不记录流水账。

## 2. 存储架构

本技能采用**双层存储架构**：

- **SKILL.md**：只放流程指导 + 案例摘要索引（保持精简，不超过 150 行流程指导）
- **独立案例文件**：每条详细事故记录写成独立的 `YYYY-MM-DD-{slug}.md` 文件，与 SKILL.md 同目录

**禁止**将完整事故记录正文内嵌到 SKILL.md 中。SKILL.md 中只保留摘要索引。

### 2.1. 目录结构

```plain
.agents/skills/fix-bug/record-bug-fix-memory/
├── SKILL.md                              # 流程指导 + 摘要索引
├── 2026-03-28-unocss-color-safelist.md   # 详细案例
├── 2026-03-29-nitro-dual-runtime.md      # 详细案例
└── ...                                   # 更多案例文件
```

### 2.2. 案例文件命名规范

- 格式：`YYYY-MM-DD-{slug}.md`
- slug 使用小写英文 + 短横杠，简明描述事故主题
- 示例：`2026-03-28-unocss-config-driven-color-safelist.md`

### 2.3. 案例文件必填结构

```markdown
# YYYY-MM-DD {事故简述}

## 1. 问题现象

{从用户视角看，哪里坏了}

## 2. 实际根因

{真正出错的地方}

## 3. 关键误导点

{哪个错误假设或误导信号浪费了时间}

## 4. 有效修复

{真正解决问题的改动}

## 5. 验证方式

{证明修复成功的证据}

## 6. 后续约束

{未来 agent 必须先检查什么、避免什么}
```

### 2.4. 摘要索引格式（写在 SKILL.md 的"案例索引"章节中）

```markdown
### {事故简述}（YYYY-MM-DD）

- 详细案例：`YYYY-MM-DD-{slug}.md`
- 适用场景：{一句话描述触发条件}
- 关键约束：{一句话核心教训}
```

## 3. 何时使用

在以下场景使用这个技能：

- 用户要求更新 AI 记忆文档、记录经验教训、补充事故记录、编写复盘摘要。
- bug 已经完成复现，且有效修复路径已经明确。
- 这条经验是仓库特有知识，应该对未来 agent 可见。
- 需要把结论同步到本地 MCP 记忆，例如 Memorix。

以下情况不要使用这个技能：

- bug 还在调查中，根因没有确认。
- 用户要求的是修复实现，而不是经验沉淀。
- 你手里只有猜测、片段证据或临时绕过方案。

## 4. 前置输入

开始写记忆前，必须能回答下面六个问题：

1. 对用户来说，表面现象是什么？
2. 实际根因是什么？
3. 哪个错误假设或误导信号浪费了时间？
4. 最终是哪一个具体改动修好了问题？
5. 用什么验证证明修复成立？
6. 这条记忆应该写到哪里？

如果有任何一个问题答不上来，先完成排错，不要提前写记忆。

## 5. 写到哪里

- **详细案例**：写到本技能目录下的独立 md 文件（默认落点）
- **摘要索引**：同步更新 SKILL.md 的"案例索引"章节
- **跨会话的本地记忆**：写到 Memorix，类型用 `gotcha`、`decision` 或 `problem-solution`
- **仓库级规则**：只有当经验会影响整个仓库的未来 agent 时，才同步写入根级 `CLAUDE.md`、`AGENTS.md`、`GEMINI.md`

## 6. 记录流程

1. 先确认 bug 已经理解清楚并且修复完成。
2. 把结果压缩成 4 到 6 条高信号事实。
3. 创建独立案例文件 `YYYY-MM-DD-{slug}.md`，按必填结构写入详细内容。
4. 在 SKILL.md 的"案例索引"章节追加一条摘要索引。
5. 如果经验影响整个仓库，同步更新根级 AI 记忆文档。
6. 用同样的结论更新 Memorix，并选对记忆类型。
   - 如果当前会话没有实际暴露 Memorix MCP 工具，就必须明确告诉用户"本会话无法写入 Memorix"，不能因为仓库文档声明"可用"就假定真的已经拿到工具。
7. 回读一遍文本，删掉瞬时噪音、猜测和低价值命令历史。
8. 如果用户还要求提交 commit，把提交动作交给单独的 git 工作流处理。

## 7. 写入经验时必须保留的额外信息

如果这次 bug 与仓库已有事故模式相似，写记忆时不要遗漏下面这些额外信息：

- 这次问题是否打破了某个"用户已确认稳定"的基线
- 是否存在"不要乱改"的配置
- 首个可信信号来自哪里，是终端日志、浏览器 console、网络请求，还是构建输出
- 这次修复属于哪一类：依赖实例统一、废弃 API 清理、导入路径修正、类型断言补齐、构建配置兜底、依赖入口兼容、模板层覆盖、样式层补齐、还是启动前置准备
- 这次是否存在误导性很强的假象
- 最终验证是否基于 fresh 进程、fresh 日志和 fresh 页面，而不是历史缓存

## 8. 验证证据写法

未来写事故记录时，优先记录可重复验证的证据，而不是模糊措辞。

- 好的写法：`pnpm exec tsc --noEmit 输出中相关错误为 0`
- 好的写法：`fresh dev.stderr 为空`
- 好的写法：`修复文件均无类型错误输出`
- 好的写法：`pnpm install 后依赖版本一致，peer dependency 无冲突`
- 不好的写法：`应该没问题了`
- 不好的写法：`看起来像是好了`

## 9. 不要写成什么

把根级 AI 记忆经验吸收到技能里，不等于把技能写成修复手册。下面这些内容不应该成为这个技能的主体：

- 大段命令执行流水
- 与当前仓库无关的泛化 debug 理论
- 逐条罗列所有试错过程
- 把某一次临时绕过方案包装成永久规则
- 用"必须执行这些命令"代替"应该记录哪些结论"

## 10. 好记忆的特征

- 解释清楚"为什么会坏"，而不是只写跑了什么命令
- 明确指出第一条可信线索，说明它如何打破错误假设
- 用可复用的方式描述最终修复
- 写出未来 agent 可以重复执行的验证动作
- 让下一次排错明显更短

## 11. 常见错误

- 根因还没确认，就开始写猜测性结论
- 写成很长的 debug 日记，而不是可复用结论
- 仓库级经验写到了错误的位置
- 没把导致绕路的错误假设写出来
- 把修复说明和记忆沉淀混在一起
- 忘了同步本地 MCP 记忆
- 只因为仓库记忆文件声明"有 Memorix"，就跳过当前会话工具可用性核对
- **把完整事故记录正文写进 SKILL.md 而不是独立案例文件**

## 12. 边界

这个技能只负责记忆沉淀和总结。

它不能替代调试、实现、测试和修复工作流。如果 bug 还没修好，先使用合适的调试或实现技能，等结果稳定后再回到这个技能做经验沉淀。

## 13. 案例索引

> 历史记录已从旧版 SKILL.md 拆分为独立案例文件；同目录的 `2026-09-01-legacy-cases-source.md` 仅作为迁移审计原文，不作为新案例写入入口。

### vite@8 构建产物缺少文件名兜底（2026-09-01）

- 详细案例：`2026-09-01-vite8-build-fallback.md`
- 适用场景：Vite/Rollup CSS 产物处理时报 `path` 类型错误。
- 关键约束：先检查 `assetFileNames` 的空值回退，不要先降级工具链。

### Nuxt 文档站启动前置缺失（2026-09-01）

- 详细案例：`2026-09-01-nuxt-dev-startup.md`
- 适用场景：开发态缺少 `.nuxt`、组件库样式产物或 `#app-manifest`。
- 关键约束：`dev/build` 必须准备 Nuxt 产物，文档站应能直接消费 workspace 源码。

### Nuxt 客户端 hydration 被依赖入口打断（2026-09-01）

- 详细案例：`2026-09-01-nuxt-client-hydration.md`
- 适用场景：暗黑模式、侧栏等交互失效且 Chrome console 出现 ESM/CJS 导入错误。
- 关键约束：先查 console 与依赖入口，再处理样式。

### Nuxt 文档站稳定启动基线（2026-09-01）

- 详细案例：`2026-09-01-nuxt-stable-startup-baseline.md`
- 适用场景：已验证可运行的文档站又被后续配置修改破坏。
- 关键约束：把用户确认的最小配置当作基线，禁止扩散式改动。

### 单语文档站误用多语言运行路径（2026-09-01）

- 详细案例：`2026-09-01-nuxt-single-language-i18n.md`
- 适用场景：单语站点出现 locale 路径或 i18n 模板继承导致的 500。
- 关键约束：记录并区分 compat 覆盖与显式单语配置，不把历史修法混为一谈。

### simple-git-hooks 写入假 `.git` 目录（2026-09-01）

- 详细案例：`2026-09-01-simple-git-hooks-fake-git.md`
- 适用场景：提交时 lint-staged 与 commitlint 从未触发。
- 关键约束：核对真实 `git-dir`、`core.hooksPath` 与钩子实际落点。

### Prettier 破坏 Nuxt MDC 图标 props（2026-09-01）

- 详细案例：`2026-09-01-nuxt-mdc-prettier-icons.md`
- 适用场景：MDC `::card` 的 YAML props 被当成纯文本渲染。
- 关键约束：Nuxt Content Markdown 必须被 `.prettierignore` 与 `requirePragma` 双重保护。

### `::demo-playground` MDC 容器语法错误（2026-03）

- 详细案例：`2026-03-01-demo-playground-mdc.md`
- 适用场景：页面出现容器标记、`title:` 或 `#preview` 裸文本与 hydration mismatch。
- 关键约束：严格保持 `::demo-playground`、frontmatter 与 `::` 闭合顺序。

### Nuxt SSR i18n 多版本依赖冲突（2026-09-01）

- 详细案例：`2026-09-01-nuxt-ssr-i18n-version-conflict.md`
- 适用场景：`registerMessageResolver` 等 SSR 运行时函数缺失。
- 关键约束：先用 `pnpm why` 找多版本，再用 workspace overrides 统一版本。

### Cursor 锁定原生 `.node` 导致 pnpm install 失败（2026-09-01）

- 详细案例：`2026-09-01-cursor-node-lock-pnpm.md`
- 适用场景：更新 Oxc、esbuild、SWC 等原生依赖时出现 `EPERM unlink`。
- 关键约束：改用 Cursor 外部终端执行安装并复核锁文件。

### `.gitattributes` 的 CRLF/LF 幽灵差异（2026-03）

- 详细案例：`2026-03-01-gitattributes-eol-ghost-diff.md`
- 适用场景：切换分支后文本文件持续显示已修改但无实质 diff。
- 关键约束：优先核对行尾与 `git add --renormalize`，并保持提交信息符合规范。

### Nuxt dev warning 清理基线（2026-09-01）

- 详细案例：`2026-09-01-nuxt-dev-warning-cleanup.md`
- 适用场景：页面可打开但 fresh dev 仍有 i18n、OG Image、Icon、Sass 警告。
- 关键约束：只以 fresh 进程日志、HTTP 状态和 Chrome console 作为证据。

### Windows Nitro trace 构建假卡死（2026-03）

- 详细案例：`2026-03-01-windows-nitro-trace-build-stall.md`
- 适用场景：PowerShell 构建停在 Nitro 收尾且旧子进程叠加。
- 关键约束：先清理进程再判断卡点；本地绕行不能直接推导 Vercel 生产策略。

### Vercel `entities/decode` 云函数崩溃（2026-04）

- 详细案例：`2026-04-01-vercel-entities-decode.md`
- 适用场景：Vercel 返回 `FUNCTION_INVOCATION_FAILED` 与 `entities/decode` 缺失。
- 关键约束：统一 `entities` 版本、恢复默认 trace，并以实际 Vercel URL 验证。

### Vercel `@vueuse/core` 外部化缺失（2026-04）

- 详细案例：`2026-04-01-vercel-vueuse-core-missing.md`
- 适用场景：workspace 包经 Element Plus 链路在云函数中找不到 `@vueuse/core`。
- 关键约束：SSR 优先检查 `vite.ssr.noExternal` 及完整运行时依赖树。

### Nuxt Content 生产环境连锁故障总复盘（2026-04）

- 详细案例：`2026-04-01-nuxt-content-vercel-cascade.md`
- 适用场景：Windows 本地构建补丁在 Vercel Linux 触发依赖与预渲染连锁故障。
- 关键约束：本地 build 不能替代生产验证，禁止无条件 `trace: false`、`inline: [/.*/]` 与清空预渲染路由。

### PowerShell Git 批量合并误报（2026-03）

- 详细案例：`2026-03-01-powershell-git-batch-merge.md`
- 适用场景：合并成功却被 stderr 管道误判为失败，随后错误执行 `merge --abort`。
- 关键约束：不要用 `2>&1 |` 包裹 git merge/push，直接检查 `$LASTEXITCODE` 与 `MERGE_HEAD`。

### CuiDialog 遮罩被堆叠上下文困住（2026-04）

- 详细案例：`2026-04-01-cuidialog-overlay-stacking.md`
- 适用场景：Dialog 显示但遮罩不覆盖页面，CSS 属性看似正常。
- 关键约束：先检查 overlay 是否挂到 `body`，并在隔离堆叠上下文中显式开启 Teleport。

## 14. 本仓库落点覆盖

- 本仓库的 bug 经验优先记录在当前技能目录：`.agents/skills/fix-bug/record-bug-fix-memory/*.md`
- 根级 `CLAUDE.md`、`AGENTS.md`、`GEMINI.md` 只在用户明确要求同步 AI 记忆文档时才更新

