pstack 系列（2）：改代码之前，先看懂再设计

AI 编程助手接到“改一下这个功能”，常常直接从第一个看起来合理的地方动手，用的也是它第一个想到的做法。这篇教你用 pstack 的五个 skill 把顺序倒过来：先让 AI 说清楚代码现在怎么运行、为什么长这样，再让它比较几种设计，改完之后再找别的模型挑毛病。每个 skill 我都会说明什么时候用、命令怎么写（附可以直接复制再改写的示例）、它会一步一步做什么、你会拿到什么，以及下一步怎么接。最后用一个虚构的例子把五个串起来，再附一张“什么时候用哪一个”的对照表。

pstack 系列｜第 2 篇

• 系列导读：这套 skill 是什么、四篇该怎么读（尚未发布）
• 上一篇（第 1 篇）：安装、选模型，再用 /poteto-mode 挑 playbook
• 下一篇（第 3 篇）：写完代码之后，先证明它能用再合并

版本提醒：本文以 pstack 0.15.30 版为准，对应 cursor/plugins 的 commit eb4db2b（2026-10-22 14:08，台北时间），搭配 Claude Code 2.1.309。之后的版本，行为可能会改变。两篇查证时用的版本不同，列在下表（第 1 篇正文没有写 Claude Code 的版本号）：

	第 1 篇	本篇
pstack	0.15.29（88d4751）	0.15.30（eb4db2b）
skill 数量	56	57
Claude Code	2.1.306	2.1.309

0.15.29 到 0.15.30 只添加了 statechart 这个 skill。本篇用到的 how、why、architect、interrogate、arena、poteto-mode，以及 Claude Code 对照说明都没有改。我在 2026-10-24 10:31（台北时间）查证时，cursor/plugins 的 main 已经到 0.15.32（6dbc3ff）。eb4db2b 之后的 pstack 改动没有碰到本篇用到的五个 skill、poteto-mode 的说明文件，以及本篇引用的指南段落。

开始之前

pstack 是 Cursor 官方插件库里的一整组 skill。skill 是一份告诉 AI 怎么完成某类工作的操作说明。安装和选模型的方法在第 1 篇，这篇假设你已经装好了。

命令要加前缀。 pstack 的文档用 Cursor 的写法，例如 /how。在 Claude Code（在终端里使用的 AI 编程助手）里，插件的命令前面要加上插件名称，写成 /pstack:how。下面的示例都用 Claude Code 的写法；在 Cursor 里，把 pstack: 拿掉就好。

这五个 skill 不会自己启动。 它们都设置成不让 AI 自行调用，所以你要亲自输入命令。另一个做法是把任务交给 /pstack:poteto-mode，让它依任务自己排顺序：例如在提示里写“先不要改任何代码”，它就会走只读调查，自动先跑 /how，遇到“为什么”的问题再加上 /why。

下面会常出现“子代理”这个词：skill 运行时，会另外派出几个 AI 分头做事，每一个就是一个子代理。派出去的子代理越多，用掉的额度通常也越多。

先看懂，再设计，改完再审查。/arena 可以单独用，也是 /architect 内部用来比较草稿的工具。

/how：先弄懂代码现在怎么运行

什么时候用：要改一块不熟的代码之前；或是想问“这段代码该放在哪里、该由哪个模块负责、放在这一层对不对”。它只回答“现在怎么运行”，不回答“为什么这样写”，那是 /why 的工作。

命令怎么写：直接问你真正想知道的事。可以加上入口点和你最在意的部分：

/pstack:how <功能或模块> 是怎么运行的？请从 <入口，例如某个 API 或命令> 开始，说明数据怎么一路流动、每个文件负责什么。我最想知道 <你在意的部分>。

例如：

/pstack:how 用户登录之后，session 是在哪里创建、怎么过期的？过期之后前端会发生什么事？

它会怎么做：

1. 先判断问题的大小。问题范围不清楚时，它会先说出自己的理解，直接开始找；理解错了，你再纠正。
2. 简单的问题（单一模块、一个小工具、像“这个函数怎么运行”这种窄问题），只派一个子代理，边读边解释。拿不准时，它会选简单的做法。
3. 复杂的问题（跨好几个文件或服务的子系统、整体架构），它会把问题拆成 2 到 4 个角度，各派一个只读不写的子代理同时去读代码。
4. 全部读完后，再派一个子代理把结果整合成一份说明。
5. 把这份说明交给你，最多做些小幅润饰，不会大幅改写。

你会拿到：一份给资深工程师看的架构说明，大小刚好够你建立正确的理解，不会像逐行注解。用不到的段落会省略：

