Pi实战 10：重构与避坑篇------让 Pi 重构大项目而不搞砸
来源：Mario Zechner 博客/推文、DAPLab《9 Critical Failure Patterns of Coding Agents》、Simon Willison 对谈、Umut Eser、HN、pi-self-learning 等。
一、使用场景
- 有个几千行的老模块想重构，不敢手拆，想让 Agent 上。
- 用 Agent 开发一段时间后，发现代码越来越臃肿、重复、抽象乱长，想治理。
- 想让它审查代码库、找"简化"机会。
- 担心 Agent 改着改着把架构改乱、引入技术债。
二、能解决什么问题
解决一个反直觉但极其重要 的认知：Agent 不会主动帮你重构，反而会让你欠更多技术债。
Mario Zechner（Pi 作者）的原话，值得每个用 Pi 的人贴墙上：
"Agents refactor less because they feel no 'pain.' Humans rewrite bad interfaces because maintaining them hurts, whereas agents will obliviously churn out and extend a terrible structure, ad infinitum. This is a big reason why AI agents keep adding more tech debt."
（Agent 很少重构，因为它们感受不到"痛"。人类会因为有维护之痛而重写烂接口，Agent 却会无意识地在一堆烂结构上继续堆砌，永无止境。这就是 AI 不断堆积技术债的一大原因。）
他还有一条推文更直白：
"Your biggest enemy is still complexity. It's also your agent's biggest enemy. But it has no holistic view of your code base, so it keeps adding complexity."
（你最大的敌人是复杂度，它也是 Agent 最大的敌人。但 Agent 没有你代码库的全局视图，所以它会不断加复杂度。）
所以这一篇的核心价值 ：教你用人来当"复杂度守门员"，用流程约束 Agent，让它重构时不帮倒忙。
三、解决思路
思路 1：你负责"痛"，Agent 负责"改"
既然 Agent 感受不到痛，你得替它感到痛------主动要求它简化、主动审查它有没有重复/过度抽象。别指望它自发做。
思路 2：只读优先，先诊断后动手
对大代码库，先让它只读、只描述、不改，你确认方向对了再让它改。HN 上 Pi 用户的真实做法（见第 09 篇那个 Go 审查 prompt）就是典范。
思路 3：分阶段，别一次吞下整个代码库
DAPLab 指出 Agent 的典型失败模式是 "lack of codebase awareness"（缺乏代码库意识） ：项目一大，它就记不住整体架构，改错组件、引入破坏性变更。对策是分阶段、小范围、有验证地推进。
思路 4：保持代码库高质量，Agent 才会产出高质量
Simon Willison 的洞见：
"There's a lot to be said for keeping your codebase high quality because the agent will then add to it in a high quality way. ... Even having just one or two tests in the style that you like means it'll write tests in the style that you like."
（保持代码库高质量很有意义，因为 Agent 会以同样高质量的方式往上加。哪怕只有一两个你风格喜欢的测试，它也会照着那个风格写测试。）
你的代码库是什么样子，Agent 就会往那个方向放大它。 这是正反馈------好的越好，烂的越烂。
四、如何实战（含例子）
实战 1：只读诊断------先让它"找简化机会"
直接复用 HN 那个被验证有效的 prompt（改改就能用）：
Review all golang code files in this folder. Look for refactor opportunities
that make the code simpler, shorter, easier to understand and easier to
maintain, while not changing the logic, correctness or functionality of the
code. Do not modify any code; only describe potential refactor changes.要点：明确"只描述不改"，并定义"好重构"的标准（更简单、更短、更易懂、更易维护、不改逻辑）。拿到清单后，你挑真正有价值的再让它动手。
实战 2：对抗 DAPLab 的失败模式
DAPLab 总结的几个高频失败模式，各有对策：
| 失败模式 | 表现 | 你的对策 |
|---|---|---|
| 缺乏代码库意识 | 改错组件、引入破坏性变更 | 分阶段、小范围；让它先画架构再动 |
| 重复代码 | 在 fetchUserData 和 fetchProductData 里各写一遍 API setup，而不是抽共享 helper |
明确要求"复用既有抽象，别重写" |
| 业务逻辑错配 | 拖拽 reorder 只更新了部分 state，没协调整个列表顺序 | 让它写测试覆盖该交互，用测试验证 |
把这三条写进 AGENTS.md，变成它的默认约束。
实战 3：禁止"并行改同一批文件"
Mario 明确说：
"Spawning multiple sub-agents to implement various features in parallel is an anti-pattern in my book and doesn't work, unless you don't care if your codebase devolves into a pile of garbage."
（并行开多个子代理实现不同功能，在我这是反模式，除非你不在乎代码库变成垃圾堆。）
对策：触及相同文件的任务串行，只有彼此独立的单元才并行。（brian-kimball 的 triage 原则也是这个：Inline / Delegate / Parallelize-only-when-independent / Serialize-when-shared.）
实战 4：对抗"过度工程"
Umut Eser 吐槽所有 Agent 的通病：
"You give an instruction and they overkill it. They all try to build a full fledged code, which has a ton of unnecessary components... A lot of fail-safe mechanisms, creating silent bugs."
对策------在 prompt / APPEND_SYSTEM.md 里明确要求最小实现：
从最简单、能跑的最小实现开始，不要预先加抽象、fail-safe 或我沒要求的组件。
我会让你迭代扩展。YAGNI.实战 5：让 Pi 记住教训（自我学习）
nodeland 指出 Agent 的致命弱点：每次会话都是全新开始，零记忆，于是你会反复踩同一个坑。
pi-self-learning 的解法：建一个 CORE.md，按频率和近远给"学到的教训"排序，每次会话自动注入。配套命令：
/learning-now → 立刻做一次反思
/learning-month 2026-08 → 生成月度总结
/learning-status → 看当前生效的配置这样"别重写既有抽象""某模块有个坑"这类教训会跨会话沉淀，而不是每次重新交学费。
五、小结 & 避坑
- 你当复杂度守门员：Agent 不觉得痛，你得替它觉得痛，主动要求简化。
- 先只读诊断，后动手：大代码库先让它只描述不改，你挑了再改。
- 分阶段、小范围、有验证：对抗"缺乏代码库意识"。
- 要求复用、禁止并行改同文件、要求最小实现 ：三条直接写进
AGENTS.md。 - 保持代码库高质量：你是什么样，Agent 就放大成什么样。
- 让教训跨会话沉淀：用自我学习扩展记住踩过的坑。
参考资料
- Mario Zechner《What I learned building an opinionated and minimal coding agent》：https://mariozechner.at/posts/2025-11-30-pi-coding-agent
- The Pragmatic Engineer《Building Pi, and what makes self-modifying software so ...》：https://newsletter.pragmaticengineer.com/p/building-pi-and-what-makes-self-modifying
- DAPLab《9 Critical Failure Patterns of Coding Agents》：https://daplab.cs.columbia.edu/general/2026/01/08/9-critical-failure-patterns-of-coding-agents.html
- Simon Willison《Fireside chat about agentic engineering》：https://simonw.substack.com/p/fireside-chat-about-agentic-engineering
- Umut Eser（LinkedIn，Agent 通病：overkill）：https://www.linkedin.com/posts/umuteser_all-ai-coding-agents-i-have-tested-have-common-activity-7354121624033394688-Otso
- nodeland《Your Coding Agent Keeps Making the Same Mistakes》（pi-self-learning）：https://adventures.nodeland.dev/archive/your-coding-agent-keeps-making-the-same-mistakes
- HN《Ask HN: How do people use coding agents?》：https://news.ycombinator.com/item?id=47867857
上一篇：09 · 提示词心法篇 ｜ 下一篇：11 · 上手陌生代码库篇