pstack原则12修复根因：给AI Agent的5 Whys调试法-二趣网

pstack原则12修复根因：给AI Agent的5 Whys调试法

【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Poteto's pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude

pstack是一套为 AI Agent 打造的技能栈（支持 Claude Code、Codex、Pi 等工具），其中"修复根因"（Fix Root Causes）是它 27 条工程原则中专门治理调试行为的一条：先复现、再连环追问"为什么"、在根因处下刀，而不是打补丁。本文带你用"5 Whys"的思路，看懂这条原则如何让 AI Agent 修 Bug 时不再头痛医头。

为什么"修症状"对 AI Agent 特别危险

人类程序员修错地方，往往是因为没耐心；而 AI Agent 打补丁，是因为补丁太容易了。加一个判空、塞一个try/catch、写一段 workaround 注释，几秒钟就能让测试变绿——但真正的 Bug 还留在原地。

pstack 在 principle-fix-root-causes/SKILL.md 中开宗明义：

症状式的修复会不断累积。每一个 workaround 都让系统更难推理，而真正的 Bug 依然存在。根因修复前期更慢，但总调试时间更短。

对 AI Agent 来说，这条原则的价值是双重的：既约束它别糊弄，也帮你少返工——因为 Agent 糊上去的补丁，迟早会在下一个需求里反噬。

5 Whys 实战：六步把 Agent 钉在根因上

经典的"5 Whys"调试法就是不断追问"为什么"，直到挖到最底层的原因。pstack 把它翻译成 Agent 可直接执行的六步模式（完整规则见 SKILL.md）：

步骤	做法	一句话提醒
1️⃣ 先复现	Reproduce first	复现不了的问题，修了等于没修
2️⃣ 连环追问	Ask "why" until you hit the root cause	别在第一层解释就收工
3️⃣ 禁止加护栏	Do not add guards	给崩溃加判空，就是症状修复
4️⃣ 注释是警报	一段话注释才能解释的 workaround	错的是代码，不是注释
5️⃣ 看模式不看个案	grep 同样的模式，一次修完所有实例	修一个漏点，可能还有九个
6️⃣ 卡住就插探针	Instrument. Don't guess	加日志、读真实报错，禁止玄学猜测

第 3 步值得单独展开：给崩溃加一个 nil check 让程序不崩，是症状修复。pstack 的判断很犀利——护栏只是把"程序崩溃"换成了"数据静默出错"，而且下次换条路径，它还会以别的姿势再崩一次。

重启类 Bug：先怀疑状态，再怀疑代码

这条原则里有一个非常实用的经验规则："重启后失效"的问题，先怀疑过期的持久状态。

配置文件、缓存、锁文件、序列化状态——这些"隐形记忆"经常是重启 Bug 的真凶。pstack 的建议是：如果清掉某个状态文件后行为恢复正常，那么状态校验（而不是改业务代码）才是修复的正解。

对新手来说这招特别好用：下次遇到"重启就好了 / 重启就坏了"，让 Agent 先列出所有持久化状态文件，逐个清空验证，往往十分钟就比改半天代码更接近真相。

在 pstack 里如何触发这套调试法

你不需要死记这些原则——pstack 的设计就是你说目标，它自己调用正确的工作流：

总入口：poteto-mode 技能。把 Bug 描述给它（例如"修复翻页时搜索条件被重置的问题"），它会走 Bug fix 剧本：自己复现 → 二分定位成因 → 修复 → 在同一环境验证 → 把失败的复现用例先提交、修复再提交，形成可验证的证据链。
考古搭档：why 技能负责回答"这段代码当初为什么这么写"，它会让多个调查子代理并行翻查 Git 历史、Issue、文档、团队聊天、错误追踪等 7 类证据源，再交给综合者输出带引用的结论——这正是"连环问为什么"需要的历史素材。
配套原则：修完一个实例后，no-comments 要求删掉所有被点名的 workaround；principle-prove-it-works 则要求拿真实产物验证，而不是"编译通过就算完"。

简单说：复现归 Bug fix 剧本，追问归 5 Whys，考古归 why，验证归 Prove It Works——四件套各司其职，Agent 的调试过程就有了完整的纪律约束。

上手前的 3 个提醒

别被"测试通过"骗了。Bug fix 剧本第 4 步明确要求：原始复现用例必须从失败变通过，"不确定"或换了一个环境验证都不算数——单元测试只证明分支行为，不证明 Bug 不存在。
根因修复前期更慢，这是特性不是缺陷。原则 12 赌的是总时间：省掉的每次返工，远比多花的那 10 分钟值钱。
把原则交给结构，而不是靠自觉。pstack 整套技能栈（见 README.md）的本质，就是把这些"人类要靠经验才做到的事"写成 Agent 每次都会执行的流程。

关键文件速查

原则 12 原文：plugins/pstack/skills/principle-fix-root-causes/SKILL.md
总调度技能：plugins/pstack/skills/poteto-mode/SKILL.md
Bug 修复剧本：plugins/pstack/skills/poteto-mode/playbooks/bug-fix.md
代码考古技能：plugins/pstack/skills/why/SKILL.md
项目总览：README.md

把"5 Whys"装进 AI Agent，得到的不是一个会问问题的助手，而是一个拒绝糊弄的调试者。下一次当你看到 Agent 又想去加一个"保险"的时候，让它先把这条原则读一遍。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析