• Overview：这是什么、做什么、为什么存在。
• Key Concepts：读懂后面需要的类型（数据的种类和形状，例如一笔订单有哪些字段）、服务或抽象概念。
• How It Works：最长的一段，说明什么会触发它、一步一步发生什么、数据流到哪里。会指出具体的文件和函数；流程牵涉多个组件时，会附上流程图。
• Where Things Live：开始动手时要知道的文件和文件夹。
• Gotchas：不明显、容易踩到的地方。

下一步：如果你接着想知道“为什么会长这样”，就跑 /why。pstack 指南的建议顺序是先 how 再 why：先弄懂机制，再查历史。如果已经懂了、准备动手，就跳到 /architect。

/why：查出代码为什么长这样

什么时候用：想知道某段代码为什么这样写、当初为什么选这个做法、某个阈值从哪里来，或是追查一次退化（原本正常、后来坏掉）的来龙去脉。它特别适合在你动手改之前用，先知道哪些地方有它的道理、不能随便动。

命令怎么写：指出目标，说明你的问题。如果你是为了改它才问，记得说出来：

/pstack:why 为什么 <某段代码或某个决定> 要这样做？这个理由现在还成立吗？我打算 <你想做的修改>。

例如：

/pstack:why 为什么 API 的重试上限设成 5 次？这个理由现在还成立吗？我打算把它改成可配置。

如果你怀疑是历史包袱造成现在的混乱，也可以一次要两个：“先用 why 查历史，再用 how 说明现在怎么运行”。

它会怎么做：

1. 确认目标和问题。 你说得不清楚时，它会从对话的上下文推测你指的是哪段代码，简短说出它的解读，然后继续；猜错了你再纠正。
2. 先把代码的线索整理好。 包括文件和行号、关键的函数和常量、最近改过这段的 commit（commit 是 git 里的一次修改记录），以及这些 commit 对应的 PR（合并请求）和讨论。它会用 git blame（查每一行最后是谁、在哪次 commit 改的）和 git log 这类命令。
3. 分头找证据。 它会先看你接了哪些 MCP（让 AI 连到外部工具的接口，例如 issue 系统、Slack、Notion），把它们对应到七类证据：版本控制、issue 或工单、长篇文档、实时聊天、基础设施监控、错误追踪、产品数据。每一类有对应工具的，就派一个子代理同时去查。版本控制一定会查。没查某一类时，要写明原因。
4. 整合。 再派一个子代理，把所有发现依可信度整理：哪些有人明文写过，哪些是几个线索互相佐证，哪些只是推论，哪些查不到。
5. 交给你。 可以小幅润饰，但不会改掉原本表达信心程度的措辞，例如“看起来是”不会被改成“就是”。

你会拿到：一份每一点都附来源的报告，段落包括：问题、相关的代码、找到了什么、可以合理推论什么、其他可能的解释、还不知道什么、查了哪些来源、信心总结。“查了哪些来源”每一类一行，连没找到东西或跳过的也会列出来，并写明原因。“没有人写下原因”本身也是一种答案。

如果你说了是为了改代码才问，报告最后还会多一份限制清单：哪些要保留（Preserve）、哪些可以改（Change）、哪些要避免（Avoid），以及有什么风险（Risk）。

下一步：把这份 Preserve／Change／Avoid／Risk 清单带到 /architect，当作设计的限制条件。

/why 会用你接上的 MCP 去读 issue、文档和聊天记录，也会用 gh（GitHub 的命令行工具）读 PR 的讨论。开始之前，先确认你愿意让 AI 读到哪些数据。权限怎么收，可以参考装了第三方 skill 和 MCP 之后，你的 Coding Agent 多了哪些破口？。

/architect：写代码之前，先画设计草稿

什么时候用：不是小修小改、一动手就可能把结构定错的工作。pstack 指南的分法是：改动会跨过函数的边界，或会改变某段代码归谁负责，就值得用 /architect。

命令怎么写：说明要做什么，加上你最在意的地方。如果想在它动手实现之前先看设计，一定要写 with checkpoint：

/pstack:architect with checkpoint. 帮我设计 <要做的功能>，设计完先停下来给我看，不要实现。我最在意 <调用端怎么用／性能／之后好不好扩展>。限制：<上一步 /why 给的 Preserve／Avoid 清单>。

例如：

/pstack:architect with checkpoint. 帮我设计导入数据的流程，设计完先停下来给我看。我最在意调用端怎么用。

它会怎么做：它会先开一份待办清单，分成五个阶段。

