pstack

给 AI 编码代理装上资深工程师的工作习惯

一套 Markdown 规则，逼 AI 在动手前把问题想清楚、动手后拿出运行时证据，而不是写完就说"改好了"。

安装 · 使用 · 工作原理 · 技能清单 · 常见问题

同时支持 Claude Code 和 Codex · 44 个技能 · 23 个 playbook · 21 条工程原则

中文 · English

npx @shiwenbin1617/pstack add

为什么用 pstack

pstack 提供按需使用的工程工作流。常规实现交给模型判断，保留项目约束、权限边界和与风险相称的验证。

本次指令精简依据 OpenAI GPT-6 Astra Model Guidance 和 Eric Provencher 的技能与提示词实践。减少固定流程不等于取消安全门禁；实际效率改善仍需结合真实任务测量。

| 能力 | 作用 | |---|---| | 按需理解 | /how 解释行为和职责，/why 根据线索追查设计历史；简单问题直接回答 | | 设计判断 | /architect 处理尚未解决的接口与架构选择，必要时比较多个方案 | | 多模型对抗 | /arena 并行出 N 个方案再择优嫁接，/interrogate 让不同模型轮流攻击你的 diff | | 证据与风险相称 | 按实际行为选择测试或运行时验证，区分编译、Mock 与真实集成结果，通过后不重复检查 | | 23 个 playbook | 按任务选择流程；固定门禁用于实际契约和安全边界，普通步骤可按需调整 | | 21 条工程原则 | 需要深入判断时查阅，不要求每次加载或逐条汇报 | | 不留 AI 味 | /no-comments 清废话注释，/unslop 去 AI 腔，/technical-writing 规范 PR 和 commit | | 一次安装，两端可用 | 从公共方法论生成两个原生产物；Claude Code 与 Codex 的文件、代理和配置互不影响 |

目标不是让 agent 写得更多，而是写得更少、但每一行都站得住。

环境要求

• Node.js >= 18
• Windows、macOS 或 Linux。核心 CLI 与 Node helper 原生支持三者，不需要 Bash、WSL 或 GNU coreutils
• Claude Code 或 Codex（装了哪个就用哪个，两个都装会自动识别）
• Bun（可选；仅 babysit 的完整 PR watcher 和 orchestrate 账本 CLI 需要。helper 不会隐式安装依赖）

安装

npx @shiwenbin1617/pstack add

先单选装给哪个 agent：Claude Code、Codex，或者两个都装。本机探测到哪个，光标就落在哪个上。

然后勾选要装哪些技能：↑↓ 移动，空格 勾选，a 全选，回车 确认。默认预选 10 个核心入口。

这套东西是耦合的，装全了才有效果。 poteto-mode 会去读全部 33 个 principle 技能，所以不管你勾几个，安装时都会按引用关系补齐，勾满核心入口最后落在 44 个里的 39 个。省事就直接 pstack add --all。

最后问一次要不要把 pstack 那段写进 CLAUDE.md / AGENTS.md，见下面的「写进 CLAUDE.md / AGENTS.md」。

嫌包名长就装成全局，之后命令就是 pstack：

npm i -g @shiwenbin1617/pstack

npm 上那个无 scope 的 pstack 是 2015 年一个同名的无关包，不是这个项目。

其他安装方式

pstack add --core            # 核心入口及其自动展开的运行依赖，共 39 个
pstack add --all             # 全装 44 个
pstack add how why           # 按名字装指定技能
pstack add --core --host codex --memory   # 只装 Codex，并写入 AGENTS.md

管理命令

pstack list                  # 看装了什么、装在哪
pstack find review           # 按关键词搜技能
pstack update                # 重装已安装的（升级用）
pstack remove                # 交互式卸载
pstack doctor                # 检查两端的安装状态

以上都可以不装全局，改写成 npx @shiwenbin1617/pstack <命令>。

安装位置

两个 host 始终安装为独立副本。Claude Code 与 Codex 使用各自的调用语法、frontmatter、代理格式和配置路径。修改一边的已安装文件不会影响另一边。

