# Issue Tracker

> 用于在开发过程中记录内部问题单，结构化沉淀 bug 的现象、根因、排查过程、修复方法、验证方式和经验总结，方便下次遇到类似问题能快速复现、定位、排查与修复。

- Skill: `jiangyinzuo/issue-tracker` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jiangyinzuo/issue-tracker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiangyinzuo/issue-tracker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jiangyinzuo (https://skillmd.com/u/jiangyinzuo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jiangyinzuo/issue-tracker

---


# Issue Tracker

## 目标

当你在软件开发过程中遇到、排查、定位或修复一个 bug / issue，并希望把这次调试与修复过程沉淀为一条高质量的内部 issue 记录时，使用本技能。

本技能的目标不是写一段泛泛的“工作日志”，而是沉淀一份可复用的工程记录，方便日后碰到类似问题时快速解决。

- 问题表现是什么
- 问题在什么条件下触发
- 如何定位/排查问题？排查过程是怎样推进的。
- 真实根因是什么
- 修改了哪些代码来修复问题
- 为什么这些修改能修复问题
- 如何验证修复有效，补充了哪些测试用例
- 这次问题对后续开发有什么可复用的启发

NOTE: 请保存为本地markdown文件。

## 何时使用

当满足以下任一情况时，应使用本技能：

- 一个 bug 已经被定位并修复
- 一个 bug 已经被定位，但只完成了部分修复
- 根因已经找到，但最终 patch 尚未完全完成
- 一次调试过程虽然没有完全修复问题，但得出了重要结论，值得沉淀
- 一次代码修改修复了逻辑错误、边界条件错误、状态更新错误、同步错误、内存使用错误、接口使用错误或性能问题
- 某个问题具有复发可能，后续很可能再次遇到
- 某个问题虽然已经修好，但根因不直观、排查过程较长，未来有较高参考价值

特别适合记录以下类型的问题：

- 逻辑 bug
- 状态机 / 状态转移 bug
- 并发 / 同步 bug
- 内存生命周期 / 所有权 bug
- 越界 / off-by-one / 边界条件 bug
- 空指针 / 非法状态 bug
- 跨模块集成 bug
- 根因明确、修复可解释的性能 bug
- 偶发 / 非确定性 / flaky 问题
- 症状与根因距离较远的问题

以下情况一般不需要使用本技能：

- 单纯 typo 修复，且没有调试价值
- 纯格式化修改
- 纯重命名修改
- 纯样式 / 注释修改
- 没有问题定位过程、没有工程复用价值的极小改动

## 核心原则

一条高质量的 issue 记录，不是 patch 摘要，而是完整解释下面这条链路：

**现象 -> 触发条件 -> 排查过程 -> 根因 -> 修复方案 -> 验证方式 -> 可复用经验**

如果缺少其中的关键环节，后续读者就很难真正复用这条记录。

## 必须遵守的行为要求

使用本技能时，必须输出一份**结构化**的问题记录。

不能只写：

- 修了某个 bug
- 修改了某几个文件
- 测试通过了

必须明确区分以下几个部分：

- **观察到的现象**
- **怀疑过的原因**
- **最终确认的根因**
- **采用过的调试方法**
- **实际采用的修复方法**
- **修复有效的验证证据**

要尽量具体，优先使用真实的工程信息，而不是空泛描述，例如：

- 文件名 / 函数名 / 类名 / 数据结构名 / 状态名
- 分支条件 / 变量 / 标志位
- 调用链
- 复现条件
- 为了观察bug临时插入的代码片段（如print、临时设置变量、辅助调试函数等等）
    - NOTE: 如果有临时的调试代码，请将代码片段附到markdown报告，或者单独保存到一个脚本文件中。
- 调试方法（如gdb调试过程、打日志过程）
- 日志 / 断言 / 栈信息 / 性能指标
- 补充的测试用例 NOTE：请写出测试用例名。

## 输出风格要求

整体风格应保持：

- 技术化
- 工程化
- 具体
- 可复用
- 不夸大
- 不虚构

具体要求如下：

- 用事实驱动描述，不要空泛抒情
- 明确区分“已确认事实”和“推测 / 判断”
- 如果根因尚未完全证明，要显式说明不确定性
- 不要为了写得完整而编造信息
- 即使读者没有参与本次调试，也应能理解问题的来龙去脉

如果某项信息当前缺失，应明确写“未知”或“未验证”，不要自行补全。

## 工作流程

当调用本技能时，按如下流程组织输出。

### 1. 明确 issue 边界

先判断：

- 这次要记录的到底是哪一个问题
- 它属于哪个模块 / 子系统 / 功能区域
- 这是一个问题，还是多个彼此独立的问题

如果一次调试中发现了多个互不相关的 bug，应拆成多条 issue 记录；  
只有在它们确实属于同一条因果链时，才合并记录。

### 2. 收集具体技术事实

尽量收集以下信息：

- 涉及的文件
- 涉及的函数 / 方法 / 类
- 涉及的数据结构
- 关键变量 / 标志位 / 状态
- 触发输入 / 测试场景 / 运行环境
- 调试方法（gdb、临时插入print代码、临时插入变量赋值代码）
- 错误日志 / 断言 / 崩溃栈 / 错误结果
- 关键 trace / profile / 指标
- 修复前后的行为差异

### 3. 还原排查过程

要把调试过程写出来，而不是只写最终答案。

重点包括：

- 问题最初是怎么暴露出来的
- 一开始怀疑过哪些方向
- 哪些假设后来被排除了
- 哪些证据缩小了排查范围
- 是什么关键观察最终指向真实根因

不要把一个曲折的排查过程硬写成“线性、一击即中”的故事。如果某些走弯路的过程对未来有参考价值，可以保留。

### 4. 说明根因

根因部分要回答清楚：

- 到底是哪段代码错了
- 错在什么假设 / 不变量 / 状态约束上
- 为什么这个错误会导致观察到的现象
- 为什么它只会在这些特定条件下触发
- 为什么之前不容易被发现

### 5. 说明修复方法

修复部分要解释：

- 改了什么
- 在哪里改的
- 为什么要这么改
- 该修改是局部修正还是会影响更大范围的行为
- 是否考虑过其他修复方案

不要只是列 diff 涉及的文件名。重点是解释修复逻辑。

### 6. 说明验证方式

验证部分要回答：

- 如何证明问题被修复了
- 是通过单测、集成测试、回归测试、复现脚本、人工验证、benchmark、日志对比，还是代码推理确认的
- 验证的是“原始现象消失了”，还是“根因路径被堵住了”，还是两者都验证了

“可以编译通过”通常不构成有效验证，除非本问题本身就是编译错误。

### 7. 提炼可复用经验

最后要总结：

- 这类问题的共性模式是什么
- 下次如何更早发现
- 是否应该补断言 / 补测试 / 补文档 / 补监控
- 是否暴露出更大的设计脆弱性
- 后续代码审查时应重点关注什么

## 重要规则

### 规则 1：不要编造证据
如果没有运行测试，就不要写“测试通过验证”。
如果根因只是推测，不要写成已经确认。

### 规则 2：不要把现象当根因
例如：
- “程序因为空指针崩溃了”

这通常只是表层现象。  
还要继续解释：为什么这里会出现空指针？是哪条状态路径让它变得可能？

### 规则 3：不要只总结最终 diff
后续读者需要的不只是 patch 本身，更是这次调试的思考路径。

### 规则 4：优先使用工程上的具体标识
尽量写真实的：
- 文件名
- 函数名
- 类名
- 结构体字段
- 状态名
- 分支条件
- 标志位
- 调用链

### 规则 5：有价值的“排除过程”可以保留
如果某个错误方向被排除的过程具有启发意义，可以简要保留。  
但不要把无意义的试错全部堆进去。

### 规则 6：验证方式必须和问题类型匹配
例如：
- 对逻辑 bug，仅仅“编译通过”不算验证
- 对性能问题，仅仅“结果正确”不算充分验证
- 对并发 bug，仅仅“这次没复现”通常也不算强验证

### 规则 7：明确区分事实与判断
必要时使用如下措辞：
- **观察到**
- **已确认**
- **推测**
- **大概率**
- **尚未验证**

## 简略与详细的把握

如果问题很简单，可以简洁一些。如果问题根因隐蔽、排查很深、后续复用价值高，就应该写得更详细。
不要机械把每个章节都写很长；但也不要为了简短而省略关键推理链条。

## 特殊类型问题的补充要求

### 性能问题
除标准模板外，还应补充：

- 性能异常表现
- workload / benchmark 场景
- 修复前后关键指标对比
- 问题来自算法复杂度、锁竞争、内存分配、缓存局部性、IO 路径、向量化失效还是其他原因
- 该修改是否影响正确性还是只影响性能

### 并发 / 同步问题
除标准模板外，还应补充：

- 涉及的线程 / 协程 / actor
- 共享状态
- 时序窗口
- 锁 / 原子 / 内存序行为
- 为什么问题是偶发的
- 为什么这个竞态路径原先容易被忽视

### 内存问题
除标准模板外，还应补充：

- 所有权 / 生命周期模型
- 分配点与释放点
- 是泄漏、越界、悬空、重复释放还是 use-after-free
- 为什么错误生命周期会变成可达路径

### 状态机 / 协议问题
除标准模板外，还应补充：

- 涉及的状态
- 合法状态转移规则
- 实际发生了哪条非法转移
- 缺少了哪个 guard / rollback / 更新动作 / 同步动作

### 部分修复 / 仅缓解
如果只是缓解或部分修复，必须明确写清：

- 当前解决了什么
- 还没解决什么
- 哪些风险依然存在
- 为什么当前不能称为彻底修复