Cursor plugin pstack's Agent engineering guide

It outlines three core components: a verification CLI for agent self-validation, a Feature Map markdown system for application documentation, and cloud-based parallel execution.

The guide emphasizes the importance of verification as a 'key infrastructure' for scaling team productivity, with practical design principles for CLI and documentation.

Cursor 官方插件 pstack 的 Agent 工程完全指南 pstack 作者 @poteto - Grok @Bot 工程师、React Compiler 核心团队成员，她在团队每天合入数百个 PR 的扩张期，一边持续重构一边保持代码质量。pstack 是她沉淀的个人 Skills 集合（以 Cursor 插件形式发布），支撑每月 2,000 个 PR 的高信心交付。 lauren 分两篇来做 pstack 工程指南： · Part 1 - 验证：Agent 能否自己确认做对了？ · Part 2 - 研究与规划：人如何指挥比自己聪明的劳动力？ # Part 1：Verification is all you need 验证 Skills 是整个体系的基石。所谓验证，就是 Agent 能自己确认改动是否生效，从而闭环执行、持续迭代直到成功，人不再是瓶颈。lauren 认为这是“关键基础设施”，值得像对待生产系统一样投入（甚至可以设 oncall 轮值），可放大团队产出 100–1000 倍，且非工程师同样受益。 一个有争议但自洽的推论：技术栈的选型标准应包含“可调试性”。如果运行时难以调试和控制（无法截屏、无 accessibility 树、无性能 trace），agent 就无法有效工作。lauren 直言会为此更换技术栈——Web/Electron 可用 Chrome DevTools Protocol，iOS 可用模拟器。 实践方法：三个组件 1. 验证 CLI（“Build the Lever” 原则） 给 agent 提供工具而非纯 markdown 指令：一个封装了应用交互与调试的小 CLI，覆盖检查（snapshot/screenshot）、导航、交互（click/type/press）、Skills（trace/wait-settle）、健康检查等子命令。这比让 agent 每次写一次性脚本更省 token、更可复现、可测试。作者还强调 agent 友好 CLI 的设计要点：可组合的 API（Ousterhout 的 deep modules 哲学）、破坏性命令带 --dry-run、子命令渐进披露功能、错误信息要告诉 agent 下一步该做什么、丰富的 --help、JSON 输出。 2. Feature Map（物化记忆） 一组 markdown 文件，记录应用每个功能是什么、用户视角如何到达、有哪些坑。本质是代码库的压缩投影——代码才是终极记忆，Feature Map 只是为了省 token 的紧凑形式，且作为技能内共享 markdown，全团队（包括非工程师）受益。配套 /maintain-verification-skill 每日例行维护，防止过时。 3. 云端并行（Cursor Cloud Agents） lauren 明确反对 git worktrees 方案（占资源，上限约 10 个并行），推荐 Cursor 云端 agent：有真实机器、可装依赖、可跑应用可录屏，首次构建后有快照，后续启动快。这是后续“数百子 agent 并行”的前提。 组合用法 · /poteto-mode 作为入口（可固化为 Cursor Custom Mode，每轮提醒） · bot 的角色定位是协调者：让 bot spawn 云端 agent 干活，保持自己上下文窗口干净 · /swarm 扇出多个云端 agent 跑验证：用足够样本量确认性能优化、fuzz 回归 · 终极形态：接入 routines/automations，监听 Slack 用户反馈，自动复现——甚至自动修复 # Part 2：监督比你聪明的人的艺术 Agent 消除了“必须先建立心智模型才能改代码”的门槛，但前沿模型仍有两个高频失败模式：理解不了你的意图（指令欠规范）和缺少把事做对的上下文。两者同源：用好 Agent 取决于你往它的上下文窗口里注入多高质量的语境。同时，现代代码库已大到人类无法在脑中装下完整心智模型，所以方法论要从“自己懂”转向“让 Agent 向你证明它懂”。 五个核心技法 1. 间接提示（In your own words） 不直接下令，先让 Agent 用自己的话复述问题（如“读这个 Slack 线程，用平实的英语复述你理解的根本问题”）。一举三得：强迫压缩噪声为结构化问题陈述；让你立刻发现误解（避免 Agent 死磕错误方向）；避免你自己的错误假设带偏 Agent。 2. 心智模型构建 Skills 组合 · /how：追踪运行时机制。子系统跨目录/服务时，用快速模型（如 Grok）并行派出探索 agent · /why：调查动机与意图。代码只告诉你“发生了什么”，很少说“为什么这么写”——并行查 Git 历史、PR 评论、Linear、Notion、Slack、Datadog、Sentry 等 · /teach：让 agent 以直觉可理解的方式解释给你听（底层调 /how + /why）。有趣的发现：这个“教学”过程对 agent 自身也有益——前沿模型常自信陈述而不真正读代码，教你的过程迫使它建立真实心智模型 · /recall：从历史会话转录中捞回上下文。跨会话项目不必每次从零重建语境 3. README 驱动开发 lauren 不写抽象规划文档（“I don't believe in planning”，实质是“用代码规划”）。对共享代码/包，先写 README 再实现：逼你戴上开发者体验的帽子，从假想用户的 API 视角倒推架构。配套 /technical-writing 技能，用 Diátaxis 框架严格区分四类文档（Tutorial / How-to / Reference / Explanation），再加 /unslop 消除 AI 腔。写好的文档同时成为 Agent 可自我检验的明确目标。 4. 原型优先（Measure a hundred times, cut once） 规划阶段最常见的两个错误：接受 Agent 的第一个设计，以及在缺乏实证时过度打磨方案。解法是 prototyping playbook：让 Agent 并行产出多个原型（UI 变体挂在 switcher 后面、用验证 CLI 实测时序与布局），用截图/视频供人选择。原型就是用代码做规划——agent 用实证回答自己的开放问题，还有机会给出你没想到的方案。 5. /architect 架构 Skills 五阶段流程：Ground（用 /how /why 建立现状模型）→ Sketch（多个独立 runner 并行、常跨模型家族，各产出完整设计包：调用点草图、类型定义、函数签名、理由）→ Cross-judge（用不同模型按严格 rubric 交叉评审）→ Implement（以草图为准填实现，发现不符则上报）→ Scrap（设计错了就全部推倒重来）。判断“错了”的标准是实证性的：无关调用点反复出现同一 workaround、类型需要 any 或强制 cast 逃生舱——那就是架构错误的经验证据。 一个重要的反直觉观点：不要对抽象方案做对抗性评审。Agent 会幻觉出理论风险、发明永远不会发生的边缘案例。让开放问题通过原型和自我验证去回答。 工作流实例（原文四个场景） · 模糊生产 bug：/poteto-mode 调查 + 并行查代码/指标/历史提交，输出“已知事实—数据来源—假设” · 新服务边界：先 /architect，开放问题用原型回答，人审后再推进 · 多 PR 迁移：拆成小的可验证 PR，每个带视觉回归测试与实机验证，要求结果与原版 100% 一致（"bugs included"） · Slack 用户反馈：上下文够时直接 "do it"；或 “用 /control-app 复现，main 上能复现就修，给我视频为证” lauren @poteto Part 2 is here! Let's learn the art of supervising someone smarter than you. x.com/i/article/2094… 🔗 View Quoted Tweet📊 1 ⚡

This report is categorized under AITOP's "How-to" desk, focusing on US frontier AI labs and Silicon Valley technology leaders. Within our cross-regional analytical framework, it directly maps to AI developer toolchains, coding agents, and engineering workflows and AI regulation, compliance frameworks, and sovereign compute policy. Key entities and technical topics under continuous tracking include Cursor, Agent, prompt engineering, workflows.

Source attribution: curated from shao__meng (@shao__meng). Cross-source corroboration: 2 independent sources have covered this development (including 小互), confirming industry-wide signal strength.