jiangyinzuo 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 / 更新动作 / 同步动作
部分修复 / 仅缓解
如果只是缓解或部分修复，必须明确写清：
- 当前解决了什么
- 还没解决什么
- 哪些风险依然存在
- 为什么当前不能称为彻底修复