poteto
@poteto
The Complete Guide to pstack Pt. 2
在 X 上查看更新于 2026-10-04
poteto
@poteto
The Complete Guide to pstack Pt. 2
在 X 上查看
在上一篇里,我讲了为什么验证是我用 agent 做一切事的地基,也讲了怎样着手创建你自己的验证 skill。最关键的一课是,agent 要是验证不了自己的工作,别的都是空谈。你还是那个瓶颈,一整天都得给 agent 当保姆。
我在写一份 pstack 指南!这是第一篇。 https://x.com/i/article/2094151284949688320
原帖:@poteto
但验证跑通以后,下一个问题就来了:你到底要怎么弄清楚该做什么?
这篇我会带你走一遍,我怎样用 pstack 做调研、规划、原型和架构。我每个月往生产环境发几千个 PR,代码质量还能保持得极高,靠的就是这套工作流。

八月收官,2,462 个 PR 进了生产环境
想当年,也就是 2024 年那会儿,要改系统里的任何东西,你都得先读够它的代码,建立起心智模型,弄清里面在发生什么。看代码库有多大、多复杂,这一步可能要花几个小时,甚至几天、几个月。改动小的话,你也许只需要看懂一个小子系统的局部,就能应付过去。可要是重构核心,你多半得掌握整个系统怎么运转的心智模型,才能把重构做对、做好。
agent 显然拆掉了这道门槛。现在改系统非常容易,给 agent 一句提示词,它就去改了,不管你对代码懂得多还是少。但要让代码质量和用户体验保持在高水平,依然很难。如果你本来就不是领域专家,不知道该看哪里、该问什么,那就更难了。
虽然 frontier 模型(当下最前沿的那批大模型)已经非常能干,我还是一再看到两种失败模式:
这两个问题是相关的。能不能用好 agent,归根结底要看你能不能事先往它的上下文窗口里装进高质量的上下文。不做这一步,当然也能写出能跑的代码。但我发现,如果我先下了功夫,给 agent 备齐把活干好需要的一切,结果和质量都会好得多。
frontier 模型写代码已经非常强了。以前用老模型,我可能会在提示词里把要它做什么写得非常具体,几乎是事无巨细地管着它。最新的模型写代码却已经比你我都好。所以我想拿捏好一个分寸:既告诉 agent 我要达到什么目标,又给它自由,让它用我可能没想到的办法去解决。
这就是监督比你聪明的人这门手艺。代码库不是你自己写的,而整个代码库的心智模型,人已经没法全装进脑子里了。
我爱用的一个技巧是写间接的提示词。我不直接告诉 agent 我到底要什么,而是想办法引它自己说出来,用它自己的话。
比如有人在 Slack 上报了问题,我常常会先让 agent 读一遍讨论串,用它自己的话把问题复述出来,然后再做别的。
举个例子,我可能会这么说:
/poteto-mode 读一下这个 slack 讨论串。用你自己的话、用大白话复述一遍,你觉得根本问题是什么
这样做有三个好处:
第一,它逼着 agent 把一段嘈杂的对话,压缩成一份有条理的问题陈述。第二,有误解的话,我能马上发现。如果 agent 揪住讨论串里一条误导人的线索不放,我能在它写任何代码之前,很快把它纠正过来。
第三,我没有先说出自己的假设和猜想,也就不会把它带上岔路。我的假设可能是错的,也可能限制 agent 本来能做到的事。
建立心智模型
和比你聪明的人共事,很重要的一环是让 agent 用你听得懂的方式复述。/teach 的灵感就来自这里。这个 skill 帮 agent 用直观的方式把事情讲给你听。每当我需要确认 agent 做的事在我看来说得通,我就用它。
/how 追踪运行时的机制。你用 /how 提问时,agent 会先评估这个子系统有多复杂。如果子系统横跨多个目录或服务,它会并行派出几个负责探索的 agent,用 Grok 这类又快又省的模型来跑。
/how 虚拟化是怎么实现的?
/why 调查动机和意图。代码能告诉你发生了什么,却很少告诉你别人为什么这样写。你运行 /why 时,pstack 会并行到多个来源里查历史证据:Git 历史和 PR 评审意见、Linear 工单、Notion 设计文档、Slack 对话、Datadog 监控、Sentry 报错、代码血缘,还有分析数仓里的事件。
/why 我们为什么还卡在旧版的 node.js 上?

