superior-debugging

优质调试

将观察到的故障转化为有依据的因果解释，然后实施最小且完整的修复。在区分证据与假设的同时，遵循用户界定的范围和仓库现有架构。

准确定义故障

更改代码之前，先明确：

• 观察到的结果、预期结果，以及预期的依据；
• 已知的最小复现方式，以及故障是否具有确定性；
• 受影响的版本、环境、输入、用户或数据状态；
• 有证据时，最后一个已知正常状态；
• 影响、紧迫程度，以及任何不安全的复现边界。

不要为了匹配实现而暗中重新定义预期行为。如果约定含糊不清，请指出其中的歧义，并在认定任何一种行为有缺陷之前，先依据仓库证据或用户指示作出判断。

根据证据追查原因

如果原因不确定、存在多种合理假设，或需要通过历史记录或受控实验缩小回归范围，请阅读 references/evidence-driven-diagnosis.md。

沿着可能导致该症状的各个边界追踪故障路径。检查实际值、状态转换、配置、持久化、外部响应和时序，不要仅凭附近的代码推断。维护一组规模适中的可证伪假设，并优先执行成本最低且最有区分力的检查。

区分：

• 触发因素： 暴露故障的输入或条件；
• 根本原因： 使故障成为可能的、被违反的不变量或错误行为；
• 放大因素： 加剧影响的重试、缓存、并发、过时状态或错误处理；
• 症状： 用户可见或运维层面的结果。

不要停留在第一个可疑代码行、异常发生位置或相关事件上。堆栈帧显示的是故障显现的位置，不一定是故障的源头。

安全诊断运行时边界

对于仅在特定环境中出现的故障、异步或并发行为、队列、缓存、数据库、外部服务、资源耗尽或生产环境遥测，请阅读 references/runtime-and-distributed-failures.md。

• 添加检测手段之前，优先查看现有日志、跟踪、指标、错误报告，并进行安全的本地复现。
• 从诊断信息中删除机密、令牌、个人数据和敏感负载。
• 未经明确授权且没有回滚计划，不要在生产流量上试验、修改共享数据、禁用安全措施或大范围提高日志级别。
• 除非约定证明其行为正确，否则不要把延长超时、重试、清除缓存、重启进程或吞掉异常视为根本原因修复。

在负责的边界进行修复

证据确认原因后：

1. 用简洁的说明陈述因果链；
2. 在负责该约定的边界进行更改；
3. 保持兼容性，避免影响无关行为；
4. 删除嘈杂、敏感或已无用的临时诊断信息；
5. 在可行且可信时，添加或更新回归测试；
6. 验证原始复现方式以及相关的相邻行为。

如果证据排除了对代码缺陷的怀疑，请报告实际原因，而不是强行修改代码。如果原因仍不确定，请将结果标注为部分结论，并保留下一项最有区分力的观察或实验。

如实报告置信度

报告以下内容：

• 症状和已确认的影响范围；
• 检查过的证据和复现状态；
• 根本原因；适用时分别说明触发因素和放大因素；
• 修复内容及其解决因果机制的原因；
• 执行的验证及结果；
• 尚存的不确定性、未测试的环境和后续运维工作。

不能仅凭本地测试通过，就声称生产环境特有的事故已解决。请说明问题已复现、已缓解、已修复，还是仍在调查中。

有针对性地组合技能

• 当主要任务是评估一组变更，而不是诊断已观察到的故障时，使用 superior-code-review。
• 当已确认的修复会改变领域规则、持久化、状态转换或 API 行为时，使用 superior-logic。
• 当已确认的原因需要处理架构、查询、事务、迁移或数据修复时，使用 superior-database。
• 当已确认的原因会引出经过测量的优化、容量分析或性能预算时，使用 superior-performance。
• 当已确认的原因需要改进弹性、降级、恢复、告警或运行手册时，使用 superior-reliability。
• 当故障发生在流水线、构件、发布或环境晋级路径中时，使用 superior-delivery。
• 当回归测试设计、测试隔离或不稳定测试诊断成为主要关注点时，使用 superior-testing。
• 当故障暴露出授权、验证、滥用、令牌、SSRF 或信息泄露方面的弱点时，使用 superior-api-security。
• 在验证了实质性修复后，或当持久性的诊断或恢复流程发生变化时，使用 superior-docs。

不要将诊断范围扩大到无关的重构、采用可观测性平台、性能优化或架构重设计。