1. Ground（打底）：对新代码会碰到的每一块，先跑一次 /how。如果这个设计会改变某段代码归谁负责、放在哪一层，也会跑 /why，把原本的理由变成限制，而不是用猜的。只有完全从零开始、没有现有代码要接的工作，才会跳过这一步。
2. Sketch（画草稿）：用 /arena 让几个子代理各画一份草稿，而且至少要有两份结构完全不同的设计，不是在同一个设计里改小地方。草稿只有类型、函数签名（函数的名称、参数和返回值）和模块的分工，函数内容先标成“尚未实现”或写成伪代码（看起来像代码、但不能运行的步骤说明）。每份草稿都会对照一份“设计警示”清单检查，例如对外接口很大、里面却没藏多少东西，或同一份状态有好几个模块在写。它会偏好对外接口小、把复杂度藏在里面的设计。
3. Agree（确认）：默认不会停，画完草稿就直接进入实现。只有你明确要求（例如写 with checkpoint 或“实现前先停下来给我看”），它才会把设计交给你，等你点头。你对设计有意见时，它会回到第 1 步重新打底、重画草稿，再继续写代码。
4. Implement（实现）：照草稿把“尚未实现”换成真的代码。草稿就是约定；实现时如果发现草稿没料到的需求，它要提出来，不会默默改掉。
5. Scrap（打掉重来）：如果实现一直卡住，例如同一种绕路写法在不相干的地方一再出现，或类型要靠强制类型转换才能编译，它会把草稿整个丢掉：重新跑 /how，把新发现当成一开始就知道的条件重新设计，先删减再增加，然后回到第 2 步。

你会拿到：先写好的“调用端怎么用”，再从它推出类型草稿。小改动是一个放新类型和函数签名的文件；大一点的工作是模块地图加类型定义。旁边附一页设计说明，包括：问题、调用端的用法、建议的结构、选了哪份草稿当底和原因、接受了哪些取舍、考虑过的其他做法、需要你决定的问题和风险，以及下一步先实现什么。

下一步：在 checkpoint 停下来时，回答设计说明里的问题，同意后它再往下实现。如果这个设计很重要、改错代价很高，可以在实现之前，先对草稿跑一次 /interrogate（草稿里已经有具体的类型和函数签名，不算抽象的计划）；不然就等实现完，再对改动跑 /interrogate。

/interrogate：找几个模型一起挑毛病

什么时候用：代码改完、合并之前，想找出自己和 AI 都没看到的问题。它要审的是实际的代码改动，不是抽象的计划：拿一份没有代码的计划去审，审查者容易想出一堆根本不会发生的风险。

命令怎么写：指出要审什么。范围可以是几个文件、一份 diff（两个版本之间改了哪些行），或整个 branch（git 里的一条开发分支）。加上“先不要改任何东西”和“不要挑小毛病”，结果会更好用：

/pstack:interrogate 审查这个 branch 的全部改动，要严格。先不要改任何东西。除非是真正的 bug 或行为退化，不要挑小毛病。

只审几个文件时：

/pstack:interrogate 审查 <文件或文件夹>。这次改动的目的是 <你想达成的事>。

它会怎么做：

1. 确定范围。 你指定了文件或 diff 就用那些；如果你在 feature branch 上，它会用 git diff main...HEAD 取出整个 branch 的改动；你提到最近的工作，它就去找相关的文件。
2. 先写一段“这次改动想达成什么”。 依据是你的消息、commit 说明、PR 说明和代码本身。不确定时，它会先问你，再往下做。
3. 派审查者。 你配置的每个模型各派一位审查者，标成 Reviewer A、B……，大家拿到同一份模板、同一份改动和同一套评分标准。它靠的是不同模型有不同的盲点，不是替每位审查者设置不同角色。
4. 合并结果。 把描述不同、但其实是同一个问题的发现合在一起，记下是哪些模型提出的。两个以上模型各自提出的问题，可信度最高；只有一个模型提出的也会看，但权重较低。
5. 主审判断。 由它扮演务实的资深工程师，把每个发现分到四类，各附一句理由。

你会拿到：一份结论，依序是：改动的意图、每位审查者用的模型和提出几项、四类发现，以及一张 Agreement Map（各模型在哪里意见一致、哪里不同）。四类是：

• Act on：会影响正确性、安全性或可维护性，真正的 PR 会因此被挡下来的问题。
• Consider：有道理，但现在处理不一定划算，值得你看一下。
• Noted：技术上没错，但现在不需要处理。
• Dismissed：错的、太琐碎，或缺少上下文，附简短理由。

它不会自动改你的代码。 要不要改、改哪些，由你决定。

下一步：先处理 Act on，再看 Consider。被归到 Dismissed 的也要读：主审只是务实的资深工程师，不是标准答案，你可以推翻它的判断。

