code-debug-skill

Bug 调查技能

调查思路（如何思考）

• 以事实为先。始终区分观察结果和推断。
• 保留多个相互竞争的假设，并按可能性和影响排序。
• 对每个假设，明确：
  • 预测（如果假设成立，必须观察到什么），
  • 证伪条件（什么情况会推翻该假设），
  • 所需的检测手段（要测量或记录什么）。
• 优先选择决定性信号，而不是叙述。不要在没有证据采集计划的情况下要求复现。
• 尽可能通过对比（失败与成功）和类似二分查找的方法缩小范围。
• 尽可能充分地添加调试检测，以便在一次复现中捕获决定性信号。
  • 假设每次复现的成本都很高；应添加足够的检测来缩小根因范围，避免需要额外复现。
• 切勿推测性地修复代码。任何生产代码变更前，都必须用证据确认根因。

工具选择（使用什么）

• 新增检测时的首选工具：本地 HTTP 接收日志工具（debugsk）。
  • AI 必须先通过 npx debugsk@latest server start --json 启动服务，然后再添加检测。
  • 使用 JSON 输出复制代码片段和端点。
  • 服务接受 CORS 预检请求（OPTIONS），因此默认 JSON 代码片段可跨源使用。
• AI 必须自动生成 sessionId/runId，并将其直接嵌入检测代码。
  • 不要要求用户通过控制台设置这些值。
• 如果可以复现，优先记录能直接验证预测的日志和指标。
• 如果无法复现，则转而使用现有信号：
  • 日志/指标/追踪、配置差异、数据快照、转储和确定性探测。
• 如果原生信号无法回答问题，优先使用 debugsk 采集新的观察结果。
  • 这样可避免污染原生日志，并将调查日志隔离。
• 除新增检测外，也要使用原生日志作为参考。

操作原则

• 将事实（观察到的）与假设（推断出的）分开。
• 在证据排除其他假设之前，始终保留多个相互竞争的假设。
• 对每个假设，明确预测、证伪条件和所需的检测手段。
• AI 执行所有可自动化的任务： 启动服务、生成 ID、收集日志、分析。
• 用户仅执行无法自动化的 UI 操作（点击、填写表单等）。
• 在检测计划准备就绪之前，不要要求复现。

核心循环

1. 准确澄清 Bug：
   • 环境（本地/预发布/生产）、版本/提交、发生频率、影响。
   • 最简复现步骤、预期结果与实际结果、错误和时间戳。
2. 找出候选代码路径：
   • 按端点/路由/功能/配置键/错误文本搜索。
   • 梳理请求 → 处理程序 → 数据/依赖项。
3. 至少提出三个假设：
   • 客户端/输入、服务端逻辑、数据/状态、并发、配置、依赖项、资源。
4. 启动调试服务并生成 ID：
   • 运行 npx debugsk@latest server start --json 获取端点。
   • 自动生成 sessionId/runId，并将其嵌入检测代码。
5. 添加检测以验证假设：
   • 在决策点和边界处添加日志/指标。
   • 包含自动生成的关联键（无需用户操作）。
6. 执行受控复现：
   • 如有需要，由 AI 启动服务。
   • 仅向用户提供 UI 操作步骤（点击、拖动、提交等）。
   • 不要提供控制台命令，不要要求执行文件操作。
7. 收集并分析日志：
   • AI 直接使用 Read/Grep 工具读取日志文件。
   • 对比成功运行和失败运行。
   • 尽可能优先使用类似二分查找的方法缩小范围。
8. 持续迭代，直到确认根因。

埋点策略

• 如果有可用的本地 HTTP 日志接收器，优先使用；否则集成现有日志系统。
• 如果原生信号不足，优先使用 debugsk，而不是添加更多原生日志。
• 将原生日志与新增埋点一起用作参考。
• 日志绝不能抛出异常；避免记录密钥和个人身份信息（PII），并确保易于移除。
• 每条事件都必须记录位置、消息、时间戳和关联字段。
• 每条日志事件都必须始终包含所有日志字段（timestamp、message、sessionId、runId、hypothesisId、location）。不得遗漏任何字段。
• 不要使用环境标志控制埋点。为调查记录日志，并在完成后移除。
• AI 启动调试服务、生成 ID、插入埋点，并收集和分析日志。
• 用户仅执行 UI 操作（点击、填写表单等）。不得执行控制台命令或文件操作。

用户交互规则

• **尽量减少用户负担。**所有可自动化的任务均由 AI 执行：
  • 启动／停止调试服务
  • 生成并嵌入 sessionId/runId
  • 读取和分析日志文件
  • 判断是否需要建立隧道（检查环境，不要询问）
• 用户仅执行不可自动化的 UI 操作：
  • 点击按钮、拖动元素、填写表单
  • 切换屏幕
  • 观察可见行为
• 需要复现问题时，只提供 UI 步骤。不得提供控制台命令或文件操作。
• 如果无法复现，则转而检查现有日志、指标、追踪信息、配置差异或安全探针。
• 对于外部／移动端访问，AI 根据环境检查结果判断是否需要建立隧道：
  • 如果是远程／预发布环境：检查现有隧道或提出具体设置方案
  • 不要提出“是否要使用隧道？”之类的开放式问题

清理策略

• 用户确认问题已解决或调查已结束后，停止调试服务并删除所有调查日志（例如 .logs/）。
• 删除日志时，不要使用 git checkout、git clean 或其他批量 Git 清理操作。应明确且安全地移除文件。
• 如果删除操作可能影响无关文件，请在移除前确认具体路径。

报告格式

使用 assets/report-template.md 中的模板。标题使用双语（英语／日语）；正文使用用户所用的语言。

参考资料

• 添加或验证埋点时，使用 references/logging-schema.md。
• 整理假设和预测时，使用 references/hypothesis-template.md。