用途:为疑难 Bug 和性能回归提供一套有纪律的诊断流程,仅在明确说明理由时才可跳过阶段。探索代码库时,若存在 GLOSSARY.md 应先阅读以建立模块心智模型,并查看所涉区域的 ADR。
主要能力与流程:
- 建立反馈回路:这是核心。优先构造能对该 Bug 变红的紧凑 pass/fail 信号,方式包括失败测试、curl/HTTP 脚本、CLI 夹具对比、无头浏览器脚本、回放捕获的 trace、一次性最小 harness、属性/模糊测试、二分 harness、差分对比,最后才用 HITL 脚本。回路要更快、信号更锐利、更确定。非确定性 Bug 的目标是提高复现率而非干净复现。
- 复现并最小化:确认失败模式与用户描述一致,可多次复现,并捕获确切症状;逐步削减输入、调用方、配置、数据与步骤,直到每个剩余元素都是承重的。
- 提出假设:先给出 3–5 个排序假设,每个必须可证伪并说明预测,展示给用户后再测试。
- 插桩:每个探针映射到具体预测,一次只改一个变量;优先调试器/REPL,其次边界处的定向日志,禁止“全量日志再 grep”;调试日志加唯一前缀如 [DEBUG-a4f2]。性能分支应先建立基线测量再二分。
- 修复与回归测试:仅在存在正确接缝时先写回归测试;若无正确接缝,这本身就是发现,需记录。
- 清理:确认原始复现不再出现、回归测试通过、移除所有 [DEBUG-...] 插桩、删除一次性原型,并在提交/PR 中写明最终正确的假设。
限制与注意:展示命令、输出和捕获物前必须脱敏,用 <REDACTED> 替换密钥,凭据留在环境变量中,只引用携带信号的日志行;若脱敏后不足以诊断,应说明并询问用户。若确实无法建立回路,应停止并明确说明,列出尝试过的方法,向用户请求可复现环境、脱敏捕获物或临时生产插桩许可,不得在无回路时继续假设。完成标准是回路紧凑且能变红:可命名一条已运行过的命令,能驱动真实 Bug 路径并断言用户的确切症状,确定、快速、可无人值守运行。资料未提供具体安装命令、收费或平台信息。