Superior Debugging 是一个用于软件故障诊断与修复的技能,目标是把观察到的失败转化为有证据支撑的因果解释,然后做出最小而完整的修复,同时保持用户设定的范围和仓库既有架构。
用途
它面向可复现、间歇性、特定环境或仅在生产中观察到的软件失败。核心做法是沿证据追踪根因,而不是停留在第一个可疑代码行、异常位置或相关事件上。技能强调不得为了迎合实现而悄悄重定义预期行为;若契约不明确,应先识别歧义,再依据仓库证据或用户指示判断。
主要能力
- 精确定义故障:在改代码前明确观察结果、预期结果及其来源,最小已知复现及是否确定性,受影响版本、环境、输入、用户或数据状态,最后已知良好状态,以及影响、紧急程度和不安全的复现边界。
- 证据驱动诊断:在原因不确定、存在多个假设或需要借助历史与受控实验缩小回归范围时,查阅 evidence-driven-diagnosis.md 参考。跨可能拥有症状的边界追踪失败路径,检查实际值、状态转换、配置、持久化、外部响应和时序,而非从邻近代码推断。维护少量可证伪假设,先做最省力的区分性检查。
- 区分四类因素:触发条件(暴露失败的输入或条件)、根因(被违反的不变量或导致失败成为可能的错误行为)、放大因素(重试、缓存、并发、陈旧状态或错误处理)、症状(用户可见或运维结果)。
- 安全诊断运行时边界:针对仅环境出现的失败、异步或并发行为、队列、缓存、数据库、外部服务、资源耗尽或生产遥测,查阅 runtime-and-distributed-failures.md。优先使用既有日志、追踪、指标、错误报告和安全本地复现;诊断中脱敏密钥、令牌、个人数据和敏感载荷;未经明确授权和回滚计划,不在生产流量上实验、变更共享数据、关闭防护或扩大日志。
- 在拥有契约的边界修复:证据确认原因后,用一段简洁说明陈述因果链,修改拥有被违反契约的边界,保持兼容性与无关行为,清理嘈杂或敏感的临时诊断,酌情添加或更新回归测试,并验证原始复现与相邻行为。若证据否定代码缺陷,应报告实际原因而非强行改代码;原因仍不确定时标注为部分结果并保留下一步区分性观察。
- 如实报告置信度:报告症状与确认范围、检查的证据与复现状态、根因(必要时分开触发与放大因素)、修复及为何解决因果机制、已做验证及结果、剩余不确定性、未测试环境和运维跟进。不得仅因本地测试通过就宣称仅生产环境的事故已解决,需说明结果是已复现、已缓解、已修复还是仍在调查。
使用方式
该技能以文档形式提供操作规范与参考文件(evidence-driven-diagnosis.md、runtime-and-distributed-failures.md),在调试任务中按上述流程执行。未提供安装命令或代码示例。
适用场景
适用于可复现、间歇性、环境特定或生产观察到的失败诊断;也可作为组合技能使用:主要任务是评估变更集时用 superior-code-review;修复涉及领域规则、持久化、状态转换或 API 行为时用 superior-logic;涉及 schema、查询、事务、迁移或数据修复时用 superior-database;涉及测量优化、容量分析或性能预算时用 superior-performance;涉及韧性、降级、恢复、告警或手册变更时用 superior-reliability;失败属于流水线、制品、发布或环境晋级路径时用 superior-delivery;回归设计、测试隔离或不稳定测试诊断成为主要关切时用 superior-testing;失败暴露授权、校验、滥用、令牌、SSRF 或信息泄露弱点时用 superior-api-security;经过验证的实质性修复后或持久诊断/恢复流程变化时用 superior-docs。
限制
不要把诊断扩大到无关重构、可观测性平台引入、性能优化或架构重设计。不得将超时增加、重试、清缓存、重启进程或吞掉异常视为根因修复,除非契约证明其为正确行为。官方未提供版本、平台支持、收费或价格信息。