同一份改动交给几个模型各自审查，再由主审分成四类。它不会自动改代码。

/arena：让几个 AI 各做一份，再挑最好的

什么时候用：只做一次，很可能就把做法定错的事。pstack 指南举的例子是命名、数据格式和算法这类单独的决定。你也可以拿它要第二意见：把你现在的设计当成其中一份，看看其他做法有没有更好的。它也是 /architect 第 2 步画草稿时用的工具。

命令怎么写：说清楚任务、为什么重要，以及你要几份。决定越重要，可以要越多份；不重要就少一点：

/pstack:arena <任务>。这件事很重要，因为 <之后很难改／会影响很多地方>。要 <N> 份候选，每份用自己的 worktree。

例如：

/pstack:arena 帮我决定缓存 key 的格式，要 3 份候选。这个格式之后很难改。

/pstack:arena 针对我们现在的做法给第二意见。

它会怎么做：它会先开一份待办清单，分成六个阶段。

1. Frame（定规则）：每份候选拿到的提示完全相同，所以提示就是约定。它会先写清楚每份候选要交出什么，再订 3 到 6 条可以打分的评分标准。评分标准是评审打分、以及它自己在第 4 步选底稿时用的，候选只看到任务。每份候选各有自己的工作位置（尽量用 git worktree，也就是同一个项目的另一份工作副本），避免互相覆盖。
2. Fan out（分头做）：同时派出 N 个子代理，各自完成任务，并附一段说明：考虑过哪些做法、为什么不选。有一份没交出东西时，就用剩下的 N-1 份继续，并记下来。
3. Cross-judge（评审）：所有候选都完成后，派一位只读不写的评审，尽量选和主对话不同家族的模型（例如 Claude 和 Grok 是不同家族）。评审依评分标准逐条打分，推荐一份当底。
4. Pick（选底稿）：它自己也把每份候选从头读到尾，逐条依评分标准打分，再和评审的结果比较。两边选的一样，就确定；不一样，就代表有一边有偏见，或评分标准写得不清楚，要再读两边的理由才决定。它会选一份之后最好扩展、又不容易破坏既有规则的版本。
5. Graft（嫁接）：再看一次落选的候选，每份通常挑一两个值得搬过来的优点，亲手融进底稿，而不是直接粘贴。如果几份候选做法一致，就直接用这个共同的做法，不必嫁接；如果彼此差太多，代表第 1 步的任务没讲清楚，要重新定规则再跑一次，而不是取平均。
6. Verify（验证）：像验证其他产出一样，验证合并后的结果。发现问题时，判断是第 1 步定错了（重来），还是某份候选其实抓到了、只是漏了嫁接（回到第 5 步）。

你会拿到：一份合并后的结果，加上一段简短的说明：选了哪份当底和原因、评审的结论、每一项嫁接来自哪份候选、哪些被舍弃和原因、有没有候选收敛或缺席，以及验证的结果。

下一步：如果产出是代码，合并前可以再跑 /interrogate。如果你要的是“每个包都检查一遍”这种覆盖，而不是比较做法，那是另一个 skill /swarm 的工作，不要用 /arena。

候选越多，派出的子代理就越多：N 份候选再加一位评审。

一个完整的例子（虚构）

以下是虚构的情境，只用来示范五个 skill 怎么接在一起，不是实际运行的记录，也没有附上任何输出。

假设你维护一个网站，现在每来一条通知（有人留言、有人点赞），系统就发一封邮件。你想加一个选项：用户可以改成每天只收一封摘要邮件。

1. 先看懂现在的通知怎么发。

/pstack:how 通知是从哪里触发、怎么排进队列、最后由谁发出邮件的？我最想知道发邮件这一步跟用户偏好设置是怎么接起来的。

读它的 How It Works 和 Gotchas，确认你知道发邮件的代码在哪里、有哪些容易踩到的地方。

2. 查清楚为什么现在是一条一封。

/pstack:why 为什么通知是每来一条就马上发，而不是整批发？这个理由现在还成立吗？我打算加一个“每日摘要”的选项。

因为你说了打算修改，报告最后会有一份 Preserve／Change／Avoid／Risk 清单。例如它可能提醒你，某类通知当初就是为了实时才这样设计，要保留。

3. 先画设计，停下来给你看。

/pstack:architect with checkpoint. 帮我设计“每日摘要邮件”这个选项，设计完先停下来给我看。我最在意现有的实时通知不要受影响。限制：<粘贴第 2 步的 Preserve／Avoid 清单>。

