pstack 完全指南(二)

在上一篇文章中,我解释了为什么验证是我用 agent 做所有工作的基础,也介绍了如何开始创建自己的验证 skill。最关键的一点是:如果 agent 无法验证自己的工作,其他一切都无关紧要。你依然是那个瓶颈,一整天都会耗在盯着 agent 干活上。

https://x.com/i/status/2094457600259842065

可一旦验证机制真正运转起来,下一个问题就是:究竟该如何判断要构建什么?

https://x.ai/bot/plugin/9717366

这篇文章会完整介绍我如何使用 pstack 做研究、规划、原型验证和架构设计。正是这套工作流,让我每个月能把数千个 PR 发布到生产环境,同时依然保持极高的代码质量。

如何带好一个比你聪明的人

遥想 2024 年的旧时代,要对一个系统做任何改动,你首先得读懂足够多的代码,在脑中建立起它的运行模型。这个过程要花几个小时,还是几天甚至几个月,取决于代码库的规模和复杂度。改动很小时,或许只需局部理解一个小型子系统;但如果要重构核心部分,你很可能得理解整个系统如何运作,才能把重构做对、做好。

agent 显然消除了这道门槛。无论你对代码了解多少,只要给 agent 一段提示,它就能轻松修改系统。但要维持高水平的代码质量和用户体验,依然很难,尤其是当你并非领域专家,不知道该关注什么、该问什么的时候。

即使前沿模型已经非常强大,我还是不断看到两种失败模式:

  1. 需求描述不足或不清楚,导致它们无法充分理解你的意图。
  2. 它们缺少正确完成工作所需的上下文。

这两个问题彼此相关。能否用好 agent,取决于你能否为它的 context window 提供高质量的上下文。当然,不这么做也能写出可运行的代码;但根据我的经验,如果我事先把高质量完成工作所需的信息都提供给 agent,最终成果和质量会好得多。

用你自己的话说

前沿模型非常会写代码。面对旧模型时,我可能会非常具体地告诉它该做什么,几乎事无巨细地盯着;而最新模型的代码能力已经胜过你我。因此,我想找到一个微妙的平衡:明确告诉 agent 我希望实现什么,同时又给它足够的自由,让它用我没想到的方式解决问题。

这就是如何在一个并非由你亲手编写、复杂到人脑已经无法装下完整心智模型的代码库上,带好一个比你更聪明的人。

我喜欢用的一种技巧是间接提示。与其直接告诉 agent 我想要什么,不如设法让它自己说出来——用它自己的话说。

例如,有人在 Slack 报告问题时,我通常会先让 agent 阅读完整对话,并用自己的话重新说明问题,然后再做其他事情。

比如我会这样说:

/poteto-mode read this slack thread. restate in your own words and in plain english what you think the underlying issue is

这样做有三个作用:

第一,它会迫使 agent 把一段杂乱的对话压缩成结构清晰的问题陈述。第二,我可以立刻发现理解偏差。如果 agent 被对话里某条误导性线索带偏,我能在它动手写代码前迅速纠正。

第三,我没有先把自己的假设和猜测灌输给它,因为这些判断可能是错的,也可能限制 agent 原本能够找到的解法。

建立心智模型

让 agent 用你听得懂的方式重新说明问题,是与一个比你聪明的人协作时很重要的一环。这也启发了 /teach:这个 skill 能帮助 agent 用直观的方式向你解释问题。每当我需要确认 agent 的做法对我来说合乎逻辑时,都会用它。

在底层,/teach 会调用 /how 和 /why。

/how 会追踪运行时机制。调用 /how 后,agent 会评估子系统的复杂度。如果子系统横跨多个目录或服务,它就会使用 Grok 这类快速高效的模型,并行启动多个探索 agent。

/how is virtualization implemented?

/why 调查动机和意图。代码会告诉你发生了什么,却很少解释为什么有人要这样写。运行 /why 时,pstack 会并行查询多个来源中的历史证据:Git 历史和 PR 审查评论、Linear 工单、Notion 设计文档、Slack 对话、Datadog 监控、Sentry 错误、代码沿革以及分析数据仓库中的事件。

/why are we still stuck an old version of node.js?

每当我想让 agent 重新解释某件事,以便自己更好地理解并信任它的工作时,都会使用 /teach。

/teach me why you implemented it this way and not <other way>. what were the tradeoffs you made and why?

在实践中,我还发现,/teach 所做的研究不只对人有用,对 agent 也很有帮助。即便是最新的前沿模型——当然,这也取决于 harness 的质量——通常还是会在没有数据支撑、也没有真正阅读足够代码来建立系统模型的情况下,信心十足地给出结论。因此,让 agent 教你它准备做什么、为什么这么做,最后也会反过来帮助它自己。

从历史中学习

我的许多项目都会跨越多次对话。例如几个月前,我在修复 Cursor 中用户报告的虚拟化 bug 和性能问题。我发现,每次新开一段对话,我几乎都要从头开始,重新为 agent 建立它上次解决类似问题时拥有的丰富上下文。

