# Bug Debug Log

> Bug 调试记录技能：将调试过程标准化写入 docs/test_book.md，包含问题发现、描述、根因分析、解决方案、效果、知识点与面试问答。触发词：总结这次调试, 总结这个bug, 记录bug, 记录调试, debug log, 写入test_book, 调试记录, log this bug, summarize debug

- Skill: `piaoxuemoli/bug-debug-log-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add piaoxuemoli/bug-debug-log-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/piaoxuemoli/bug-debug-log-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: MIT
- Author: piaoxuemoli (https://skillmd.com/u/piaoxuemoli)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/piaoxuemoli/bug-debug-log-2

---


# Bug Debug Log Skill

将每次调试过程标准化记录到 `docs/test_book.md`，形成面向面试展示的技术调试档案。

**触发词**（任意匹配即激活）：`总结这次调试` / `总结这个bug` / `记录bug` / `记录调试` / `debug log` / `写入test_book` / `调试记录` / `log this bug` / `summarize debug`

---

## Step 1: 信息收集

从当前对话上下文中提取以下字段。**若某字段上下文中已明确，直接使用，不要重复询问**。若关键字段缺失，使用 `ask_questions` 工具补充：

| 字段 | 说明 | 是否必须询问 |
|------|------|-------------|
| bug 标题 | 一句话描述问题 | 若上下文不明确则询问 |
| 严重程度 | 高 / 中 / 低 | **必须询问**（用户最了解影响范围） |
| 发现方式 | 如何触发/复现的 | 若上下文无则询问 |
| 是否已完全修复 | 是 / 部分 / 否 | 若上下文不明确则询问 |

询问格式（使用 ask_questions 工具）：

```
严重程度（此 bug 对用户的影响范围）？
  - 高：核心功能不可用
  - 中：功能受损但有绕过方式
  - 低：视觉/体验问题，不影响功能

修复状态？
  - 已完全修复
  - 部分修复（仍有遗留问题）
  - 尚未修复（仅记录分析）
```

---

## Step 2: 确定记录编号

1. 使用 Read 工具读取 `docs/test_book.md`
   - 若文件不存在（报错或空），记录编号为 `001`，标记需要创建文件头
   - 若文件存在，统计其中 `## BUG-` 出现的次数，新编号 = 次数 + 1，格式化为三位数（如 `002`, `010`）

---

## Step 3: 生成知识点与面试题

根据 bug 涉及的技术领域，自动生成内容。**必须覆盖实际 bug 相关的知识域**，不得生成与 bug 无关的内容。

**技术领域映射参考**（根据实际情况选择 2-4 个）：

| 关键词 | 对应知识域 |
|--------|-----------|
| useState / 组件卸载 / 重挂载 | React 组件生命周期与本地状态 |
| useEffect / 依赖数组 / 闭包 | React Hooks 闭包与副作用 |
| Zustand / persist / store | 全局状态管理与持久化策略 |
| navigate / router / 路由跳转 | React Router 路由机制 |
| IPC / preload / contextBridge | Electron 进程间通信安全模型 |
| Worker / postMessage | Web Worker 与主线程通信 |
| TypeScript / 类型守卫 / unknown | TypeScript 类型系统 |
| async/await / Promise / 竞态 | 异步编程与竞态条件 |
| useCallback / useMemo / 依赖 | React 性能优化 |

**面试题生成要求**：
- 2-3 道题，从**概念原理**和**实战场景**两个维度出发
- 答案要简洁但完整，面向高级前端/全栈岗位
- 至少 1 道题直接与本次 bug 场景强相关（如"组件重新挂载时如何保留数据？"）

---

## Step 4: 写入 docs/test_book.md

### 4.1 若文件不存在，先写入文件头：

```markdown
# ImmerseAI Bug 调试记录

> 技术栈：React + TypeScript + Electron | 项目：ImmerseAI
> 本文档记录开发过程中遇到的 bug，包含根因分析、解决方案与面向面试的知识总结。

---
```

### 4.2 Append 新记录（严格按以下模板，不得省略任何章节）：

```markdown
## BUG-{编号}: {标题}

**日期**: {YYYY-MM-DD} | **技术栈**: {涉及技术，如 React / Zustand / Electron} | **严重程度**: {高/中/低} | **状态**: {已修复/部分修复/记录中}

### 问题发现

{描述怎么触发的，具体操作步骤，如："打开书籍后点击返回按钮，书架页面显示空白"}

### 问题描述

{表象是什么，用户视角的感知，不涉及代码}

### 根因分析

{技术层面的根本原因，层层递进说明，可包含代码片段}

```{相关代码片段（可选，选取最能说明问题的部分）}
```

### 解决方案

**修改文件**: `{文件路径}`

{说明改了什么，为什么这样改}

```diff
- {修改前的关键代码}
+ {修改后的关键代码}
```

### 解决效果

{修复后的表现；若有遗留问题也在此说明}

---

### 涉及知识点

**{知识点标题}**
{2-4 句话解释核心概念，要能独立成文，面向不熟悉此概念的读者}

**{知识点标题}**
{同上}

（共 2-4 个知识点）

---

### 面试问答

**Q: {问题}**

> {标准答案，3-6 句话，包含关键术语}

**Q: {问题}**

> {标准答案}

（共 2-3 道题）

---
```

### 4.3 写入方式

- 使用 Write 工具时：**先 Read 原文件全部内容，再将原内容 + 新记录合并后整体写入**（因工具不支持原生 append）
- 新记录追加在文件末尾，与上一条记录之间保留一个空行

---

## Step 5: 完成确认

写入完成后，向用户输出：

```
已将 BUG-{编号} 记录写入 docs/test_book.md

记录摘要：
- 标题：{标题}
- 根因：{一句话}
- 知识点：{知识点标题列表}
- 面试题：{题目列表}

可通过 `git diff docs/test_book.md` 确认写入内容。
```

---

## Guardrails

- **NEVER 覆盖历史记录** — 始终 append，不得删除或修改已有的 BUG-* 条目
- **NEVER 省略模板章节** — 即使信息不完整，也要保留章节标题并注明"待补充"
- **ALWAYS 生成知识点和面试题** — 这是本 Skill 的核心价值，不得跳过
- **知识点必须与 bug 相关** — 不得生成套话，每个知识点都要能解释"为什么会有这个 bug"
- **日期取当天** — 使用系统当前日期，格式 YYYY-MM-DD