specsfy-specialist-debugging

诊断

适用场景

• 当观察到的行为与预期不符时使用，无论是否已建立可靠的复现方式。
• 间歇性故障（“flaky”）、部署后的回归，或出现具体症状（超时、错误、报告的延迟）的性能下降，也使用此项。
• 不要用于优化行为正确且没有症状的系统——这种情况适用 $specsfy-specialist-performance-engineering，它从 SLO 出发，而不是从故障出发。
• 如果生产环境没有暴露足够的信号来为正确的边界添加检测，则与 $specsfy-specialist-observability 配合使用。

流程

1. 记录预期行为、观察到的行为、确切环境，以及最近一次发生的时间和频率——缺少这些信息，假设就只是猜测。
2. 建立可靠的复现方式；如果无法直接复现，则建立与故障相关联、可观察且可重复的信号（日志、指标、跟踪）。
3. 缩减输入、涉及的组件和时间窗口，直到得到仍能复现故障的最小案例——移除后不影响结果的每个元素，都是从假设中排除的一个变量。
4. 提出可证伪的假设，并根据测试难易程度和观察到的症状所显示的可能性排序，而不是按趣味性排序。
5. 在剩余假设之间最具区分度的边界添加检测——即一个假设预测某个值、另一个假设预测不同值的位置。
6. 找出原因、影响范围（仅此路径，还是整类调用）以及导致症状的确切机制。
7. 如果获准修复，则应用能消除原因的最小改动，并添加回归测试，确保缺少该修复时测试会失败。

准则

• 一次不要更改多个候选原因——同时更改两处内容后，如果症状消失，就无法确定原因。
• 区分时间相关性和因果关系：“在部署 X 之后开始”是一条线索，而不是证据，除非已隔离出具体机制。
• 重启进程或清除状态前，先保留证据（日志、状态、转储）——发生故障的环境之后可能无法复现。
• 系统地比较正常和异常环境：版本、配置、数据、负载和操作顺序都相同，每次只改变一个因素。
• 在有相反证据前，将 flakiness 视为并发、时序、共享状态或外部依赖的症状——绝不要只当作“再运行一次就好”。
• 完成诊断前，移除临时的、冗长的或敏感的检测内容（个人数据、密钥）。
• 从机制层面描述原因（“X 与 Y 之间的竞态允许在写入完成前读取”），不要只描述症状（“有时会失败”）。

反模式

• 没有事先提出假设就“添加 print 然后重新运行”——这会产生噪声，很少能缩小搜索范围，而且往往与随机尝试无异。
• 只修复错误首次出现的位置，却不确认那里是根源，还是仅仅是效果显现之处（NullPointerException 很少是在抛出的位置产生的）。
• 因为手动复现时有一次没有再失败，就宣称“已修复”——没有自动化且确定性的复现方式时，症状消失可能只是运气好或时序发生了变化。
• 将 flaky 测试视为“有时不稳定，与问题无关”而不调查——多数情况下，flakiness 是真实并发错误或共享状态错误的证据，而不是应该压制的噪声。

验证

• 修复前，可在同一环境中稳定复现失败；修复后，可稳定通过。
• 撤回修复后，新增的回归测试会因正确的原因失败（而非其他偶然原因）。
• 已检查修复路径相邻的场景，确认变更没有副作用。
• 已简要记录原因（机制）、证明原因的证据，以及新增的预防措施（测试、不变量、告警）。
• 没有这些证据，不要宣称原因已“解决”——禁止在没有复现或回归测试的情况下凭直觉归因。

相关技能

• $specsfy-specialist-server-report 使用 Ansible 以只读方式收集数据，按主机汇总日志、服务和磁盘使用情况。

• $specsfy-specialist-technical-research 在原因取决于一手文档时，确认外部行为、勘误或兼容性。

• $specsfy-specialist-observability 在现有信号不足以区分各种假设时，为生产环境添加检测。

• $specsfy-specialist-performance-engineering 在症状表现为性能下降、但没有功能错误时使用——此处的根因诊断可以交由该技能决定哪项优化值得投入成本。

• $specsfy-specialist-code-review 在合并前审查修复和回归测试。

阅读 references/standards.md，了解复现和隔离技巧、常见的不稳定原因、各环境适用的工具及官方资料。