在我的上一篇文章中，我向你展示了为什么验证是我使用 Agent 所做一切的基础，以及如何开始创建你自己的验证技能。关键教训是，如果一个 Agent 无法验证自己的工作，其他一切都无关紧要。你仍然是瓶颈，你的一整天都将花在照看你的 Agent 上。
https://x.com/poteto/status/2094457600259842065
但一旦验证工作正常，下一个问题就是：你实际上如何弄清楚要构建什么？
https://x.ai/bot/plugin/9717366
在这篇文章中，我将向你介绍我如何使用 pstack 进行研究、规划、原型设计和架构。这正是让我能够每月向生产环境交付数千个 PR，同时保持极高代码质量的工作流程。
以 8 月份结束，生产环境中部署了 2,462 个 PR
监督比你聪明的人的艺术
回到 2024 年的旧时代，要对系统进行任何更改，你首先需要阅读足够多的代码，以构建一个关于系统运作的心理模型。根据代码库的大小和复杂性，这可能需要你花费数小时，甚至数天和数月的时间。对于小改动，你可能只需要对一个小型子系统有局部了解。然而，如果你要重构核心部分，你可能需要了解整个系统的工作原理，才能正确有效地进行重构。
Agent 显然消除了这个障碍。你可以通过简单地提示你的 Agent 来轻松地对系统进行更改，它会执行操作，无论你对代码了解多少。但是，保持代码和用户体验的高质量仍然很困难，特别是如果你还不是一个知道该寻找什么和该问什么的领域专家。
尽管前沿模型已经变得非常强大，但我仍然经常观察到两种失败模式：
- 它们无法完全理解你的意图，因为意图描述得不够充分或不够清晰。
- 它们没有足够的上下文来正确完成工作。
这两个问题都是相关的。用好 Agent 归结于你能够用高质量的上下文来填充 Agent 的上下文窗口。当然，你也可以不这样做就编写出能工作的代码，但我发现，当我为 Agent 提供了完成高质量工作所需的一切时，结果和质量会好得多。
用你自己的话来说
前沿模型是非常能干的程序员。虽然对于较旧的模型，我可能会非常具体地提示我想要它做什么，几乎是微观管理，但最新的模型能够写出比你我更好的代码。因此，我需要找到一个微妙的平衡：告诉 Agent 我想要它实现什么，同时给予它自由，让它以我可能没有想到的方式去解决问题。
这就是监督一个比你聪明的人的艺术，在一个不是你编写的代码库上，而且人类的大脑已经无法容纳整个代码库的心理模型。
我喜欢使用的一种技术是间接提示。我不是直接告诉 Agent 我确切想要什么，而是尝试引导 Agent 自己说出来——用它自己的话。
例如，当有人在 Slack 中报告问题时，我通常会先让 Agent 阅读整个讨论串，并用它自己的话重新表述问题，然后再做其他任何事情。
例如，我可能会说：
/poteto-mode 阅读这个 Slack 讨论串。用你自己的话，用通俗易懂的英文，重新表述你认为的根本问题是什么
这实现了三件事：
首先，它迫使 Agent 将一个嘈杂的对话压缩成一个结构化的问题陈述。其次，它让我能够立即发现误解。如果 Agent 在讨论串中纠结于一个误导性的线索，我可以在它开始编写任何代码之前迅速纠正它。
第三，我没有通过陈述我自己的假设和猜想（这些可能是错误的，或者限制了 Agent 本可以实现的成果）而可能将其引向错误的方向。
建立心理模型
让 Agent 以你能理解的方式重新表述自己，是与比你聪明的人一起工作的重要部分。这也是 /teach 技能的灵感来源，它帮助你的 Agent 以直观的方式向你解释事情。每当我需要确保我的 Agent 做的事情对我来说有意义时，我就会使用它。
/how 追踪运行时机制。当你询问 /how 时，Agent 会评估子系统的复杂性。如果子系统跨越多个目录或服务，它会使用快速、高效的模型（如 Grok）生成并行的探索 Agent。
/how 虚拟化是如何实现的？
/why 调查动机和意图。代码告诉你发生了什么。它很少告诉你为什么有人会那样写。当你运行 /why 时，pstack 会并行查询多个来源的历史证据：Git 历史和 PR 审查评论、Linear 工单、Notion 设计文档、Slack 对话、Datadog 监控、Sentry 错误、代码谱系和分析仓库事件。
/why 我们为什么还停留在旧版本的 node.js 上？
每当我希望 Agent 重新表述某些内容，以便我能更好地理解和信任它的工作时，我就会使用 /teach。
/teach 我，为什么你以这种方式实现，而不是<其他方式>。你做了哪些权衡，为什么？
在实践中，我还发现 /teach 技能所做的研究不仅对人类有用，对 Agent 也很有用。即使是最新的前沿模型（这也取决于 harness 的质量），总的来说，我发现它们仍然经常自信地陈述事情，而没有用数据来支持，或者没有实际阅读构建其工作原理心理模型所需的代码。因此，这种教你它将做什么以及为什么做的行为，最终也帮助了 Agent。
从历史中学习
我的许多项目跨越多次对话。例如，几个月前，我正在修复人们在 Cursor 中报告的虚拟化错误和性能问题。我意识到，每次我开始一个新的聊天时，我基本上都必须重新为我的 Agent 建立之前解决类似问题时拥有的丰富上下文。
我意识到的是，你过去的对话记录通常是丰富上下文的金矿。pstack 附带了 /recall 技能，可以从聊天历史中提取你最近的上下文，这样即使是新的 Agent 也能拥有恢复到良好状态所需的正确上下文。
/recall 我昨天在虚拟化方面所做的工作，然后阅读 Slack 上的这个错误报告
使用 /teach、/recall、/how 和 /why 是我保持自己对代码库的心理模型最新、并将其压缩成易于理解和记忆的形式的方法。而且，这对 Agent 也有帮助！
逆向工作
一旦你理解了问题，如何指定解决方案？
在我看来，大多数具有计划模式的 harness 往往过度指定实现细节，而低估了其他一切。这就是为什么在 pstack 中，我开玩笑地说 "我不相信计划"。事实是，我确实有计划，但我是通过代码来计划的。
对于某些类型的工作，比如创建其他人会使用的共享代码或包，我是自述文件驱动开发的坚定信徒。如果你不熟悉它，这是一种过去流行的开发技术，你首先从编写自述文件开始。这迫使你戴上开发者体验的帽子，从向假设的用户描述 API 开始，然后逆向工作到实现和架构。
例如，当我构建 Dune（我们用于桌面应用的内部客户端框架）时，我首先为它编写了一个教程，这样我就能理解用它构建应用会是什么样子。或者至少我尝试过。让 Agent 产生任何好的或可读的内容确实是一场斗争。所以我必须首先花一些时间来磨刀，通过创建 /technical-writing 技能。
没有 /technical-writing 技能的第一版自述文件读起来很痛苦，因为它混合了不同的目标。它试图在同一份文档中成为教程、操作指南、架构解释和 API 参考，并且是用你常见的那种 AI 废话和 矫揉造作的文风 写成的。
/technical-writing 使用 Diátaxis 框架 将文档分为四种不同的模式：
- 教程： 在实践中学习。一个引导新手通过一系列步骤来构建可见内容的课程。
- 操作指南： 为有经验的用户解决特定、现实问题的步骤。
- 参考： 关于机器、API 和配置标志的枯燥、完整、权威的技术描述。
- 解释： 高层次讨论，阐明和说明背景、设计选择和权衡。
它还使用了 /unslop，因此生成的文档非常易读。
以这种方式编写计划非常有帮助，因为它也为你的 Agent 提供了一个具体的目标和目的，它可以据此检查自己的工作。当然，也更容易理解 Agent 究竟要构建什么。
pstack 的许多技能在设计阶段会在这里叠加。例如：
(1) /recall 我过去 7 天修复虚拟化错误和性能问题的工作。使用 /how 和 /why 来理解我们当前的虚拟化实现是如何工作的。
(2) 然后使用 /poteto-mode 规划和 /technical-writing 来提出一个新的虚拟化引擎，从根本上消除闪烁和抖动。让我们从编写一个关于如何使用这个新包来虚拟化 React 应用的教程开始。
(3) 在你写完计划后，/teach 我并向我证明为什么这种新方法优于我们当前的引擎。
这里的技术实际上是关于提取有趣且丰富的上下文，让你的 Agent 能够像你一样看待问题——而不仅仅是一个小片段：
- 提示的第一部分回顾了关于虚拟化在我的应用中如何实现的相关的过去和现在的上下文。
- 第二部分指导 Agent 使用该上下文，例如它之前修复过的错误，来提出一个能完全消除这些问题的全新设计。
- 最后一部分是要求你的 Agent 向你证明这个新包更优越。这就是像 验证技能 这样的高质量工具发挥作用的地方。
百次测量，一次裁剪
在规划时，我看到的两个最常见的错误是：
- 接受 Agent 的第一个设计。
- 在没有经验证据的情况下过度规划。
当人类编写代码时，我们经常通过设计文档相互协作。这些文档讨论高层架构、考虑的替代方案、权衡以及任何不寻常的实现说明。在达成一个确定的设计之前，经历这些文档的多次迭代是非常常见的。
有了 Agent，虽然我们可以跳过设计文档的仪式，但我经常看到人们犯下接受 Agent 第一次给出的东西的错误。使用 pstack，我们可以将“二次测量，一次裁剪”的方法发挥到极致，使用并行 Agent。
我们通过使用 原型设计 playbook 来做到这一点。
在 pstack 中，playbook 不是技能，而是 /poteto-mode 内部的参考文件。这些 playbook 会根据你正在处理的任务类型有条件地加载（为了 token 效率）。这 23 个 playbook（截至 0.15.0 版本）每个都包含我在执行任务时使用的工作流程。
与技能不同，playbook 由 Agent 作为 /poteto-mode 的一部分自动使用。例如：
/poteto-mode 为新下拉菜单原型设计几个选项 /poteto-mode 修复这个错误 /poteto-mode 评估这个技能变更
原型设计是我最喜欢的 pstack playbook 之一。它为你提供了多次尝试实现目标的机会，并帮助 Agent 推理出最佳选项。这不仅对视觉原型设计有用，也对为功能、错误修复等原型设计不同解决方案有用。
/poteto-mode 为<功能请求>原型设计几个选项。使用 /control-app* 并录制视频/截图供我审查和选择
\ 注：/control-app 是我们在 [第 1 部分]([https://x.com/poteto/status/2094457600259842065](https://x.com/poteto/status/2094457600259842065)) 中创建的验证技能*
当原型设计视觉变化时，Agent 会在你的应用或临时目录中构建可丢弃的草图。如果它正在测试 UI 交互，它会将两三个变体放在一个简单的切换器后面。然后它使用 /control-app 技能驱动交互，为每个变体截图，并测量实际的时间或布局。
原型设计就是规划，但通过代码进行。它允许 Agent 自由探索问题空间，并给他们一个机会，用你自己想不到的东西给你带来惊喜。原型允许 Agent 用经验证据回答自己的问题，而不是等待我的输入。
架构更大的变更
作为 Agent 时代的工程师，将时间花在架构上、选择正确的数据结构以及思考我构建的系统将如何协同工作更为重要。我的 Agent 负责填充实现细节。
pstack 附带的另一个有用的技能是 /architect。它将设计结构化为不同、有纪律的阶段：
- 夯实问题。 Agent 对受影响的系统运行 /how 和 /why，以构建关于现有所有权和约束的准确心理模型。
- 草图。 Agent 进入一个架构竞技场。它并行生成独立的候选运行器，通常跨越不同的模型家族。每个运行器接收基础简报并起草一个完整的设计包：调用者的使用草图、核心类型定义、公共函数签名以及简洁的理由说明。这些通常通过草拟类型签名来完成，这些签名源自我们希望调用点看起来的样子。每个运行器必须评估接口深度，检查弱模型上的失败模式，并根据我们的设计危险信号目录进行筛选。
- 交叉评判与综合。 一个使用与主 Agent 不同模型的交叉评判 Agent，根据严格的评分标准评估候选方案。
- 根据草图实现。 Agent 用真正的逻辑替换草图的占位符主体。如果在实现过程中，Agent 发现某个函数需要意外的参数或额外的状态，它会指出这种不一致。
- 当设计错误时丢弃。 如果在实现过程中我们发现草图是错误的，Agent 会抛弃所有内容并重新开始。
这里的重点是给 Agent 一个自包含的迷你循环，它可以将来自不同模型家族的多个竞争性设计综合成一个最优方法，并注意保持严谨，如果根据经验证明其提出的架构是错误的，不要害怕抛弃它。如果相同的工作绕过不相关的调用点出现，或者类型需要像 𝚊𝚗𝚢 或强制转换这样的逃生舱口，这就是架构错误的经验证明。
/architect 这个新的<功能请求>
这里的重要教训是，使用 /poteto-mode 原型设计和 /architect 通过代码进行规划要有效得多。
这也是为什么我从不费心去对抗性地审查抽象计划。Agent 会开始幻觉理论上的风险，并发明复杂的边缘情况来防范永远不会发生的问题。当你的计划仍然是抽象的时候，不要过度烹饪：让 Agent 通过原型设计和验证自己的工作来自行回答未解决的问题。
好吧，但我真的想要一个规划文档
虽然 pstack 没有附带规划技能，但它确实附带了一个 多阶段规划 playbook。我通常在 Agent 提出了一个我满意的设计后使用它，作为一种创建战术执行计划的方式。
/poteto-mode 把这个设计变成一个计划
计划中的每一个任务都围绕着证明和验证来构建。playbook 告诉 Agent，仅靠测试是不够的验证。只有当它实际运行了代码并验证了它能工作时，才算验证通过。
每个计划都由一个自动化脚本检查，该脚本验证其结构和格式。一旦批准，计划就逐项执行。每个 PR 都很小、自包含且易于审查。
对于非常大的项目（比如可能需要我整整一周的项目），我有时可能会决定将计划临时提交到代码库中，以便其他 Agent 知道正在进行的工作。但我通常在完成后删除它们，这样就不会让代码库处于混乱状态。我认为永久保留计划没有价值。
实践中的工作流程
为了了解所有这些部分如何组合在一起，让我们来看三个具体的例子，说明我如何提示这些工作流程。
示例 1：调查一个模糊的错误
当生产环境中出现一个问题，且根本原因不明确时：
/poteto-mode 调查为什么后台工作进程会定期出现超时错误。给我一份关于我们所知信息、你使用了哪些数据以及你最佳假设的详细说明。
Agent 会探索代码，并行检查指标和历史提交，并给出它关于问题可能出在哪里的最佳有根据的猜测。
示例 2：设计一个新的服务边界
当引入一个其他模块将依赖的新子系统时：
/poteto-mode 我们需要为外部 webhook 添加速率限制。先 /architect 这个，并用原型回答任何未解决的问题。在继续之前让我审查。
Agent 夯实现有的 webhook 架构，跨多个模型启动竞争性设计运行器，用可丢弃的原型进行基准测试，并生成一个干净、经过验证的接口。
示例 3：执行一个多 PR 迁移
当跨许多文件执行复杂的重构时：
/poteto-mode 创建一个计划，将我们整个 UI 库迁移到 StyleX。将迁移分解成小的、可验证的 PR。每个 PR 必须有视觉回归测试和实时验证步骤。我希望最终结果与原始版本 100% 相同——包括错误。
Agent 将工作分解为独立的步骤，编写一个可审计的检查清单，并准备每个单元，以便可以安全地构建、验证和上线。
示例 4：修复人们在 Slack 上报告的问题
如果你曾经在 Slack 的某个问题或反馈频道中见过我，你可能会看到这些经典操作：
# 讨论串已有足够的上下文
/poteto-mode 去做吧
/poteto-mode 用 /control-app 复现这个问题。如果在主分支上能复现，就修复它，并给我看一个视频作为证明
我在这里谈到的许多技能已经被 /poteto-mode 自动使用，所以绝大多数时候你只需要使用 /poteto-mode，然后继续你的生活！
规划的艺术
计划模式通常被用作一种说服自己 Agent 会做正确事情的方式。但现实是，抽象的计划只会给你进步的错觉。一个冗长的计划看起来像是你和你的 Agent 非常高效，但它可能缺乏实质内容。
pstack 为你提供了结合彻底调查、经验证据和严格验证的工具。当你以这种方式规划时，使用 Agent 进行工程就不再感觉像是一场赌博。它变得可预测且可重复。
https://x.ai/bot/plugin/9717366
感谢阅读，敬请期待第 3 部分！
