systematic-debugging

# Systematic Debugging - 系统化调试 ## BenszAPI 任务工作区 本 Skill 的新任务中间文件统一写入 `./.bensz-api/task-{yyyymmdd-hhmm}-{简短描述}/{skill名}/input|output|log/`。同一任务复用一个任务根目录；多 Skill 协作才创建 `shared/`。正式交付物不写入该目录，历史隐藏目录只允许显式兼容读取、迁移或清理。 ## 与 bensz-collect-bugs 的协作约定 - 因本 skill 设计缺陷导致的 bug，先用 `bensz-collect-bugs` 规范记录到 `~/.bensz-skills/bugs/`，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。 - 只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地 `gh` 上传新增 bug 到 `huangwb8/bensz-bugs`；不要 pull / clone 整个仓库。 ## 铁律 ``` NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST ``` **违反规则的信件就是违反规则的精神。** **无例外**： - 不跳过根因调查直接修复 - 不基于猜测进行修复 - 不尝试多个更改同时测试 - 不在不完全理解的情况下修复 --- ## 常见合理化 | 借口 | 现实 | |------|------| | "快速修复现在，稍后调查" | 永不会有"稍后"。技术债���累 | | "尝试改变 X，看是否有效" | 猜测不是调试。可能碰巧修复但未理解 | | "添加多个更改，运行测试" | 无法确定哪个更改有效。浪费调试时间 | | "可能大概差不多是 X" | 模糊理解导致错误修复 | | "不完全理解但可能有效" | 理解不完全=修复不完整 | --- ## 红色标志 - 停止并重新开始 - "快速修复现在，稍后调查" - "尝试改变 X，看是否有效" - "添加多个更改，运行测试" - "可能大概差不多是 X，让我修复" - "不完全理解但可能有效" - 基于猜测而非证据的修复 **所有这些意味着：停止修复。回到根因调查阶段。** --- ## 四阶段框架 ### 阶段 1：根因调查 **任何修复前**： 1. **仔细阅读错误消息** - 不要跳过错误或警告 - 它们通常包含确切解决方案 2. **一致复现** - 你能可靠触发吗？ 3. **检查最近变更** - 什么变更可能导致此问题？ 4. **多组件系统收集证据** ```bash # 对于每个组件边界： - 记录进入组件的数据 - 记录退出组件的数据 - 验证环境/配置传播 - 检查每层状态 运行一次以收集显示何处中断的证据 然后分析证据以识别失败组件 然后调查该特定组件 ``` 5. **追踪数据流** - 向后追踪到坏值起源 ### 阶段 2：模式分析 1. **找到工作示例** 2. **与参考对比** 3. **识别差异** 4. **理解依赖** ### 阶段 3：假设与测试 1. **形成单一假设**："我认为 X 是根本原因，因为 Y" 2. **最小化测试**：进行最小可能更改 3. **验证后再继续**...