~/.agents/skills/how/          ← Codex 技能，使用 $how
~/.codex/agents/*.toml         ← Codex 自定义代理
~/.claude/skills/how/          ← Claude Code 技能，使用 /how
~/.claude/agents/*.md          ← Claude Code 自定义代理

| 选项 | 作用 | |---|---| | --host claude / codex / both | 只装给指定 agent。默认自动探测本机装了哪些 | | --scope user / project | 装到全局 ~/，还是当前仓库的 ./.claude/、./.agents/。默认 user | | --copy | 显式使用独立副本；当前也是默认且唯一模式 | | --memory / --no-memory | 写不写 CLAUDE.md / AGENTS.md 里那段 pstack 说明。不给这个选项时，交互安装会问一次，非交互安装默认不写 | | --dry-run | 只打印会做什么，不写任何文件 | | -y / --yes | 跳过确认 |

写进 CLAUDE.md / AGENTS.md

--memory 会在常驻指令文件里维护一个 ## pstack 段落，说明技能副本的选择、工作流启用条件和模型配置位置。

写哪个文件由 host 和 scope 决定。Claude Code 写 CLAUDE.md，Codex 写 AGENTS.md；--scope project 写当前仓库根目录，--scope user 写 ~/.claude/CLAUDE.md 和 ~/.codex/AGENTS.md。

内容统一为两条中文规则，以 Codex 为例：

<!-- pstack:start -->
## pstack

- 使用当前项目指定的技能副本；存在同名技能时，优先使用项目级 `.agents/skills/`，缺少时再使用用户级 `~/.agents/skills/`，不重复加载两份。
- 仅在用户明确启用 `$poteto-mode` 时进入完整流程，授权限于当前任务。只有技能需要角色模型配置时才读取 `~/.codex/pstack-models.md`。
<!-- pstack:end -->

重复安装原地替换这一段，并合并重复的管理区块。已知的两种中文手写格式（旧版技能路径与启用说明、上面的两条规则）会自动加上标记并迁移；其他自定义 ## pstack 段落或损坏的标记会阻止写入，原文保留，可用 --no-memory 继续安装技能。代码块中的示例不参与迁移。

除明确迁移的旧格式外，区块外的内容保持不变。pstack update 默认只刷新已有管理区块；显式传入 --memory 可创建或迁移区块。--no-memory 不写入指令文件。卸载完最后一个技能时，管理区块会被一起删掉。

分发给同事

同事只需要一行：

npx @shiwenbin1617/pstack add --core

想固定版本或走内部源，把这个仓库发到私有 registry，之后运行 npx <你的包名> add。项目不提供 Claude Code plugin 入口，避免插件加载绕过 host adapter；Claude Code 和 Codex 都只通过 CLI 安装各自的独立产物。

使用

1. 配置模型档位（可选，但建议跑一次）

# Claude Code
/setup-pstack

# Codex
$setup-pstack

它探测你这个会话实际能用哪些模型，绑定三个档位：

| 档位 | 用在哪 | |---|---| | 快速代码模型 | 机械的、规格明确的改动 | | 精确执行模型 | 需要一字不差按步骤执行的活 | | 判断模型 | 文案、设计决策、对抗式评审 |

技能正文只说"用你的判断模型"，具体是谁由这里决定。Claude Code 写入 ~/.claude/pstack-models.md，Codex 写入 ~/.codex/pstack-models.md。两边配置互不读取。跳过也能跑，每个技能有自己的档位默认值。

2. 日常只用一个入口

# Claude Code
/poteto-mode 这个 PR 有个诡异的 bug。先复现，再修，再验证。

# Codex
$poteto-mode 给设置页加一个导出功能，支持 CSV 和 JSON，并拿出运行时证据。

3. 它会自己路由

读你的请求 → 匹配 playbook → 把步骤原样抄进 todo list → 按步骤调用其他技能。

Claude Code 的 /poteto-mode 保留原生粘性模式。Codex 不伪造该能力；每个新的独立任务显式调用 $poteto-mode，长任务使用当前 Codex 会话提供的 goal、wait 或 recurring-monitoring 能力。

4. 需要时直接点名

/how 我们是怎么取消 run 的？批量取消时有 N+1 查询吗？
/why 这个重试逻辑当初为什么写成指数退避加抖动？
/interrogate 审一下这个 PR。

Codex 上把 / 换成 $，例如 $poteto-mode。

工作原理

五段式循环

  ① 理解          ② 设计          ③ 构建          ④ 验证          ⑤ 交付
  ────────       ────────       ────────       ────────       ────────
  /how           /architect     写代码          /interrogate   /unslop
  /why           /arena         /tdd           验证技能        /technical-writing
  /recall        /blast-radius  /swarm         真实取证        /no-comments
                                                              开 PR / 合并

       └── 每一步都有出口条件，不满足就不进入下一步 ──┘

| 阶段 | 出口条件 | |---|---| | ① 理解 | 能不含糊地讲清楚从输入到输出的完整路径 | | ② 设计 | 接口和数据形状定了，实现只是填空 | | ③ 构建 | 代码能自解释，不靠注释撑着 | | ④ 验证 | 拿到运行时证据，不是断言 | | ⑤ 交付 | 人类要读的地方没有 AI 味 |

23 个 playbook

/poteto-mode 从这些里选一个匹配的：

| 类别 | playbook | |---|---| | 查问题 | investigation 只读调研 · bug-fix 复现→定位→修→取证 · perf-issue 对着 baseline 优化 · hillclimb 长期爬一个指标 · runtime-forensics 泄漏/空转/闪烁 · trace-forensics 分析 profile 文件 | | 写东西 | feature 从数据形状出发的新行为 · refactoring 保持行为的结构调整 · prototype 一次性原型定决策 · visual-parity 两套实现的像素级一致 | | 交付 | opening-a-pr · babysit 推 PR 到可合并 · shipping 独立验证后成串落地 · autopilot-full 每 PR 一个 owner 跑到合并 · autopilot-stack 构建 graphite stack 交人审 | | 长任务 | autonomous-run 不停机跑完 · orchestrate 多天多 PR 多 agent 常驻协调 · multi-phase-plan 跨阶段 · session-pickup 接手上个 agent 的活 · pause-safely 干净暂停留检查点 | | 元 | authoring-a-skill 写 SKILL.md · eval 盲测 prompt 改动的影响 · worktree-cleanup 清 worktree 回收磁盘 |

举个例子：feature playbook 的实际步骤

1. 确认受影响的行为、职责和验收标准。
2. 解决重要设计选择，已有模式明确时直接沿用。
3. 直接实现，或将值得并行的独立工作交给子代理并检查产物。
4. 运行与改动相称的项目检查，必要时验证界面或集成路径。
5. 修复问题并交付可审阅结果。只有获得授权才提交或开 PR。

普通改动不要求固定技能串联、并行度检查点或单独的日志。

技能清单

| 分类 | 技能 | |---|---| | 主入口 | poteto-mode | | 理解 | how why recall blast-radius teach | | 设计与构建 | architect arena swarm tdd typescript-best-practices figure-it-out | | 验证 | interrogate create-verification-skill maintain-verification-skill | | 写作 | unslop no-comments technical-writing bro | | 元 | setup-pstack automate-me reflect show-me-your-work | | 21 条原则 | principle-*，由上面的技能在需要时引用 |

boundary-discipline build-the-lever encode-lessons-in-structure exhaust-the-design-space experience-first fix-root-causes foundational-thinking guard-the-context-window laziness-protocol make-operations-idempotent migrate-callers-then-delete-legacy-apis minimize-reader-load model-the-domain never-block-on-the-human outcome-oriented-execution prove-it-works redesign-from-first-principles separate-before-serializing-shared-state sequence-verifiable-units subtract-before-you-add type-system-discipline

跑 pstack find 看带描述的完整列表。

资源

| 想做什么 | 看哪里 | |---|---| | 装包 / 看版本历史 | npm: @shiwenbin1617/pstack · GitHub Releases | | 提 issue 或 PR | github.com/shiwenbin1617/pstack | | 了解移植时改了什么 | adapters/claude-code.md · adapters/codex.md | | 跟着原作者走一遍完整任务 | docs/guide/ | | 改技能后做校验 | node scripts/build.mjs --check | | 生成两端的分发目录 | node scripts/build.mjs → dist/ | | Slack issue 自动三分类 | automations/benny/（需自行接 Slack MCP 和定时 agent） |

常见问题

那几个是常驻的项目规则，每次会话全量塞进 context，所以只能写短、写笼统（"用 TypeScript"、"测试放 tests/ 下"）。

pstack 技能按需加载。描述用于选择技能，正文提供必要约束，较长的条件流程放在引用文件中。feature 不强制委派，refactoring 优先复用已有行为测试。

两者不冲突：CLAUDE.md 写你这个项目的事实，pstack 写通用的工程方法。

不是。Claude Code 和 Codex 都支持，装的时候自动探测。

skills/ 保存公共方法论，构建器生成两个独立 host tree。Claude Code 产物使用 /skill、Markdown agents 和 Claude frontmatter；Codex 产物使用 $skill、agents/openai.yaml、TOML agents 和 Codex 路径。scripts/build.mjs --check 会拦住跨 host 泄漏。

想加第三个 host，44 个技能一个都不用动——写一份新 adapter，再在 scripts/lib.mjs 的 HOSTS 里加一项就行。

不会。常驻的只有每个技能的 description 那一行，正文按需加载。

Codex 那边有个硬限制：技能索引最多占 context 的 2% 或 8000 字符（取小），超了会先截断长描述。pstack 的描述都控制得比较紧，但如果你还装了别的技能包导致被截断，用 pstack add 挑一部分装，别 --all。

分工不同，但有一块会打架。

pstack 是无状态的——它管"干一件事的方法和标准"，不记跨会话的项目状态。Trellis 管的是 .trellis/ 里沉淀的 spec、任务、工作日志，解决"agent 每次从零开始"。

打架的地方是两边都有工作流编排（Trellis 的 plan→implement→verify→finish vs pstack 的 playbook），而且验证标准差很多：Trellis 的 check 跑 lint/type-check/测试，pstack 明确说这些都不算验证。

要组合的话，让 Trellis 管状态、pstack 管方法：把 pstack 的核心规则写进 .trellis/spec/，让它的自动注入把标准带进每个任务。

会有这个风险，所以 /poteto-mode 的定位是"需要严谨的任务"，不是所有任务。它匹配不到 playbook 时会退出来，不硬套。

另外有一条 laziness-protocol 原则专门管这个：能达到目标的最小改动才发版，"可能有用"的推测性清理要 revert 掉。

真嫌重就别用 /poteto-mode，单独点名 /how 或 /interrogate 就行。

公共方法论在 skills/，host 差异在 adapters/claude-code/ 与 adapters/codex/。修改后运行 node scripts/build.mjs --check，再分别 pstack update --host claude 和 pstack update --host codex。已安装目录不会互相同步。

改完跑 node scripts/build.mjs --check，它会检查 frontmatter 合法性、目录名冲突、相对链接可达、以及有没有写死模型名或某个 host 的工具名。

想让 agent 按你个人的工作习惯办事，用 /automate-me——它会翻你的历史会话，把你实际的工作方式起草成一个专属的 -mode 技能。

• Cursor 的 readonly 模式会剥掉 MCP 访问，Claude Code 的 Explore 子代理不会——保留 MCP 但去掉写文件能力。所以 why 和 reflect 里"请你别改文件"的口头约定改成了由 harness 强制。
• 依赖 cursor-team-kit 的技能（deslop、control-ui、control-cli）换成了自带的 /unslop 和 /create-verification-skill 生成的项目本地验证技能。
• 删掉 grokbot/make-bot-ui，它绑死在 Cursor 的 automation webhook 上，两个目标 host 都没有对应物。
• 上游写死的模型 slug 全部换成三档语义，具体绑定交给 /setup-pstack。

完整映射见 adapters/。

上游与许可

Fork 自 cursor/plugins/pstack，作者 Lauren Tan（@poteto，React 核心团队，前 Meta / Netflix / Cursor）。原作者的使用指南一并保留（内容仍以 Cursor 为背景，方法论完全通用）。

MIT License。改进和 PR 都欢迎。