--- name: systematic-debugging description: 在缺陷、测试或构建失败、异常行为和反复修错时使用；先建立可区分假设的反馈环和根因证据，再按用户授权决定是否修复。普通代码审查、明确的小修改或只执行已有测试不触发。 --- # 系统化排查问题 目标是找到能解释现象的根因，并用同一个反馈环证明修复有效。诊断请求默认只定位和报告；用户要求修复时才修改代码。 ## 核心循环 1. **固定现象**：记录错误、环境、输入、期望、实际结果和最近已知正常状态。 2. **建立反馈环**：优先使用最小测试、复现命令、页面路径、日志条件或可观察状态，使问题能失败、复跑并在修复后变绿。 3. **收集独立证据**：日志、堆栈、配置差异、近期变更、相关源码、网络和环境状态可以并行读取，但结论必须汇入同一证据链。 4. **排序假设**：维护轻量矩阵： `假设 | 支持证据 | 反证 | 置信度 | 下一步最小检查` 5. **验证一个假设**：用最小观测或可逆改动获取能证实或证伪的结果，不同时改变多个变量。 6. **更新模型**：记录被排除方向；同一症状未消失时停止叠补丁，回到矩阵重新排序。 7. **修复与回归**：根因明确且用户授权修复后，做最小修改；先用原反馈环证明问题消失，再按风险扩大验证。修复授权不包含提交、推送、发布或破坏性操作。 8. **同型排查**：宣布修复前，提炼触发缺陷的函数、调用形状、选择器、锁或校验缺口，在仓库内搜索同类位置，逐项标注；方法见 [references/advanced-modes.md](references/advanced-modes.md)。 在改代码前，应能用一句话表达当前假设：`我认为根因是 X，因为证据 Y；结果 Z 会证伪它。`X 要具体到文件、函数、行或触发条件；“状态管理问题”这类说法无法证伪，还不算假设。假设必须解释全部已观察症状，包括报告人认为无关的症状；只解释首个症状的是表层猜测。 出现“先试试这个”“应该是同一个问题”“我本地正常”时，说明还没有假设：先写出假设、重读执行路径或列出环境差异。用户的直接观察与日志冲突时，优先相信观察，把差异当作未覆盖的路径；只在正常路径上通过的探针不能证明故障路径不存在。 反馈环应命中用户报告的具体故障路径，并断言对应的错误输出或终态；“没有报错”或无关测试通过不算复现。先运行一次确认它确实会失败，再尽量缩小输入、调用方和环境条件，每次删去一个条件后重跑。保留原始场景，修复后同时检查最小复现和原始场景。 ## 没有稳定复现时 只能做读取、加观测和缩小范围，不把猜测提交成修复。记录可替代证据，例如 CI 失败、生产日志、用户的稳定步骤、状态差异或最小监控指标，并说明它比本地复现弱在哪里。 运行一次后通过不能自动判定 flaky。至少需要近期重复运行、通过对照和能解释失败的基础设施或时序证据。 缺的是报告人的环境时，下一步交付只读探针而不是新假设：一段可直接复制运行的命令，输出环境信息、争议中的测量值和假设所依赖的状态，不输出凭据或私有路径；安装方式、目录、locale、shell 和版本都要探测，不按自己的环境写死。 ## 按问题类型取证 - 窗口生命周期、事件顺序、焦点、定时器、状态机和异步时序问题：形成假设时就加定向日志，不靠静态阅读连猜两次。 - 渲染或视觉问题：先查图层、层叠上下文和样式计算，再加日志或调试覆盖层。 - 纯逻辑问题（公式、边界、off-by-one）：静态分析和最小用例即可。 - 性能问题：修改前测基线（耗时、采样、内存），修改后用同一方法复测，报告前后数值；“感觉变快”不是证据。 - MCP、API 或外部工具失败：先确认服务、凭据、配置和版本，再决定是否换工具，不直接绕开。 - 修改算法后输出仍不对：先确认运行时没有读取旧代码写入的缓存、快照或生成物；需要时在同一修改中失效或升级旧数据版本。 ## 参考路由 只在命中对应问题时读取： - [root-cause-tracing.md](root-cause-tracing.md)：错误出现在深层调用链，需要追踪原始输入或触发点。 - [condition-based-waiting.md](condition-based-waiting.md)：异步或测试依赖时序，需要用条件轮询替代固定 `sleep`。 - [defense-in-depth.md](defense-in-depth.md)：根因修复后仍需要在多个边界阻止无效状态传播。 - [references/advanced-modes.md](references/advanced-modes.md)：回归对照、二分定位、同型缺陷搜索、回归测试红绿验证、运行时证据和配置诊断。 - [references/failure-patterns.md](references/failure-patterns.md)：问题重复出现、首次修复未生效，或症状更像运行时状态、入口、环境差异而不是语法错误。 ## 安全边界 - 修改配置、版本、端口、权限或网络参数前，记录原值、目标文件和要验证的假设；失败后恢复本轮临时变化。 - 生产和共享环境先做只读检查；修复、重启、删除、回滚和权限操作需要明确目标与授权。 - 临时日志只记录能区分假设的事实，不输出凭据或敏感数据，并在任务结束前移除不需要的观测代码。 - 保护用户工作区中的无关改动，不用破坏性 Git 命令清理环境。 - 编译或静态检查通过不能证明界面、网络、生成物、状态机或生产行为已经恢复。 ## 停止与重置 - 连续两个假设被证伪后，重新排序矩阵，不沿熟悉方向继续加码。 - 连续三个假设被证据推翻后，汇总现象、证据和已排除方向，重新选择诊断方法；有已授权的有效检查时继续，不因计数自动交接。 - 同一阈值、超时、间距或数值调整三次仍不对时，停止调参，检查结构约束和不变量。 - 缺少完成诊断所必需的访问、日志或复现条件时，报告具体缺口和能继续的最小输入。 ## 输出契约 报告： - 现象、范围和复现/替代证据； - 当前最高置信假设及其反证条件； - 已排除方向和关键命令/观察； - 根因结论及证据强度，或为什么仍不能确定； - 若已修复：实际改动、原反馈环结果、更宽验证和残余风险； - 同型排查：检查了哪些位置、哪些同样有问题、哪些可安全保留及原因；未做时说明原因； - 回归保护：新增测试的位置和红绿运行结果，或不加测试的原因； - 若只诊断：不修改文件，并给出下一步最小检查。