后来我意识到,过去的对话记录往往是一座上下文金矿。pstack 提供了 /recall skill,可以从聊天历史中取回最近的上下文。这样,即使是刚启动的 agent,也能拿到迅速进入状态所需的上下文。

/recall the work i did yesterday on virtualization and then read this bug report on slack

我会用 /teach、/recall、/how 和 /why,让自己对代码库的理解保持更新,并把信息压缩成容易理解和记忆的形式。这同样也能帮助 agent!

从目标倒推

理解问题之后,该如何描述解决方案?

在我看来,大多数带有规划模式的 harness,往往对实现细节规定得太多,对其他一切却规定得太少。所以我才会在 pstack 里半开玩笑地说:“我不相信规划。” 其实我当然会做规划,只不过是通过代码来规划。

某些工作——比如创建供他人使用的共享代码或软件包——很适合采用 README 驱动开发。如果你没听过,这是以前流行过的一种开发方法:先编写 README。这样,你会被迫从开发者体验的角度思考,先向一位假想用户描述 API,再反推实现和架构。

例如,在构建内部桌面应用客户端框架 Dune 时,我先为它写了一篇教程,这样就能弄清楚使用这个框架开发应用会是什么体验。

第一版文档把教程、操作指南、参考资料和原理说明全混在了一起,结构混乱,满是常见的 AI 废话与矫饰的文风。

/technical-writing 使用 Diátaxis 框架,把文档分成四种明确的模式:

  1. 教程: 在实践中学习。通过一系列步骤带领新手构建出看得见的成果。
  2. 操作指南: 为有经验的用户提供解决某个现实问题的具体步骤。
  3. 参考资料: 对机制、API 和配置标志进行简洁、完整且权威的技术描述。
  4. 原理说明: 从较高层次讨论背景、设计选择和权衡,帮助读者理解其中缘由。

它还会使用 /unslop,因此生成的文档很好读。

用这种方式写规划很有帮助,因为它也为 agent 提供了一个具体目标,让它能够据此检查自己的工作。当然,你也更容易理解 agent 究竟要构建什么。

pstack 的许多 skill 会在设计阶段相互叠加、共同发挥作用。例如:

(1) /recall my work fixing virtualization bugs and perf issues from the past 7 days. use /how and /why to understand how our current virtualization implementation works.

(2) then use /poteto-mode planning and /technical-writing to come up with a new virtualization engine that categorically eliminates flickering and jittering. let's start by writing a tutorial on how i would use this new package to virtualize a React app

(3) after you write the plan, /teach me and prove to me why this new approach is superior to our current engine

这里的关键,是把有价值的丰富上下文引出来,让 agent 能像你一样看到问题的全貌,而不是只看到一个小切面:

  1. 提示词的第一部分会找回过去和现在与应用虚拟化实现有关的上下文。
  2. 第二部分引导 agent 利用这些上下文——例如它过去修复过的 bug——设计一套能彻底消除这些问题的新方案。
  3. 最后一部分要求 agent 向你证明新软件包更出色。这正是验证 skill 这类高质量工具发挥作用的地方。

量一百次,只下刀一次

做规划时,我最常看到的两个错误是:

  1. 接受 agent 给出的第一个设计。
  2. 在没有实证依据的情况下,把方案做得过于复杂。

过去由人编写代码时,我们经常通过设计文档协作。这些文档会讨论高层架构、考虑过的替代方案、各种权衡,以及不同寻常的实现细节。在最终确定设计之前,反复修改几轮设计文档非常常见。

使用 agent 后,设计文档的仪式可以省掉,但我经常看到有人直接接受 agent 交回来的第一个方案。借助 pstack,我们可以利用并行 agent,把“量两次、切一次”的方法推到极致。

具体做法是使用原型 playbook。

在 pstack 中,playbook 不是 skill,而是 /poteto-mode 内部的参考文件。它们会根据当前任务类型按条件加载,以节省 token。截至 0.15.0,共有 23 个 playbook,每个都记录了一套我实际处理某类任务时使用的工作流。

与 skill 不同,agent 会在 /poteto-mode 中自动使用 playbook。例如:

/poteto-mode prototype a few options for the new dropdown menu
/poteto-mode fix this bug
/poteto-mode eval this skill change

原型验证是我最喜欢的 pstack playbook 之一。它让 agent 能围绕同一个目标做多次尝试,并推理出最好的方案。这不仅适用于视觉原型,也适用于探索功能、bug 修复等工作的不同解决方案。

/poteto-mode prototype a few options for <feature request>. use /control-app* and take videos/screenshots for me to review and choose from

* 注意:/control-app 是我们在第一部分中创建的验证 skill。

为视觉改动制作原型时,agent 会直接在应用里或临时目录中构建一次性草图。如果要测试 UI 交互,它会把两三种方案放在一个简单的切换器后面;然后用 /control-app skill 操作这些交互,截取每个方案的画面,并测量真实的耗时或布局。

原型验证就是用代码做规划。它给 agent 探索问题空间的自由,也给它机会拿出你自己未必想得到的方案。借助原型,agent 可以用实证回答自己的问题,不必等我提供答案。