每当我想让 agent 复述一件事,让我更能看懂、也更信得过它的工作,我就会用 /teach。
/teach 给我讲讲,你为什么这样实现,而不是 <另一种做法>。你做了哪些取舍,为什么?
实际用下来,我还发现 /teach skill 做的调研不光对人有用,对 agent 也有用。哪怕是最新的 frontier 模型,我发现它们总体上还是常常很笃定地下结论。它们既不拿数据支撑,也没真去读代码,可要弄懂东西怎么运作、建立心智模型,那些代码是必须读的。这一点也跟 harness(模型外面那层调工具、管上下文的程序)的质量有关。所以,让 agent 教你它要做什么、为什么这么做,最后也帮到了它自己。
从历史中学习
我的很多项目要跨好几次对话。比如几个月前,我在修大家在 Cursor 里报的虚拟化 bug 和性能问题。我发现每开一个新对话,基本都得从头再来,把 agent 之前解决类似问题时攒下的丰富上下文重新建一遍。
我意识到,过去的对话记录往往是丰富上下文的金矿。pstack 自带 /recall skill,能从聊天历史里把你最近的上下文找回来。这样即使是新开的 agent,也能拿到需要的上下文,很快回到状态。
/recall 我昨天在虚拟化上做的工作,然后读一下 slack 上这份 bug 报告
我就是靠 /teach、/recall、/how 和 /why,让自己对代码库的心智模型保持最新,并压缩成我容易理解、也容易记住的样子。而且,这对 agent 也有帮助!
弄懂了问题,解法又该怎么写清楚?

在我看来,大多数带规划模式的 harness,都爱把实现细节写得过细,别的却写得太少。所以我在 pstack 里半开玩笑地说过「我不相信规划」。实情是我也做规划,只是用代码来做。
有些类型的工作,比如写给别人用的共享代码或包,我非常推崇 readme 驱动开发。要是你没听说过,这是早年流行过的一种开发方法,第一步就是写好 readme。它逼你先从开发者体验出发:先向一个假想的用户介绍 API,再倒推出实现和架构。
比如我做 Dune 的时候(Dune 是我们内部自研的桌面应用客户端框架),先给它写了一篇 tutorial,想体会一下用它搭应用是什么感觉。至少我是这么打算的。可要让 agent 写出点像样、读得下去的东西,实在太费劲了。所以我只好先花点时间磨刀,做出了 /technical-writing skill。
没有 /technical-writing skill 时写出的第一版 readme,读起来很痛苦,因为它把不同的目标混在了一起。同一份文档既想当 tutorial,又想当 how-to 指南、讲架构的 explanation 和 API reference。通篇还是你熟悉的那种 AI slop(AI 写出来的空洞套话),外加矫揉造作的文风。

/technical-writing 用 Diátaxis 框架把文档分成四种不同的模式:
它还会用上 /unslop,所以写出来的文档非常好读。
这样写计划很有帮助,因为它还给了 agent 一个具体、明确的目标,agent 可以拿它来检查自己的工作。当然,你也更容易看懂 agent 到底要做出什么。
pstack 的很多 skill 在设计阶段会叠加起来用。比如:
(1)/recall 我过去 7 天修虚拟化 bug 和性能问题的工作。用 /how 和 /why 弄清我们现在的虚拟化实现是怎么工作的。(2)然后用 /poteto-mode 的规划和 /technical-writing,设计一个新的虚拟化引擎,从根本上杜绝闪烁和抖动。我们先写一篇 tutorial,讲我会怎么用这个新包给 React 应用做虚拟化。(3)写完计划后,/teach 给我讲讲,并向我证明为什么这套新方案比我们现在的引擎更好
这里的技巧,说到底是把有意思、内容丰富的上下文引出来,让 agent 能像你一样看问题,而不是只看到一小片:

做规划时,我最常看到的两个错误是:
以前人写代码的时候,我们常常围着设计文档协作。这些文档讲高层架构、考虑过的备选方案、取舍,以及各种特别的实现说明。这类文档往往要改好几轮,设计才最终定下来。
有了 agent,设计文档那套仪式可以省掉。但我常看到有人犯这个错:agent 交回来的第一样东西,照单全收。用 pstack,我们可以换个做法,用并行的 agent 把「量两次,剪一刀」做到极致。
具体做法是用原型 playbook。
在 pstack 里,playbook 不是 skill,而是 /poteto-mode 里面的参考文件。这些 playbook 会根据你手上任务的类型按需加载(这样省 token)。这 23 个 playbook(截至 0.15.0)各自写着一套我做任务时用的工作流。
和 skill 不同,playbook 是 /poteto-mode 的一部分,agent 会自动使用。比如:
/poteto-mode 给新的下拉菜单做几个原型方案 /poteto-mode 修掉这个 bug /poteto-mode 评估一下这次 skill 改动
原型是我最喜欢的 pstack playbook 之一。它让你朝同一个目标多试几次,也帮 agent 推理出哪个方案最好。这不光适合做视觉原型,也适合给功能、bug 修复等等,各做几种不同解法的原型。
/poteto-mode 给 <功能需求> 做几个原型方案。用 /control-app*,录视频或截图给我看,我来挑
*注:/control-app 就是我们在第一篇里创建的验证 skill
给视觉改动做原型时,agent 会在你的应用里或者一个临时目录里,搭几个用完就扔的草稿。如果要测的是某个 UI 交互,它会把两三个变体放在一个简单的切换开关后面。然后它用 /control-app skill 操作这个交互,给每个变体截图,并测出实际的耗时或布局。
原型就是规划,只不过是用代码来规划。它让 agent 能自由探索问题空间,也给了它机会,拿出你自己想不到的东西,让你眼前一亮。有了原型,agent 能用实证回答自己的问题,不用干等我发话。
给大改动做架构
在 agent 时代当工程师,我更该把时间花在架构上,花在选对数据结构上,花在想清楚我做的这些系统要怎么配合上。实现细节交给我的 agent 去填。

