上个月我接了个需求原始描述只有两句话做一个内部工具用户能登录、能提交表单、能看历史记录。看着需求简单实际从零到能跑通用了整整两周。整个开发过程我没写几行代码全程靠 pi agent 在终端里驱动从项目初始化、建表、写接口、调页面到测试、修 bug、补文档一步步把“毛坯房”装成了能住人的房子。这篇文章不打算写成一个标准教程更像一份装修踩坑记录哪些坑我替你趟过了哪些决策回头想想是错的哪些习惯如果从一开始就有能少熬好几个夜。如果你是第一次听说 pi agent或者刚下载完还没想清楚拿它干什么又或者你已经用它写过几个 demo 但一碰真实项目就各种不对劲这篇应该能帮你省点时间。我尽量把命令、配置和踩坑现场都还原出来你可以照着走也可以拿来当避坑清单。1. 开工之前认清 pi agent 能干什么别把它当魔法棒1.1 pi agent 到底是个什么东西先对齐一下概念。pi agent 是一个跑在终端里的编程代理coding agent不是 IDE 插件也不是那种聊聊天帮你补全代码的 AI 助手。你把任务用自然语言描述给它它会自己去读项目文件、分析代码结构、修改文件、执行命令、看运行结果再根据结果决定下一步做什么。整个过程是一个“理解—行动—观察—再行动”的循环而不是一次性给你吐一段代码就完事。我第一次用的时候最大的误判是以为它是个更聪明的 ChatGPT把需求甩过去等结果就行。实际不是。它更像一个刚入职、学习能力很强但缺乏项目背景的实习生。你得给它项目上下文告诉它技术栈是什么、代码放在哪、要做到什么程度、哪些约束不能碰它才能干出像样的活。你要是只说“帮我做个登录功能”它大概率能写出来但可能用了你没打算用的框架或者把整个项目结构都改了。跟 Copilot 这类补全工具比pi agent 的优势在于它能处理“一整块任务”。补全工具是你写一行它补三行整体架构还是你脑子里的pi agent 是你把“做一个带分页的用户列表页”整个任务扔出去它自己去建组件、写接口、处理 loading 状态、把样式调好。劣势也很明显它干的活越多越需要你把控方向否则装修到一半发现墙砌错位置了返工成本比从头写还高。1.2 毛坯房比喻这个工具适合干什么我把用 pi agent 做项目比作毛坯房装修是认真想过的。毛坯房的特点是墙是墙、地是地水电管线都在但没有任何居住功能。一个空目录加一个 git 仓库就是数字世界的毛坯房。pi agent 负责的是装修但设计图纸、预算上限、验收标准都得你自己定。你不定它就按自己理解的默认值来最后交付的可能是你根本没想要的风格。那它适合用来干什么适合从零搭一个 CRUD 应用、写后端接口、做数据迁移脚本、写单元测试、重构一个模块、补充文档和注释。适合你有明确技术栈和经验但不想浪费时间在重复性编码上想把想法快速落地成可运行的原型。不适合你对需求都还没想清楚指望 agent 帮你把需求也一并想了。它不是产品经理。不适合项目极其冷门、依赖全是小众库、网上资料稀少。agent 的训练数据里没有足够的样本它只能瞎猜然后你帮它擦屁股。我踩的第一个坑就是把一个“还没想清楚”的需求直接扔给 pi agent。结果它给我设计了一个带角色权限、多租户、消息通知的系统而我只想要一个能记录“今天做了什么”的表格。所以现在我的习惯是动工之前先把需求在纸上捋一遍哪怕只是几行要点也要让需求边界清清楚楚。1.3 装车清单环境准备与最小化验证开工之前先把工具链备齐。我是 macOS 环境用的终端是 iTerm2shell 是 zsh。pi agent 安装本身不复杂去官网或者 GitHub releases 页面下载对应平台的安装包或安装脚本按 README 里的说明装就行。如果你用的是 Windows建议优先考虑 WSL2 环境别直接在 PowerShell 里硬扛很多路径、权限和脚本兼容问题在 WSL 里会少很多。装完之后别急着上大项目先做一个最小化验证确认三件事pi agent 能正常启动能读取当前目录下的文件。它能在项目目录里新建文件、修改文件。它能在终端里执行命令并读到输出。我当时的验证方式很原始在一个空目录里让 pi agent 初始化一个 Node.js 项目创建 index.js在控制台打印 Hello World然后运行它。如果这一条链路能跑通说明它的“读取—修改—执行—观察”闭环是正常的可以开工了。如果连这个都跑不通先别急着排查业务问题把环境问题解决干净再说。注意pi agent 的版本迭代很快不同版本在参数、权限配置上可能有差异。我下面涉及的命令和配置项在不同版本里可能略有出入以你当前使用的官方文档为准。2. 水电进场项目初始化与工程规范的坑2.1 别让 agent 自己猜技术栈毛坯房装修的第一步不是刷墙是定水电点位。项目的第一步也不是写功能是定技术栈和目录结构。这一步如果交给 pi agent 自由发挥基本等于把装修风格的决定权交给了一个没见过你家的包工头。我第一个项目就是这么翻车的。我告诉它“做一个待办事项应用”它自作主张选了个 Express SQLite 的组合。不能说错但这个选择意味着我后续得手动维护原生 SQL、自己处理数据库连接而我想用的其实是一个带 ORM、带自动迁移的框架。等发现的时候基础代码已经写了一千多行推倒重来又舍不得。后来我学乖了在项目根目录放一个 AGENTS.md 文件把关键决策写清楚。这相当于给 pi agent 的一份“项目说明书”。每次它开始干活之前我先让它读一遍这个文件。文件里我一般写这些内容# 技术栈 - 后端Node.js 20 Fastify Prisma PostgreSQL - 前端React 18 Vite Tailwind - 禁止引入未在 package.json 中声明的依赖 # 目录结构 - src/api 路由和控制器 - src/services 业务逻辑 - src/models 数据模型 - tests 测试文件与 src 结构对应 # 代码风格 - TypeScript 严格模式 - 函数命名使用驼峰组件命名使用 PascalCase - 错误处理统一抛 HttpError由全局中间件捕获 # 约束 - 不修改 src/api 之外的文件来实现业务功能 - 所有数据库变更必须通过 Prisma migration这个文件不需要写得多长但必须把“不能动的底线”和“必须遵守的规范”写清楚。pi agent 是服从性很高的工具你给它明确的规则它就会照做你不给它就会自己发明规则。2.2 依赖拉不下来先分清是网络问题还是配置问题项目初始化的第二个坑出现在拉依赖环节。npm install 跑了十几分钟还在转圈最后报一堆 ETIMEDOUT。当时我第一反应是网络问题换了几个公共 npm 镜像也没根本解决。折腾半天发现pnpm 的全局存储路径配置得不对导致它在反复重新下载同一个包。这个坑给我的教训是遇到依赖安装慢先别忙着换源按顺序排查三层包管理器本身配置是否正确缓存路径、存储路径、registry 地址。是否存在版本冲突导致包管理器在反复解析依赖树。网络链路是否真的慢用小体积包单独测一次安装耗时。用一个临时目录验证最直接新建空目录执行 npm install lodash如果秒过说明基础链路是通的如果也卡死那才是网络层面的问题需要配置更稳定的镜像源或调整超时参数。这个排查顺序能避免在错误的方向上浪费大量时间。另外提一句pi agent 在拉依赖失败后的第一反应往往是“重试”。它不会主动去分析是不是源的问题也不会去看配置。所以你最好在 AGENTS.md 里写一条遇到依赖安装失败先检查 registry 配置和网络不要盲目重试。否则你会看到它反复执行同一条命令像个复读机。2.3 建仓打 tag任何时候都能回退到毛坯状态装修最怕什么最怕改到一半发现方向错了想回到动工之前结果墙已经拆了。代码项目也一样所以我强烈建议在 pi agent 第一次动手之前先初始化 git 仓库并打一个 tag比如 v0.0.0-init。这个操作本身很简单但它给了你一个“时间机器”。pi agent 改代码的速度非常快快到你反应不过来它已经把某个文件改成了你不认识的样子。有 tag 在手随时可以 git reset --hard 回到初始状态重新下指令再让它干。没有这个基线你只能靠 CtrlZ 或者凭记忆手动还原效率极低且容易遗漏。我还习惯在每次阶段性任务完成之后打一个 tag 或至少 commit 一次。pi agent 执行的是一连串操作我们要的是“每一步都可回退”而不是“最后成功了一次”。这一步在我的整个项目过程中帮了大忙至少三次在改动失控后我都能干净利落地回到上一个稳定点。3. 硬装阶段核心功能开发与 Agent 工作流的真实用法3.1 任务描述的四要素目标、约束、验收、参考等环境就绪、规范确立之后才进入真正的硬装阶段——让 pi agent 开始写业务代码。这个阶段最关键的技能是怎么把需求翻译成它听得懂的任务描述。我刚开始给 pi agent 下任务的时候习惯用口语描述“帮我写一个用户注册接口手机号验证码那种。”结果它给我写了个用邮箱注册的接口验证码是假的只是 console.log 打出来。不能说它写错了只能说我没说清楚。后来我把任务描述固定成四个部分目标做什么、约束在哪些限制下做、验收怎么算完成、参考可以参考哪些文件或接口风格。写成一个模板大概是这样的目标在 src/api/auth.ts 中新增一个注册接口 POST /api/register 约束 - 使用 Prisma 操作数据库 - 手机号必须是 11 位数字校验失败返回 400 - 密码使用 bcrypt 加密存储 - 不修改 src/models 下已有的模型文件 验收 - 运行 npm test 中 auth 相关测试全部通过 - 使用 curl 请求接口传合法参数返回 201非法手机号返回 400 参考 - 参照 src/api/login.ts 的现有代码风格这种描述方式看起来很啰嗦但它能显著减少 pi agent 的“自由发挥空间”。它自由发挥的空间越小你后面返工的成本就越低。说白了就是把装修图纸画清楚再让工人动工。3.2 上下文管理别让 agent 忘记它自己改过什么pi agent 能处理的任务长度是有限的越长的对话上下文越容易出问题。我在项目进行到第二周时发现pi agent 开始“失忆”——它明明十分钟前改过一个函数重新提问时却说没有改过或者给出了一个基于旧代码的建议。这个问题的根源是上下文窗口被撑满了前面的信息被截断或丢弃。解决思路不是去增大窗口而是把关键信息“固化”到文件里。我的做法是在项目里维护一个 PROGRESS.md 文件记录每天完成了哪些模块、改过哪些文件、下一步打算做什么。每次让 pi agent 开始新任务之前先让它读这个文件。这样即使会话断掉、从头开一个新会话它也能通过文件快速恢复上下文。还有一个习惯值得养成一个会话只干一件事。想让它加接口就只聊加接口想让它在同一批文件里改样式另开新会话。混在一起聊不仅上下文消耗快还容易让 agent 产生任务优先级误判把 A 任务做到一半突然去干 B 任务。3.3 人工审查agent 写代码人做验收这是我最想强调的一点pi agent 写出来的代码本质上是初稿。它可能功能正确但不代表风格良好、边界处理完备、没有隐藏问题。你必须是那个“最后拍板的人”。我建立了一个简单的代码审查清单每次 agent 完成一个任务我不急着让它做下一个先对照清单检查审查项具体内容功能完整性主路径是否走通是否覆盖了失败分支边界处理空值、超长输入、并发请求是否处理安全性用户输入是否有校验SQL 是否有注入风险异常处理是否有 try-catch 包裹外部调用错误是否被记录可维护性命名是否清晰是否有重复代码是否留下调试日志拿实际的例子说。有一次让 pi agent 写一个文件上传接口它在能跑通的路径上一切正常但只要上传空文件就报 500而且没捕获错误就直接抛给前端。功能“能跑”但离“能用”差远了。如果没有审查清单这种问题会一直藏在代码里直到线上出事故。提示审查不是重新写一遍而是像验收精装房一样逐项对照标准看。发现问题就让 agent 改直到满足清单为止。人盯结果agent 盯实现角色要分清楚。3.4 实测记录一个增删改查模块的全过程复盘写点具体的。我项目里有个“项目管理”模块要求很基础项目列表、新建项目、编辑项目名称、删除项目。听起来毫无难度但这是最能体现 agent 工作流价值的场景因为逻辑简单、链路完整可以完整观察它从接到任务到交付的全过程。我下发的任务描述包括技术栈约束Prisma Fastify、路由路径/api/projects、字段定义id、name、createdAt、updatedAt、验证规则name 必填且不超过 50 字、验收标准相关测试通过。第一轮它很快生成了 Prisma model 和迁移文件然后写好了路由和 service。看起来不错的初稿但我在审查时发现新增和编辑接口没有做 name 长度校验直接入库。我把这个反馈给它让它补上。第二轮它补上了校验但又引入了一个新问题删除接口在项目不存在时返回 404 的逻辑写错了写成了返回 success。我继续反馈让它修正。第三轮功能逻辑全部正确了但它又往代码里塞了一堆没用的注释。我追加了一条规范“不要添加无意义的注释代码本身要表达意图。”它把注释清干净了。这时候测试也过了我才算验收通过。整个过程用了不到四十分钟其中有十分钟是它在跑测试。如果是我自己写不算测试时间大概也得两三个小时。这就是 agent 的价值所在——但不是“完全托管”的价值而是“你出图纸、它砌墙、你验收”的分工价值。4. 软装阶段调试、测试与迭代的踩坑实录4.1 测试是装修图纸先画图纸再动工硬装结束了房子能住了但还不能急着入住得做竣工验收——在软件项目里就是测试。这个环节的坑在于让 pi agent“顺便写个测试”和“先写测试再做功能”效果天差地别。我最早是让 agent 先写功能再补测试。结果是测试确实写了但都是那种“断言代码能运行”的空壳测试覆盖率倒是好看一点实际问题都查不出来。因为 agent 写功能时它知道代码内部逻辑写测试时会不自觉地避开自己没实现好的分支。后来我换了个顺序每个任务描述里先写测试要求再写功能要求。让 agent 先基于需求文档写测试用例然后再去实现功能。这样测试就是“图纸”功能是照着图纸施工而不是“房子盖完再画图纸”。实测下来这种方式能让 agent 自己发现不少问题因为它写测试的过程就是重新理解需求的过程理解不到位的地方在测试里就会暴露。我一般要求测试里至少覆盖三种场景正常输入、异常输入、边界条件。比如一个删除接口正常场景是删除存在的项目异常场景是删除不存在的项目边界场景是删除已被其他表引用的项目。三个场景都能测过这个接口才算合格。4.2 报错速查表依赖冲突、路径问题、环境变量、端口占用开发过程中难免遇到各种运行时问题。pi agent 擅长修代码但遇到环境层面的问题它往往比较迟钝。我把这段时间遇到的典型报错整理成了一个速查表供大家参考报错现象常见原因处理办法module not found依赖没装或路径大小写不一致先确认包是否在 package.json再确认 import 路径与实际文件名完全一致EADDRINUSE端口被占用用 lsof -i :端口 查占用进程结束进程或换端口DATABASE_URL 未定义环境变量没加载检查 .env 文件是否存在确认加载顺序别把 .env 提交到 git类型错误string 不可赋给 number前端参数未做类型转换在接口边界做参数校验和类型转换别把字符串直接传进数值逻辑测试超时请求没有 mock真实调用了外部服务测试环境统一用 mock禁用真实网络请求这些问题的共同特点是它们不是逻辑错误而是“环境上下文”错误。pi agent 面对这类报错时倾向于反复修改业务代码来碰运气但正确做法是先查环境再改代码。我在 AGENTS.md 里专门加了一条遇到环境类错误先执行诊断命令比如打印环境变量、查看端口占用把结果贴出来再决定怎么改禁止盲目改代码。4.3 迭代策略一轮改动只做一件事项目后期我开始追求效率让 pi agent 一次性改好几个模块改完接口再顺便把前端页面调一下再把文档更新了。结果就是改动之间互相影响测试挂了不知道是哪个改动导致的代码回退也不知道该回退到哪个 commit。这个教训让我总结出一条迭代纪律一轮改动只做一件事。哪怕这件事很小比如只改一个接口的返回格式也要经历“下任务—实现—审查—测试—提交”的完整循环。改完一个跑一遍测试提交一次再开始下一个。这么做的好处是问题定位极其清晰。测试挂了看一眼最后一个 commit 改了什么基本就能锁定原因。而且 pi agent 在单任务模式下表现更稳定它不需要在多个目标之间切换反而更容易把当前任务做好。我知道有人会觉得这样太慢但实测下来单任务循环的总耗时反而比多任务并行更短。多任务并行省下的时间全都在排查问题、回退代码里加倍赔回去了。5. 入住之后复盘与长效维护的几条经验5.1 收尾验收让 agent 补文档、清理、做最后的自检功能全部完成后别忘了收尾。这一步相当重要直接决定了项目是“能跑”还是“能交接”。我做收尾的顺序是先让 pi agent 跑一遍完整的测试套件确认所有测试通过然后生成一份 README包含启动方式、环境变量说明、目录结构接着更新 PROGRESS.md把最终状态记录下来方便以后接手的人包括未来的我自己快速了解项目最后清理掉项目里的调试日志、临时文件和没有用到的依赖。这里有个小技巧在让 pi agent 清理依赖时不要直接说“把没用的依赖清理掉”它会根据自己记忆里的代码来判断。更可靠的方式是跑一遍 lint 和 build看有没有引用缺失的包或者直接用 depcheck 之类的工具扫描。让数据说话而不是让 agent 凭印象做事。5.2 三张备忘清单开工前、开发中、收尾时各一张我把这次的经历沉淀成了三张清单每次用 pi agent 开工我都会过一遍开工前项目技术栈是否固定并写入 AGENTS.md目录结构是否有明确约定git 仓库是否初始化并打了基线 tag依赖环境是否验证过最小安装链路开发中每个任务是否包含“目标、约束、验收、参考”四要素是否每轮改动只做一件事是否每次改动后都跑了测试并提交是否定期更新 PROGRESS.md收尾时全部测试是否通过README 是否完整临时文件和调试代码是否清除依赖是否精简并验证可正常构建这三张清单一开始觉得繁琐但用习惯了反而轻松因为每一张都是在帮 pi agent 减少自由发挥空间也是在帮我自己减少返工次数。5.3 给新手的三个建议如果你正准备开始用 pi agent 做自己的第一个真实项目我给你三条建议。第一先拿一个玩具项目练手。不要一上来就重构老项目更不要直接拿生产环境测试。找个需求清晰、逻辑简单的小工具从头到尾走一遍完整流程体验一下“下任务—反馈—修正—验收”的节奏建立手感。第二学会从小处入手但把话说完整。一个任务拆得越小成功率越高。小任务不是让你每次只说一句话而是让你把一句话能讲清楚的事情用足够的背景信息包裹好。背景信息多一点agent 的发挥就更稳一点。第三永远保留人工审查这一步。这点我再强调都不为过。pi agent 是一个效率工具但它不是质量保障。质量保障是你自己的审查清单、你的测试用例、你的验收标准。工具有多强不代表交付物就有多好关键还是看你怎么用它。写在最后说实话用 pi agent 做这个项目的经历比我预想的要曲折得多。刚开始我把它想像成一个能听懂人话的编程机器人结果发现它更像一个需要明确指令和严格验收的施工队。毛坯房装修踩的坑大多不是因为“工具不够聪明”而是因为我作为“甲方”没有把需求、边界和验收标准想清楚。现在我再拿到新需求第一件事已经不是打开终端叫 pi agent 开工了而是先把需求在文档里写明白要做什么、不做什么、怎么算做好。这个过程看起来跟写代码无关但恰恰是它决定了后面 pi agent 是帮你干活还是帮你添乱。如果你正准备踏上这条路我希望这篇记录能帮你少踩几个坑。工具会越来越强但这套“先定规范、再动工、全程验收”的工作方法什么时候都不过时。