为更大的改动设计架构

在 agent 时代,作为工程师,我更应该把时间花在架构设计、选择合适的数据结构,以及思考自己构建的各个系统该如何协同上。实现细节则由 agent 补齐。

pstack 还附带了另一个很实用的 skill:/architect。它把设计工作分成几个清晰而严谨的阶段:

  1. 弄清问题。 agent 对受影响的系统运行 /how 和 /why,准确理解现有职责归属和约束。
  2. 勾勒方案。 agent 进入架构方案竞赛环节,通常会跨不同模型系列,并行启动相互独立的候选方案 agent。每个 agent 都会拿到前一步整理的背景材料,并起草一套完整的设计:调用方式草图、核心类型定义、公开函数签名和简要理由。这通常只需勾勒类型签名,并由我们期望的调用方式反推出来。每个 agent 都必须评估接口深度、检查弱模型下的失败模式,并对照我们的设计风险清单进行筛查。
  3. 交叉评审并汇总。 使用不同于主 agent 的模型,由一个交叉评审 agent 按照严格标准评估各个候选方案。
  4. 依照草图实现。 agent 用真正的逻辑替换草图中的占位实现。如果实现过程中发现某个函数意外需要额外参数或状态,agent 会把这项偏差明确指出来。
  5. 设计错了就推倒重来。 如果实现过程中发现草图有误,agent 会全部丢弃,从头开始。

这样做的目的,是让 agent 在一个自行闭环的小流程里,把不同模型系列提出的多个竞争方案整合成一个最优解,严谨地推进工作;一旦实证表明自己设计的架构有误,也不怕把整个设计推倒重来。如果同一种变通办法反复出现在彼此无关的调用点,或者类型系统需要 any、强制类型转换之类绕过约束的后门,那就是架构有问题的实证。

/architect this new <feature request>

这里最重要的经验是:使用 /poteto-mode 的原型 playbook 和 /architect,通过代码来规划,效果要好得多。

这也是我从不费心对抽象方案做对抗式审查的原因。agent 会开始臆想理论风险,编造复杂的边界情况,防范那些根本不会发生的问题。方案还停留在抽象层面时,不要把它做得过于复杂;让 agent 通过原型和自我验证,自己回答尚未解决的问题。

好吧,但我真的想要一份规划文档

虽然 pstack 没有专门的规划 skill,但它带有一个多阶段规划 playbook。我通常会在 agent 提出令我满意的设计之后使用它,把设计转成一份具体的执行计划。

/poteto-mode turn this design into a plan

计划里的每一项任务都围绕证据和验证来组织。这个 playbook 会告诉 agent:只有测试还不算充分验证。只有真正运行代码并确认它能工作,才算验证完成。

每份计划都会经过自动化脚本检查,验证结构和格式。计划获批后,再逐项执行。每个 PR 都很小、自成一体,也很容易审查。

面对真正的大型项目——比如要花整整一周的项目——我有时会决定把计划暂时提交进代码库,让其他 agent 知道当前有哪些工作正在进行。但项目结束后,我通常会删除这些计划,以免代码库里的过期信息让人困惑。我认为永久保留计划没有什么价值。

实际工作流

下面通过三个具体示例,看看这些环节如何组合起来,以及我是怎样为这些工作流写提示词的。

示例一:调查原因不明的 bug

生产环境出现问题、根因又不明确时:

/poteto-mode investigate why background workers periodically fail with timeout errors. give me a breakdown of what we know, what data you used, and your best hypotheses.

agent 会探索代码,并行检查指标和历史提交,然后根据掌握的信息,给出它对问题所在位置最有根据的判断。

示例二:设计新的服务边界

要引入一个其他模块都会依赖的新子系统时:

/poteto-mode we need to add rate limiting for external webhooks. /architect this first, and answer any open questions with prototypes. let me review before proceeding.

agent 会梳理现有 webhook 架构,使用多个模型启动相互竞争的设计方案,通过一次性原型进行基准测试,最终给出一套简洁且经过验证的接口。

示例三:执行跨多个 PR 的迁移

要在许多文件中进行复杂重构时:

/poteto-mode create a plan to migrate our entire UI library to StyleX. break the migration into small, verifiable PRs. each PR must have its visual regression tests and live verification steps. i want the final result to be 100% identical compared to the original - bugs included

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

我在这里谈到的许多 skill,/poteto-mode 已经会自动使用。因此绝大多数时候,你只要用 /poteto-mode,然后接着忙别的就行!

规划的艺术

规划模式经常被用来让你说服自己:agent 接下来会做正确的事。但实际上,抽象方案带来的往往只是进展的幻觉。一份冗长的计划会让你觉得自己和 agent 做了很多事,实际上却可能没有多少实质内容。

pstack 提供了一套工具,把深入调查、实证和严格验证结合起来。用这种方式做规划,与 agent 一起做工程就不再像赌博,而会变得可预测、可复现。

https://x.ai/bot/plugin/9717366

感谢阅读,第三部分见!