pstack 自带的另一个好用的 skill 是 /architect。它把设计分成几个界限分明、按规矩走的阶段:
这里的重点,是给 agent 一个自成一体的小循环。在这个循环里,它能把来自不同模型族的几套竞争设计,综合成一套最优方案。它还要保持严谨,一旦实证表明自己想出的架构是错的,就不怕把设计扔掉。如果同一种变通写法出现在互不相干的调用处,或者类型上不得不用 any、强制类型转换这类逃生舱,这就是架构错了的实证。
/architect 这个新的 <功能需求>
这里最大的教训是,用 /poteto-mode 的原型和 /architect 拿代码来规划,效果要好得多。
这也是为什么我从来懒得对抽象的计划做对抗式审查。agent 会开始臆想各种理论上的风险,编出复杂的边界情况,去防那些永远不会发生的问题。计划还停在抽象阶段时,别在上面用力过猛。让 agent 自己去做原型、验证自己的工作,用这些去回答悬而未决的问题。

pstack 虽然没有规划 skill,但确实带了一个多阶段规划 playbook。我一般在 agent 拿出一个让我满意的设计之后才用它,用来写一份战术层面的执行计划。
/poteto-mode 把这个设计写成计划
计划里的每一项任务,都围绕证明和验证来安排。这个 playbook 告诉 agent,光有测试还不算充分的验证。只有 agent 真的把代码跑起来,确认它能用,才算验证过。
每份计划都要过一道自动脚本,校验结构和格式。计划通过之后,就逐项执行。每个 PR 都很小、自成一体,也好审。
碰上真正的大项目(比如可能要花我一整周的那种),我有时会把计划临时提交进代码库,让其他 agent 知道这项工作还在做。但做完以后我一般会删掉,免得代码库里留下让人困惑的东西。我不觉得把计划一直留着有什么价值。
为了看清这些部分怎么拼到一起,我们来看三个具体的例子,看我怎么给这些工作流写提示词。
生产环境出了问题,根因又不清楚时:
/poteto-mode 调查一下后台工作进程为什么会周期性地超时失败。给我梳理一下我们已经知道什么、你用了哪些数据,以及你最好的几个假设。
agent 会去翻代码,并行查看指标和历史提交,然后给出它最有根据的推测,告诉你问题可能出在哪。
要引入一个其他模块都会依赖的新子系统时:
/poteto-mode 我们需要给外部 webhook 加限流。先 /architect 一下,有悬而未决的问题就用原型来回答。继续之前先让我看一下。
agent 会先摸清现有的 webhook 架构,再拉起几个分属不同模型的子代理,各出一套互相竞争的设计,拿一次性原型跑基准测试,最后产出一个干净、经过验证的接口。
要在很多文件上做一次复杂的重构时:
/poteto-mode 做一份计划,把我们整个 UI 库迁到 StyleX。把迁移拆成一个个小的、可验证的 PR。每个 PR 都要有自己的视觉回归测试,还要有跑起来实测的验证步骤。我要最终结果和原来 100% 一样,连 bug 也一样
agent 会把工作拆成互相独立的步骤,写一份可审计的清单,并把每个单元都准备好,确保它能构建、能验证、能安全合入。
如果你在 Slack 上我们报问题或提反馈的频道里见过我,大概也见过这几句经典台词:
# thread already has sufficient context/poteto-mode do it
/poteto-mode repro this with /control-app. if it repros on main, fix it and show me a video as proof中文大意:(讨论串里的上下文已经够了)/poteto-mode 动手吧。/poteto-mode 用 /control-app 复现一下,如果在 main 上能复现,就修掉,再给我一段视频作为证据。
这里讲到的很多 skill,/poteto-mode 已经会自动调用。所以绝大多数时候,你只管用 /poteto-mode,然后该干嘛干嘛去!
很多人拿 Plan Mode 来说服自己,相信 agent 会做对的事。但现实是,抽象的计划只会给你一种有进展的错觉。一份洋洋洒洒的长计划,看起来像是你和 agent 都很高产,但多半没什么实质内容。
pstack 给你的工具,能把彻底的调查、实证和严格的验证结合起来。这样做规划,和 agent 一起做工程就不再像赌博,而是变得可预测、可重复。
感谢阅读,第三篇敬请期待!