pstack 拆解

一套面向资深工程师的精读系列。把 pstack 这台机器,从原则到调度,整台拆开讲清楚。

pstack 的来历

pstack 的作者是 poteto(X / GitHub)。她在 Meta、Netflix、Cursor 写过几百万行代码,同时在 React 核心团队,参与 React Compiler 的构建和维护。

她做这套东西的起点是一个判断:AI 正在写太多 slop,注水、低质的代码。而"跑得快但质量差"不是一个值得追求的目标。原文里有一句话被反复引用:

if you want to go fast, go deep first.

想快,先深。

pstack 就是她对这件事的回答。它不是新工具,而是她本人在 Cursor 每天用来交付高质量代码的那一套 skill 和原则。目标不是最大化代码量,恰恰相反,它帮你写得更少,但质量更高。

它最初是 Cursor 官方插件仓库 cursor/plugins 里的一个插件。后来有人在独立仓库 backnotprop/pstack 维护了一份镜像,让它能用在 Cursor 之外的 harness 里。它现在是一个有一千五百多颗星的独立项目。

pstack 是什么

pstack 是给 AI 编程用的一套工作系统。它把"怎么和模型协作、把代码写好"这件事,拆成了四层:

层	是什么	数量
Principles	公理。每条是一个"何时适用"的不变式	24
Skills	能力。how / why / arena / swarm / tdd 这些	28
Playbooks	程序。按任务类别编排 skill 的步骤	23
poteto-mode	调度。匹配任务、拷步骤、路由 skill	1

它们的关系一句话:底层把公理写一次,上层按名字引用。 你给一个目标,调度器匹配到一个程序,程序里的每一步触发能力,最后收在一个验证闸门和一份证据上。

它不是提示词合集,而是一套约束:让 agent 每一步都知道按什么标准做事,并留下能被检查的产物。

它解决什么问题

AI coding 之后,软件工程的前提变了。

以前,写代码和读代码的是同一群人,理解在写作里自然发生;评审靠人;状态靠人的记忆;质量靠人的手速和耐心。

现在这四条同时失效了:

• 你不是每一行的作者,读不完所有产出;
• 一个模型可以同时开几路、连跑几小时,人不该是那个盯梢的人;
• 干活的人(agent)不记得上一轮,也不会替你保留设计意图;
• 它能给出"看起来对"的代码,也会自信地写错。

于是问题从"怎么写得更多",变成四件必须重新回答的事:

1. 怎么确认它对。 在不满读每一行的情况下,凭什么相信这份代码是对的?
2. 怎么并行。 怎么让几个 agent 同时干活,而不互相踩、不一起漂移?
3. 怎么传达意图。 怎么把脑子里的设计和规则,变成机器能持续遵守的东西?
4. 怎么还敢负责。 在这么快的节奏下,责任仍然在你身上,凭什么?

它怎么解决

它做两件事:把模型的长处放到最大,再用结构挡住它的短处。对应上面四个问题:

• 怎么确认它对 → 验证闸门。 对着真实产物检查,而不是自述、代理或者"能编译"。
• 怎么并行 → 隔离加独立验证。 每个 agent 有自己的工作区,每个分支都能独立验证。
• 怎么传达意图 → 把规则搬进结构。 领域进结构,校验进边界,约束进类型,意图写进代码和文档,而不是留在人脑子里。
• 怎么还敢负责 → 判断的人不是生成的人。 关键的判断,交给一个没参与生成的模型或人来复核。

这些收在一句话上:想快,先深。 你必须先让每一步产出能被验证,才谈得上委托、并行和放手。

其中有一根承重柱,记住它就够:验证。它有两层意思,一是"什么才算证明"(对真实产物检查,不是自述或"能编译"),二是"谁来判断"(没参与生成的一方)。它成立之后,后面才安全:委托,因为每一步都会被检查;并行,因为每个分支都能独立验证;自主,因为"完成"由一个可检查的条件决定,不由 agent 自己说了算。

它带来什么

• 写得更少,质量更高。 目标不是行数,是在结果不变的前提下,引入的复杂度最小。
• 无畏的并行。 每个 agent 都能自证,你就敢同时开很多个。
• 可以放手的运行。 过夜跑、自动队列、项目级编排,都建立在"信得过"上。
• 一个会自己变好的仓库。 错误被编码成结构,而不是靠人反复提醒。

这个系列

这个系列把这四层逐层拆开。每个节点回答同样的三个问题:它解决什么问题,为什么非有它不可,它怎么调用下一层。

