用途:任何技术问题(测试失败、生产缺陷、意外行为、性能问题、构建失败、集成问题)发生后、提出修复前使用。核心原则是先找到根因再修复,只治症状视为失败。
铁律:未完成第一阶段根因调查,不得提出修复。
四个阶段(每阶段完成后才能进入下一阶段):
- 根因调查:仔细读错误与堆栈、记录行号路径与错误码;稳定复现并确认步骤;检查近期变更(git diff、提交、依赖、配置、环境差异);多组件系统在提出修复前先在各组件边界加诊断日志,观察数据进出、配置传递与各层状态,一次运行定位失效层;沿调用栈向上追溯坏值来源,在源头而非症状处修复。
- 模式分析:在同仓库找可用的相似实现作为参照,完整阅读参照实现,列出可用与失效之间的全部差异,理解所依赖的设置、配置与环境假设。
- 假设与验证:写出单一明确假设(“我认为X是根因,因为Y”),做最小改动、一次只改一个变量来验证;不行则提出新假设,不要叠加更多修复。不清楚就直说,求助或继续查证。
- 实施:先写最小复现的失败测试(可用则自动化),再做单一修复,只解决根因,不做“顺手”改进或捆绑重构,最后验证修复通过且未破坏其他测试。
失败处理:修复尝试少于3次则带新信息回到第一阶段;达到或超过3次则停下,与搭档讨论架构问题(每修一处又暴露新耦合、需大规模重构、别处出现新症状,说明架构有误),不要直接做第4次修复。
建议:事先写测试,不跳过流程,时间压力下更应系统化。资料提到配套文档 root-cause-tracing.md、defense-in-depth.md、condition-based-waiting.md,以及相关技能 superpowers:test-driven-development 和 superpowers:verification-before-completion。资料中给出的效果数字:系统化方式15-30分钟修复、首次修复率95%、新引入缺陷接近零;随机修复2-3小时、首次修复率40%。若调查确认问题属环境、时序或外部因素,则记录调查过程、实施重试/超时/错误提示等处理并加监控;但约95%的“无根因”实为调查不完整。具体安装与使用方式暂未提供。