/architect 的第一步本来就会自己跑 /how，必要时也会跑 /why。这个例子前两步先手动跑，是为了先看懂代码、也先检查 AI 的理解有没有偏；如果你不需要亲自看，可以直接从这一步开始。它停下来时，读设计说明里“需要你决定的问题”，回答之后再让它实现。

4. 遇到一个单独的决定，交给 /arena。

假设设计说明里有一个问题：摘要邮件的内容要依时间排，还是依通知类型分组？这种单独的决定，可以另外交给 /arena：

/pstack:arena 帮我设计每日摘要邮件的内容格式，要 3 份候选。重点是让用户一眼看到最重要的通知。

5. 改完之后，合并之前审查。

/pstack:interrogate 审查这个 branch 的全部改动，要严格。先不要改任何东西。除非是真正的 bug 或行为退化，不要挑小毛病。

先处理 Act on，再看 Consider；Dismissed 也读一遍，不同意就推翻它。

这个例子是逐一手动调用每个 skill，好让你掌握每一步。平常你可以直接把目标和限制交给 /pstack:poteto-mode，它会自己决定要用哪些 skill、照什么顺序。这时候不要在提示里逐一列出 skill，那会打乱它原本排好的顺序；只有想改变默认做法时，才点名某个 skill。

什么时候用哪一个

pstack 指南先讲了一句很重要的话：大部分的改动，这些都不需要。下面是它建议的分法，加上 /how 和 /why：

情况	用哪个
要改一块不熟的代码，先弄懂它现在怎么运行	/how
想知道为什么这样写、改之前哪些不能动	/why（说明你打算改它）
一个已经改完的小改动，但你不放心	只用 /interrogate
改动会跨过函数的边界，或改变某段代码归谁负责	/architect（它会带上 /arena）
一个单独的决定，例如命名、数据格式、算法	直接用 /arena
有争议、改错代价很高的设计	先 /architect，合并前再 /interrogate
要做覆盖，例如每个包都检查一遍	不是这五个，用 /swarm
想交给 AI 自己判断	/poteto-mode，它已经内置这套分法

注意事项

• 额度：派出的子代理越多，通常越耗额度。/how 遇到简单问题只派一个，复杂时是 2 到 4 个探索者加一个整合者；/why 每类有工具的证据各派一个，再加一个整合者；/interrogate 每个模型一位审查者；/arena 是 N 份候选加一位评审；/architect 里面包含 /how、可能的 /why，还有一整场 /arena，派出的子代理通常是五个里面最多的。小改动不值得动用 /architect 或 /arena。
• /architect 默认不会停：想在实现前看设计，要写 with checkpoint。
• 不要只采用第一个设计：第一次做出来的设计，往往只是模型第一个想到的形状。重要的设计，用 /architect 或 /arena 多看几种。
• 不要审抽象的计划：/interrogate 用在实际的代码改动上。
• 不要全盘接受审查意见：/interrogate 会把意见分类并附理由，但最后由你决定，两个方向都可以推翻。
• 平行的 AI 不要共用一个工作目录：它们会互相覆盖，也分不出谁改了什么。用 /arena 时，可以要求每份候选用自己的 worktree。
• 版本：以上依 pstack 0.15.30 的说明文件整理，之后的版本可能会改变做法。

结论

用 pstack 改代码之前，顺序是：先用 /how 弄懂代码现在怎么跑，需要时用 /why 找出不能动的理由；再用 /architect 写好调用端的用法和类型草稿，记得加 with checkpoint 先看过；遇到单独的决定，用 /arena 让几份候选比一比；代码改完，用 /interrogate 让几个模型各自挑毛病，再自己决定改哪些。不是每次都要五个全跑：小改动直接改，改完不放心再审查就好。

延伸阅读

• 指南：Understand the code：/how、/why、/teach、/recall 各自适合的情况。
• 指南：Design：/architect、/arena、/swarm、/interrogate 和原型。
• 指南：Recipes and pitfalls：可以直接复制的提示和常见陷阱。
• 五个 skill 的说明文件：how、why、architect、interrogate、arena。
• pstack 系列（1）：安装、选模型，再用 /poteto-mode 挑 playbook：怎么安装，以及 /poteto-mode 怎么替任务排顺序。
• 自己写 Agent Skill：从写 skill 的角度看 SKILL.md 的结构和测试。
• 装了第三方 skill 和 MCP 之后，你的 Coding Agent 多了哪些破口？：agent 读得到哪些文件、权限怎么收。
• 另一套 skill 的做法：mattpocock/skills 系列导读、把模糊需求问清楚、先找出缺口，再决定要写规格还是拆工作单、代码写完之后，谁来看结构、审修改、解冲突、查资料、做交接、学新东西。