读完你能做到一件事:翻开任何一份 SKILL.md,都能反推出它为什么长成这个样子,并且精确地控制 agent 的行为。

怎么读

• 第一次,按顺序从头读。第一部分是原则,是后面所有内容共用的词汇表,跳过后面的会吃力。
• 已经用过 pstack,可以先看 37 · poteto-mode 与运行时,看四层合起来怎么跑,再回头补原则。
• 只想尽快上手,读 01、08、31、37,再按需翻其他章节。

其中第 08、09 篇是全系列的承重柱:整台机器能在并行、自主里安全地跑,都建立在"什么才算证明"上。

目录

第一部分 · 原则(10 篇)

地基。24 条原则按仓库自己的分类组织,是后面每一章共用的词汇。

• 01 · 少即是多(上) — 默认删、先减、用读者的负担衡量少。
• 02 · 重画与终态 — 新需求不硬贴,迁移朝终态收敛。
• 03 · 基础与体验 — 先定数据结构,为使用者而建。
• 04 · 探索与杠杆 — 没先例就造原型,把工作做成杠杆,反复失败就质疑前提。
• 05 · 领域与边界 — 领域进结构,校验进边界。
• 06 · 类型与状态 — 让非法状态无法表达,让操作幂等收敛。
• 07 · 迁移与并发 — 迁移即删除,先消除共享。
• 08 · 验证(上):真实产物与根因 — 对真实产物验证,追到根因。
• 09 · 验证(下):单元、行为与数字 — 小步可验证,测行为,解释数字。
• 10 · 委托与元 — 打破一个人的上限。

第二部分 · 能力(15 篇)

skill 是什么:一种具名的能力,由原则组合而成,带触发、输出和契约。

• 11 · 理解(上):它怎么运作 — 它现在怎么运作。
• 12 · 理解(下):它为什么长成这样 — 它为什么长成这样。
• 13 · 理解(三):讲清楚、找回来、看波及 — 讲清楚、找回来、看波及。
• 14 · 设计:先把形状摆出来 — 先把形状摆出来,而且设计两次。
• 15 · 对抗:让模型互相挑错 — 让模型互相挑错。
• 16 · 验证机械(上):测试与数字 — 先红后绿的测试,审数字的问题。
• 17 · 让 agent 能在应用里自证 — 让 agent 能在应用里自证。
• 18 · 让验证技能保持诚实 — 让验证技能保持诚实。
• 19 · 文体(上):去掉 AI 味 — 去掉 AI 味。
• 20 · 文体(下):文档标准 — 文档标准。
• 21 · 文体(三):注释与语言 — 注释交给没写它的人,语言规则。
• 22 · 自我改进:改仓库、改技能、生成入口 — 改仓库、改技能、生成入口。
• 23 · 可审计与定制流程 — 决策轨迹,为任务定制流程。
• 24 · 按角色配模型 — 按角色配模型。
• 25 · 入口与辅助 — 帮助、白话、汇总、小页面。

第三部分 · 程序(11 篇)

playbook 是什么:一段程序,编排 skill,带步骤、证据契约和完成契约。

• 26 · 调查与取证 — 先看清,再动手。
• 27 · 技能元:写技能与测技能 — 写技能与测技能。
• 28 · 构建:加行为、改结构、修缺陷 — 加行为、改结构、修缺陷。
• 29 · 性能与持续改进 — 性能与持续改进。
• 30 · 探路与对齐 — 探路与对齐。
• 31 · 开 PR:把工作变成 briefing — 把工作变成 briefing。
• 32 · 看门与落地 — 看门与落地。
• 33 · 自主运行与自动队列 — 自主运行与自动队列。
• 34 · 治理:把整个项目交给一个协调者 — 把整个项目交给一个协调者。
• 35 · 接续与挂起 — 接续与挂起。
• 36 · 计划与清理 — 计划与清理。

第四部分 · 调度(2 篇)

• 37 · poteto-mode 与运行时 — 四层怎么合起来。
• 38 · 取舍与上手 — 成本、边界,长出你自己的 mode。

一句话

这一整套东西,从头到尾只讲了一件事:可信。

生成变便宜了,可信没有。pstack 把"可信"这件昂贵的事拆成 24 个名字,组织成能力,组织成程序,再交给一个调度器,让 agent 能自己对着一件真实的东西证明自己的工作。信任一旦成立,委托、并行、自主才安全。

---

本系列的源码在 GitHub。pstack 的上游在 cursor/plugins,独立镜像在 backnotprop/pstack。