外观
监督比你聪明的 Agent:六个动作与 Lint 倒金字塔
一句话定义:当模型写代码比你强、而你已经读不完它写的每一行,管理方式要从"指挥它怎么写"换成**"让它把问题复述清楚、拿证据说话,并把你纠正过的每个错误锻造成机器可执行的约束"**。
为什么旧办法失效
前沿模型在编码上仍然经常栽在两个地方:
- 规格没写清楚 —— 它没完全理解你要什么;
- 上下文不足 —— 它不知道该按什么约束去干。
老模型时代,对策是把提示词写得极具体,微观管理到每一行。但模型写代码比人好之后,过度指定反而有害:既限制了它的解法,又把你自己的错误假设一起塞了进去。
真正的转变是从"将兵"到"将将":你不再比谁更会写,而是决定谁来做、做到什么标准、怎么验收。
六个动作总览
| # | 动作 | 解决的问题 | 主要手段 |
|---|---|---|---|
| 1 | 提需求 | 意图没传达到 | 间接提示词:先让它复述、甚至反过来采访你 |
| 2 | 建认知 | 人和 Agent 都不懂这套代码 | /teach → /how + /why,加 /recall 与 Feature Map |
| 3 | 做规划 | 抽象计划是进度幻觉 | README 驱动 + 用完即弃的代码原型 |
| 4 | 定架构 | 实现细节锁死了错误形状 | /architect 五步闭环 + 跨模型草图竞技 |
| 5 | 卡质量 | 错误在代码库里自我复制 | lint 倒金字塔 + /no-comments + /correct |
| 6 | 搭底座 | 人成了验收瓶颈 | Agent 专用 CLI + Feature Map,让 Agent 自验证 |
一、用"间接提示词"让它先复述
不直接指挥改哪一行,先让 Agent 用自己的话把问题讲一遍。
text
/poteto-mode read this slack thread. restate in your own words and in plain english what you think the underlying issue is这一步同时解决三件事:
- 降噪:把一段嘈杂的多人聊天记录压缩成结构化的问题陈述;
- 提前纠偏:如果它盯着无关的干扰项,你能在它写第一行代码前摁住;
- 防止人带偏模型:你对 Bug 的假设本身可能就是错的,写进提示词等于限制了它的发挥。
同一招可以推广到任何重复流程。口述你平时怎么做,最后补一句:
text
"Potato, this is how I usually do this goal myself: <process>
I want you to think about how you can take this over completely from me. Before you begin, restate what you think my goal and process is in simple English so I can give you feedback and confirm it. I don't want you to start executing on this yet, let's focus on getting the process planned first."更狠的做法是让 Bot 反过来采访你,把"做熟了根本不过脑子"的隐性判断挖出来:
text
"Potato, help me figure out what I haven't told you about this process yet. Ask me questions about how I make decisions, where I get my information, how I check the work, and when you should ask me for help. Ask one question at a time, then walk me through a few examples so I can give you feedback before we automate this."一次只问一个问题,走几个真实案例(包括出过错的例外),等它复述得完全对味,再放手。
二、让 Agent 教你,顺手治它的盲目自信
比它弱的人最怕两件事:它干了什么你看不懂;它其实也没看懂,却很自信。
解法是 /teach:要求 Agent 把方案讲到你能判断,底层调用两个技能:
| 技能 | 查什么 | 怎么查 |
|---|---|---|
/how | 运行时机制 | 先评估子系统复杂度;跨多目录/多服务时,用快模型(如 Grok)并发拉起多个探索子 Agent 摸底 |
/why | 历史动机 | 并发查 Git 历史、PR 评论、Linear 工单、Notion 设计文档、Slack、Datadog、Sentry、代码血缘与数仓事件 |
/why 针对的是一个常被忽略的事实:代码只告诉你发生了什么,极少告诉你当初为什么这么写。
而 /teach 的副作用才是关键:为了讲清楚权衡,Agent 必须真的去读代码、查历史,在自己的上下文里建起心智模型 —— 没读代码就下结论的毛病顺带被治好了。
跨会话时用 /recall 捞回近期对话记录(transcript 的信息密度比重新描述高得多)。
记忆是分层的
- 代码库 —— 终极记忆,团队所有决策的投影与唯一真实源头;
- Feature Map —— 写在技能里的 Markdown 目录,记录有什么功能、用户怎么点过去,是省 Token 的物化记忆;
/why—— 跨系统的历史决策背景;/recall—— 近期对话。
四层叠起来,庞大的代码库才被压缩成"人脑能理解、Agent 一进来就能上手"的上下文。
三、不相信抽象计划:README 与原型才是计划
对盛行已久的 Plan Mode,她的批评很直接:大多数计划模式过度指定了实现细节,却对其他重要的东西交代不足。
更反直觉的是:她从不对抽象计划做对抗式评审。因为对着纸面计划挑刺,Agent 会开始幻觉出理论上的风险,再编造一堆现实中不会发生的边缘情况去防御它们。长篇抽象计划给你的只是"今天和 AI 干了好多活"的进度幻觉。
替代方案有三样:
① README 驱动开发。 先写 README 或教程,戴上"开发者体验"的帽子,从用户怎么调用 API 倒推架构。直接让 Agent 写 README 会得到 AI 腔大杂烩(教程、操作指南、架构解释、API 字典混在一起),所以她基于 Diátaxis 做了 /technical-writing:严格区分 Tutorial / How-to / Reference / Explanation 四种模式,再用 /unslop 去掉 AI 废话。
② 用完即弃的代码原型。 做 UI 改动时,让 Agent 在应用里写两三个草稿变体,挂在简单切换器后面,然后自己用 /control-app 点按交互、截图、测真实耗时和布局。
text
/poteto-mode prototype a few options for <feature request>. use /control-app* and take videos/screenshots for me to review and choose from原型就是用代码写的计划。 它让 Agent 拿实证数据回答悬而未决的问题,还经常拿出人没想到的方案。
③ 真要写执行计划,只写以验证为核心的短清单。 每条任务围绕"证据与验证"展开:跑过测试不算完,必须把代码真跑起来验证有效;格式由脚本检查。耗时长的大项目可以临时提交计划文件,让并发 Agent 知道彼此在干什么 —— 干完就删,不留在库里制造混乱。
四、架构:五步闭环与多模型竞技场
工程师的时间应该花在架构、数据结构、系统间配合上,实现细节交给 Agent。/architect 把这件事做成五步闭环:
- 摸底:对受影响的系统跑
/how与/why,摸清职责边界与约束。 - 草图竞技场:跨模型家族并发多个候选设计。每个候选交一份设计包:调用方使用草图、核心类型、公共函数签名、简明理由。只画类型签名,同时评估接口深度、在弱模型上的失效模式、对照设计危险信号目录筛查。
- 异构交叉评审:评委模型与主 Agent 不同家族,按严格评分标准评审各家方案,合成最优解。
- 按草图实现:把占位符换成真实逻辑。若某个函数需要预期之外的参数或额外状态,立刻把偏差浮现出来。
- 设计错了就推翻:实现过程中的实证证据表明草图错了,就全部扔掉重来。
text
/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.什么算"架构错了"的实证? 她给了两条可操作的判断:
- 同样的临时补丁出现在毫不相关的多个调用处;
- 类型系统被迫用上
any、强制类型转换这类逃生舱口。
这两条比"我觉得这样不优雅"硬得多 —— 它们是代码里能看见的证据。
五、质量:把每一次纠正变成铁律
这是整套方法里最该反复读的部分。多数人管 Agent 的第一反应是狂写 AGENTS.md、叠规则、加注释;在她的体系里,文字规则排在倒数第一。
倒金字塔
自顶向下,加固的优先级依次是:
text
┌──────────────────────────────┐
│ 1. 代码库架构改进 │ 让错误写不出来
├──────────────────────────────┤
│ 2. 静态分析与测试 │ 让错误进不了主干
├──────────────────────────────┤
│ 3. 散文式的文字规则与注释 │ 靠自觉,且会被滥用
├──────────────────────────────┤
│ 4. 人工审查 │ 最贵、最不可扩展
└──────────────────────────────┘为什么嫌弃注释?原话很刺:"comments are simply a crutch that agents will happily misuse" —— 注释不过是一根拐杖,Agent 会开开心心地滥用它。注释会过期,会被当成解释丑陋变通补丁的借口,而且无法靠机器强制执行。
让 lint 说人话
架构 lint(lint-arch.sh)分 WARN(超软阈值)与 ERROR(超硬上限)两级,每条告警固定输出四行信息,前缀 [ARCH][WARN] / [ARCH][ERROR]。效果不靠感觉,看提交历史里的文件体积变化。
两个配套技能把纪律自动化:
/no-comments(配 Comment Sicko 子 Agent):能删的注释一律删;写着do not remove的约束性注释,强制改写为类型定义、运行时检查、测试或 CI lint;eslint-disable/@ts-ignore默认视为可疑,凡掩盖正确性问题的抑制注释全部干掉。/correct:读最近的 commit、revert、评审评论、Agent 指令文件、解释 workaround 的注释,把反复出现的错误归类(出现两次才算一类),再按"架构消灭 → 类型系统 → lint / CI → 测试 → 最后写文档"的层级加固。
/correct 里有五条硬纪律,值得直接抄:
- lint 报错必须点名该用哪个文件、哪个类型或哪个函数;
- 坏模式在旧代码里已经到处都是时,新 lint 只在新增代码里报错拦截;
- 每条新规则都必须证明它能在历史上的某个真实错误上触发失败;
- 任何破例必须写在具体那一行,附理由、过期日期与人类批准;
- 在 Agent 指令文件里维护一张"文字规则 ↔ 由什么机器检查强制执行"的映射表;某条规则对应的错误已经不可能发生,就立刻删掉那条文字规则。
一个极端样本
4 天合入约 1,150 个 PR 做了一个小游戏。期间每发现一个问题,就让 bot 写一条对应的 lint;性能敏感代码统一 .hot.ts 后缀,并专门写了一条 lint 禁止在 .hot.ts 里分配内存;注释在这个项目里被 lint 全面禁用。
六、造杠杆:让 Agent 自己验收
第六条是前五条能成立的前提:验证即一切(Verification is all you need)。如果 Agent 不能自己验证代码对不对,其他一切都白搭,你依然是全局瓶颈。
"造杠杆"的具体做法:创建技能时,优先给 Agent 工具,而不只是给 Markdown 文档。一个标准的验证技能由两块资产组成:
① 为应用专门写的、Agent 友好的 CLI。 把点击、导航、调试、抓性能轨迹、造测试数据库、鉴权都脚本化。Agent 跑一条命令就能验证,不用每次现场写一次性脚本 —— 省 Token、可复现、可测试。
六条设计标准:
- API 易于组合,符合深模块(deep modules)哲学;
- 有破坏性副作用的命令必须提供
--dry-run; - 用子命令渐进式披露功能,不要一次全塞出来;
- 报错必须详尽,并直接告诉 Agent 下一步该改什么;
- 配备丰富的
--help; - 输出机器可读(如 JSON)。
② Feature Map。 /create-verification-skill 扫描应用,生成 references/features 目录与总览 README,把"这个功能干什么、用户怎么点过去、背后调什么命令"整理成目录;再用每日定时任务跑 /maintain-verification-skill 保持更新。
她甚至建议:为了拿到 Agent 自验证带来的产出放大,值得自己造一套调试工具,乃至换一个更容易调试的技术栈(Web/Electron 用 Chrome DevTools Protocol,iOS 用模拟器)。验证技能应当被当成核心基础设施来投资。
搭好之后,日常修一个 Slack 上报的问题,她在群里只需要敲:
text
/poteto-mode repro this with /control-app. if it repros on main, fix it and show me a video as proof机器人当协调者:派生并监督云端 Agent 干活、过 lint、跑 CLI 验证、截图录视频交差。人腾出脑子去想目标、架构、数据结构和下一条 lint 规则。
适用场景与代价
适合:代码量大、多人/多 Agent 并发写同一个仓库、有可跑的 CI 与成型工具链的团队;尤其是"Agent 反复犯同类错误"已经让你疲于救火的场景。
不太适合:一次性脚本、小工具、没有测试与 CI 的项目 —— 六个动作的成本会超过收益。倒金字塔的前提是"有机器可执行的层",缺了 CI 和 lint,它就退化成一句口号。
三个容易被误读的地方:
- 倒金字塔不是"不要文档"。文字规则仍然要写,只是用来处理判断类问题,并且必须能被机器检查兜底。
- "每月 2,000 个 PR"是结果,不是目标。作者在 pstack README 里明确写了相反的目标:写更少、但更高质量的代码。吞吐没有质量就不是目标。
- 这套方法吃工程能力。写一条"报错点名修复方式"的 lint、造一个 Agent 友好的 CLI,都需要人先有判断。它放大的是工程师的杠杆,不替代工程师。
一条隐含的风险:把判断写进 lint 的前提是判断本身正确。规则一旦写错,会被所有后续 Agent 忠实地放大 —— 这也是 /correct 要求"每条规则必须能在真实历史错误上触发"的原因:先证明它拦得住真问题,再让它进 CI。
出处与版本
pstack 位于 Cursor 的官方插件仓库 cursor/plugins/pstack,README 自述作者 poteto 在 Meta、Netflix、Cursor 工作过,并在 React core team 参与 React Compiler。技能目录里能找到文中用到的全部名字:teach、how、why、recall、architect、arena、correct、no-comments、technical-writing、create-verification-skill 等。architect 的说明要求先追踪受影响系统、画出两种不同形状再选;arena 明确评委不能来自父模型厂商;correct 的层级与前面列出的五条纪律一致。
仓库当前有 22 个剧本(skills/poteto-mode/playbooks/),早期版本为 23 个。每月 2,000 个 PR、500 万浏览、4 天 1,150 个 PR 与 lint-arch.sh 的具体实现,目前只有作者陈述,无法独立核对。
pstack 迭代较快,技能与剧本数量会变,引用时连同日期一起使用。
参考资料
关联词条
- Loop Engineering:让 AI 自主闭环运转(pattern)—— 让它自己转;本篇补的是"转起来之后怎么不跑偏"
- 自动化任何事:目标、流程与反馈回路(pattern)—— 同一作者面向非技术用户的方法:目标、流程、反馈、触发器
- Harness Engineering 与知识工程:数据研发企业落地实践(pattern)
- AI Friendly 知识库体系:后端系统知识显式化(pattern)—— 与"代码库即记忆"同源
- Harness(智能体执行框架)(concept)
- Pi vs OMP:同一份代码的两个答案(comparison)—— "看得见结构"的另一个证据:LSP/AST 与 lint 纪律同向
- 从模型到 Super-agent(concept)
- 返回 设计模式