最近接了个活儿，用 Pi coding agent 把一个仓库从“毛坯房”状态装修成能正常跑起来的项目。所谓毛坯房，就是只有一手老代码、一个残缺的 README 和几条没人敢动的历史包袱，既没有完善的工程化配置，也没有测试兜底。本来想着有 AI 辅助，应该能省不少事，结果一路踩坑踩到怀疑人生。这篇文章就把我这段时间用 Pi agent 装修毛坯房的完整过程记录下来，包括那些文档里不会写的坑、Agent 的脾气秉性，以及最后沉淀下来的一套能少走弯路的实操流程。如果你也是拿 AI 写代码当日常，尤其是要接手老项目、补历史债的人，这篇内容应该能让你少交一点学费。
1. 毛坯房交付前，先把Agent的“施工图纸”画清楚
1.1 环境准备和上下文构建，决定了后面是装修还是返工
我第一次用 Pi agent 处理这个老仓库时，犯了个很蠢的错误——直接把仓库丢给它，说“帮我把这个项目跑起来”。结果它花了大量时间在猜我到底想要什么：是先修构建脚本？还是补依赖？还是重写文档？最后产出了一堆看起来很努力、但完全没有落点的改动。
后来我才意识到，AI 编程代理和我们人接手一个老项目是一模一样的：你给它多少上下文，它就做多少判断题。毛坯房它看不到墙里的水管图，你得先把图给它。所以我的第二个做法是，在开工前自己先花 20 分钟，手动梳理出这个仓库的全貌，用一份简短的AGENTS.md把项目说明写清楚。
这里分享一个我现在固定用的上下文模板，不只是给 Pi agent 看，任何 coding agent 都适用：
- 项目整体目标：这个项目是干什么的，目标用户是谁，核心业务闭环是什么
- 技术栈清单：语言、框架、关键依赖、构建工具的版本，越精确越好
- 目录结构导览：哪些目录是核心业务代码，哪些是生成物，哪些是历史垃圾不要碰
- 当前最大痛点：你希望 Agent 优先解决哪个问题，比如“先让 dev server 能跑起来”或“修掉构建警告”
- 明确的禁区：比如“不要动 tests 目录”、“不要升级 React 版本”
1.2 一次只给一个装修任务，别让它当“全屋设计师”
还有一个我在初期反复踩的坑：任务给得太宽。装修毛坯房，你不会找一个工人既改水电、又刷墙、又打柜子，哪怕他是全能工，你也得按工序来。Pi agent 同理。
有一次我让它“顺便把代码风格统一一下、顺手修掉两个 lint 报错、再给新接口补个测试”，结果三个任务哪个都没做利索。统一风格改动了大量文件，导致 diff 根本无法 review；修 lint 又触碰了核心逻辑；测试补了一半就没停住，跑去重构其他函数。
我的教训是：每个任务只给一个清晰、可验收的目标，并明确“完成”的定义。比如：
- 不叫“修一下这个模块”，而是“让
paymentService中的calculateFee函数在传入负数时返回 0，并新增一条对应的单元测试” - 不叫“优化启动速度”，而是“定位
webpack.dev.js中导致二次编译超过 3 秒的插件，移除并验证 dev server 启动时间”
这不是限制 Agent 的能力，恰恰是给它的上下文“画线”。画得越清楚，它越不会跑偏。
2. 装修事故No.1：Agent的“默认审美”和你的工程规范不对付
2.1 格式化偏好冲突：一场没有赢家的代码风格战争
毛坯房装修最怕什么？最怕你的设计稿和工人的习惯拧着来。我用 Pi agent 干的第二个大蠢事，就是没有提前告诉它这个项目的代码风格底线。
我当时让 Agent 修一个函数，它很主动地把整个文件都用 Prettier 默认配置重新格式化了一遍——单引号变双引号、尾逗号加回来了、缩进从 4 空格变成 2 空格。从我视角看，整个文件 diff 全是噪音，真正改的逻辑淹没在几百行格式改动里，根本没法 review，WebStorm 的 Git 对比窗口一片标红。
后来我研究了一下原因：Pi agent 默认生成的代码风格，是根据训练语料里 GitHub 高频风格来的，而这个老仓库用的是 5 年前的团队自定义风格。两者不匹配，Agent 就会“善意”地帮你全部统一。
这件事的解法其实很便宜：在项目根目录放一份.prettierrc或者.editorconfig，并且在 AGENTS.md 里写死一条规矩：“格式问题由提交时的 husky 钩子统一处理，Agent 不要对已有代码做任何格式重排。”加上这条之后，Pi agent 的产出立刻规矩多了。它其实并不是有意添乱，只是你的“工地守则”没传达给工人。
2.2 Agent的“全屋重建”倾向：为什么它总想推翻重写
如果说格式冲突是表面问题，那深一层的坑就是——Pi agent 面对一栋结构性不太好的老房子，第一反应往往不是局部修缮，而是推倒重来。
我遇到过一次特别典型的例子：老代码里有一个工具函数，三百多行，中间有大量重复逻辑和一段明显失灵的异常捕获。我让 Agent “优化这个函数，保持外部调用接口不变”。它给我的方案是：重写整个模块，把函数拆成 6 个小函数，还配了个类。从纯代码质量角度，它的方案其实还挺好，但问题是我没法验收——调用方有十几个文件依赖这个模块的历史行为，里面有几个让人摸不着头脑的“隐含约定”，Agent 的重构版本表面行为一致，边界行为完全不同。
那一次返工我浪费了将近两个小时。我的应对策略是在任务描述里明细两条：
- 禁止重构与本次任务无关的代码块
- 如果发现当前函数无法在不动结构的前提下完成修复，必须先列出“需要动的函数清单”再动手，而不是直接新写一个替代版本
这两条加进上下文之后，Pi agent 开始学会“在原有结构里打补丁”了，产出质量对于老项目来说，比它自由发挥时好得多。
3. 装修事故No.2：依赖管理的“水电改造”环节
3.1 毛坯房的水电管线，就是你的依赖关系
做过装修的人都知道，水电改造是隐蔽工程里的头等大事，返工成本最高。代码项目里，依赖管理就是水电管线。而 Pi agent 在这块的表现，属实需要“老父亲式”的盯防。
有一次我让它给项目加一个新的 HTTP 客户端库，它很乖巧地在package.json里追加了最新版本依赖，然后顺手把另一个旧库从依赖列表里删了——因为它在某个文件里发现旧库已经没被 import 了。看起来非常合理对不对？但问题是，那个旧库是通过全局注册的方式被其他服务间接引用的。Agent 只扫了当前仓库的 import 语句，没有能力知道运维平台上还有别的服务在引用这个包。
这个坑的教训是：在涉及依赖增删的任务里，我必须自己先做一轮排查，而且绝不让 Agent 直接改 package.json 和 lock 文件。我会让它先把方案写出来，比如“我建议移除 xxx 包，因为我在 src/ 下没有找到任何直接引用”，然后我自己基于仓库搜索和运维知识来判断这个结论是否成立。
3.2 npm 与 pnpm 的暗坑：双重锁文件带来的混乱
老项目最经典的坑之一，就是 package-lock.json 和 pnpm-lock.yaml 同时存在。这往往是几波人接力维护留下的历史遗迹。Pi agent 遇到这种情况会怎么处理？它完全没有犹豫——直接按照项目里最新修改时间较近的锁文件来执行安装，根本不会向你确认。
我遇到过的情况是：项目根目录同时有package-lock.json（三天前更新）和pnpm-lock.yaml（两个月前生成）。Agent 以为是 npm 项目，跑了一遍npm install，把 node_modules 里原本由 pnpm 安装的依赖结构全打乱了。结果就是 dev server 启动报各种诡异的模块找不到，排查了整整一个下午，最后只能删掉 node_modules 重新用 pnpm 装一遍才恢复。
从那次以后，我在 AGENTS.md 里加了一条硬性规范：统一包管理器，明确写明“本项目只使用 pnpm，禁止混合使用 npm/yarn 安装依赖”。并且我会建议任何准备引入 coding agent 的项目组，第一步就做依赖管理器统一，否则每个 Agent 都有可能在这上面摔一跤。
3.3 lock 文件版本冲突：别让Agent当“仲裁者”
还有个细节是关于^版本符号和 lock 文件的关系。老项目里 package.json 通常写了"lodash": "^4.17.20"，lock 文件锁的是 4.17.21。如果 Agent 单纯为了修复一个 bug 去升级依赖，它可能直接把版本改成^4.17.21，然后 lock 文件就会产生一个 diff。
有人觉得这没问题，但在我处理的项目里，任何 lock 文件的改动都需要走单独的依赖升级流程，不能混在业务代码提交里。因为一旦升级丢失了某个间接依赖的固定版本，后续部署环境的兼容性就可能出现只在一台机器上复现的神奇 bug。
所以，我会给 Pi agent 设置一条行为边界：除非任务明确是“升级某某依赖”，否则不允许修改 package.json 和 lock 文件；如果它确实需要依赖变更，先提方案，由我手动执行安装命令。虽然这多了一道工序，但比事后排查一个下午要轻松得多。
4. 装修事故No.3：Agent的“经验主义”输出，总是带私货
4.1 Pi agent的“过度完成”：做的比要求的还多
Pi coding agent 这类工具，在主观能动性上确实比早期的 AI 辅助工具强很多，强到很多时候会“过度完成”。装修师傅给你装个吊灯，顺手把客厅开关面板也换了，你觉得这是贴心还是添乱？
有一次我让 Agent 修复一个登录页面的表单校验 bug，它修完之后，顺手给整个表单加了autocomplete属性、调整了错误提示的文案，还重构了提交按钮的加载状态逻辑。每一项单独看都不算错，但合在一起，就变成了一次我本来不需要承担的回归测试范围和 UI 走查成本。
我现在对 Agent 的任务描述都会加上一句“只做任务描述要求的事，如果需要动其他代码，在响应末尾单独说明”。这是一条非常有效的约束，能把 Agent 的自由发挥控制在“提醒”而非“行动”的层面。它如果发现了另一个潜在问题，会写进工作总结里，但不会主动改代码。这才是我要的协作姿态：它是我的施工队，不是我的产品经理。
4.2 不存在的“常识”：Agent对业务隐性规则的漠视
用 Pi agent 越久，我越清楚地体会到一件事：它非常懂代码的通用规则，但完全不懂我们这个具体项目的业务规则。
有次它帮我重写一个订单状态更新函数，延续了老代码的逻辑，但悄悄去掉了里面一个看起来“多余”的缓存清理调用。它认为那行代码和更新订单状态无关，是历史遗留的死代码。但它不知道的是，这个项目当时的并发设计有问题，那行缓存清理是在用一个很丑陋的方式，规避另一个模块读脏数据的老 bug。Agent 把这行删了之后，线上订单列表偶发地出现了状态显示滞后。
这件事给我了一个血泪教训：对于任何老项目里的“看似多余代码”，不管是对人还是对 Agent，都必须先搞清楚它的存在意义，再决定要不要删。我现在要求 Pi agent 在删除任何非本次任务引入的代码行之前，必须把这行代码加进一个“待确认删除清单”，由我来判断。
4.3 生成测试代码时的“假阳性陷阱”
最后一个经验主义的问题，是 Agent 写测试代码时的“自证清白”。Pi agent 帮我补单测时，它写的断言往往恰好就是用它的实现逻辑推出来的结果——也就是说，它用自己的代码验证它自己的逻辑，而不是用一个独立的业务预期来验证行为。
举个具体的例子：我让它给某个计算折扣的函数补测试，它会先想一个实现方案，然后预期值直接照着这个方案手算一遍写进断言。这听起来没问题，但实际上等于把同一个错误逻辑复制了两份。真正有效的测试，应该基于独立推导出来的期望值，而不是实现逻辑的复述。
我现在会要求 Agent 在写测试时，把“预期值的业务计算过程”写在断言旁边，然后我自己抽查几条边界数据，手动算一遍验证。好消息是，当我明确要求“用独立业务口径推导期望值”之后，Pi agent 生成的测试质量确实有可见提升。
5. 当Agent在毛坯房里迷路：定位问题与“无头苍蝇”模式
5.1 排查链路断裂：Agent只看到症状，找不到病根
如果说前几章聊的是施工质量，那这一章的坑是施工方的“诊断能力”。毛坯房装修踩坑，最怕的不是工人手艺不好，而是工人只会告诉你“这里不平”，却说不清是地基沉降还是墙角填充物隆起。
有一回项目里一个定时任务经常崩溃，日志里报的是TypeError: Cannot read properties of undefined (reading 'id')。我让 Pi agent 分析这个问题，它把报错行周围的代码翻了个遍，给我分析出三个可能原因，还按概率排了序。听起来很合理对吧？但它没有继续做一件事——去查这个定时任务的数据是从哪个上游接口拉的，那个接口最近有没有改过字段名。
结果真正的原因和它的三个猜测全不沾边。上游服务的某个字段从id改成了objectId，因为老的缓存还留着旧数据，所以一半数据没事、一半数据崩溃。Agent 只盯着报错现场，完全没往数据源方向想。
从这次之后，我总结了一个排查任务的标准工作流，我也建议你把它写进自己的提示词模板里：
- 第一步：先要求 Agent 在项目全局搜索报错字段的所有来源，列出“可能产生该字段的业务路径”
- 第二步：让它顺着数据流的方向走一遍，而不是只盯着报错的那个函数
- 第三步：要求它给出“证据链”——每个猜测必须配一个搜索结果佐证，没有证据的猜测列为低优先级
5.2 Agent的“无头苍蝇”模式：越修越乱的死循环
有时候 Pi agent 不是不聪明，而是太容易陷入“无头苍蝇”模式。我观察到的触发条件通常是：任务描述里包含一个自身无法验证的目标。
举个例子：我让它“修复 Safari 浏览器下按钮点击无效的问题”。这问题本身我对它就没有提供足够的上下文——是事件绑定没生效？是 CSS 遮挡？还是 JavaScript 报错中断？Agent 只能靠猜。第一次它给了一个“可能是 z-index 问题”的修复；第二次它说“可能是 pointer-events 问题”；第三次它改成“建议引入 polyfill”。每一次它都相当笃定，但每两次修复之间，完全没有验证手段。
这不怪 Agent，是我给的任务本身没有给它“判断是否修好”的测试手段。在修复问题之前，我至少应该和 Agent 先对齐一个“验证方案”——比如手动复现步骤、单测断言、或者一个可执行的最小复现案例。有了验证手段，Agent 才可能在这间毛坯房里找到正确的方向，而不是到处敲墙。
5.3 让Pi agent带着“感应器”干活：把验证写进任务
我现在所有交给 Pi agent 的修复类任务，都会强制包含一个“验证标准”字段。它不是可有可无的废话，而是让 Agent 对着干活的“感应器”。
举个实际的例子：
- 任务：修复支付回调偶发丢失的问题
- 验证标准：本地启动服务后，用
curl连续发送 20 次模拟回调，每次都会在日志中打印payment result received且无未捕获异常
你看，交代了验证标准之后，Agent 的行为就变了。它不再只改代码，还会自己跑验证，因为它清楚“完成”的定义是什么。跑不过，它会继续改；跑得过，它才告诉你“可以了”。这比起我之前那种“改完了，你测测看”的交付方式，效率提升了不是一点半点。
6. 装修尾声：我总结的“毛坯房Agent协作清单”
6.1 一套可以直接抄作业的任务提示词模板
踩了这么多坑之后，我把“毛坯房装修”的场景沉淀成了一套固定的任务模板，每次交给 Pi agent 的 prompt 基本长这样：
背景：这是一个接手的老项目，技术栈是 xxx，仓库根目录有 AGENTS.md，开工前请先读它。
任务：只处理下面描述的一个问题，不要顺带重构或改动无关代码。
问题描述：请复述一遍你理解的问题现象，方便我确认我们没有理解偏差。
验证标准：完成后如何确认这个任务做对了？请列出可执行的验证方法。
禁区：不要修改 package.json 和 lock 文件；不要重排已有代码格式；涉及删除代码时，先列清单。
输出要求：用中文回复，列出每个改动的文件名和简要说明。
这套模板下来，Pi agent 在我这个毛坯房项目上的表现，明显从“自由艺术家”变成了“听指挥的施工队”，效率和质量都稳了一个档位。
6.2 Plan模式比直接改代码更省时间
很多人用 coding agent 时喜欢让它直接动手改，觉得这样快。但根据我这段时间的经验，在毛坯房里直接动手改，大概率会让你进入返工循环。
我现在更倾向于让 Pi agent 先进入“plan 模式”，让它先给我一个方案，我确认了再执行。这种方式对于老项目尤其重要，因为老项目的水下成本高，任何一个“没想到”都可能让我多花两个小时去排雷。方案先行，相当于让它先画施工图，我再审图纸。虽然多了一轮交互，但整体时间反而是省的。
尤其是当任务牵涉到多文件修改、依赖调整、或者数据流方向改动时，plan 模式几乎是我唯一的选择。省下的返工时间，比那几十秒生成方案的时间多得多。
6.3 最后，说一点我对 Pi coding agent 这类工具的观察
用了一段时间 Pi agent 之后，我最大的体会是：这类工具的真正价值，不是替你写代码，而是替你加速“验证想法”的速度。它不会比你更懂你的业务，也不会比你的团队更懂历史包袱，但它可以在你画好图纸之后，高效地完成一块块具体的工序。
“毛坯房装修”这种老项目改造场景，最大的敌人其实是模糊和不确认。而只要你把上下文给足、边界画好、验证标准定明白，Pi agent 就能成为一支相当靠谱的装修队。毕竟它还不会像人一样，干到一半跟你说“这墙我不敢拆，得加钱”。
