给 AI 编码代理装上资深工程师的工作习惯
一套 Markdown 规则，逼 AI 在动手前把问题想清楚、动手后拿出运行时证据，而不是写完就说"改好了"。
同时支持 Claude Code 和 Codex · 44 个技能 · 23 个 playbook · 21 条工程原则
中文 · English
npx @shiwenbin1617/pstack addpstack 提供按需使用的工程工作流。常规实现交给模型判断，保留项目约束、权限边界和与风险相称的验证。
本次指令精简依据 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/pstacknpm 上那个无 scope 的
pstack是 2015 年一个同名的无关包，不是这个项目。
pstack add --core # 核心入口及其自动展开的运行依赖，共 39 个
pstack add --all # 全装 44 个
pstack add how why # 按名字装指定技能
pstack add --core --host codex --memory # 只装 Codex，并写入 AGENTS.mdpstack 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 |
跳过确认 |
--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 安装各自的独立产物。
# Claude Code
/setup-pstack
# Codex
$setup-pstack
它探测你这个会话实际能用哪些模型，绑定三个档位：
| 档位 | 用在哪 |
|---|---|
| 快速代码模型 | 机械的、规格明确的改动 |
| 精确执行模型 | 需要一字不差按步骤执行的活 |
| 判断模型 | 文案、设计决策、对抗式评审 |
技能正文只说"用你的判断模型"，具体是谁由这里决定。Claude Code 写入 ~/.claude/pstack-models.md，Codex 写入 ~/.codex/pstack-models.md。两边配置互不读取。跳过也能跑，每个技能有自己的档位默认值。
# Claude Code
/poteto-mode 这个 PR 有个诡异的 bug。先复现，再修，再验证。
# Codex
$poteto-mode 给设置页加一个导出功能，支持 CSV 和 JSON，并拿出运行时证据。
读你的请求 → 匹配 playbook → 把步骤原样抄进 todo list → 按步骤调用其他技能。
Claude Code 的 /poteto-mode 保留原生粘性模式。Codex 不伪造该能力；每个新的独立任务显式调用 $poteto-mode，长任务使用当前 Codex 会话提供的 goal、wait 或 recurring-monitoring 能力。
/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 味 |
/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 回收磁盘 |
- 确认受影响的行为、职责和验收标准。
- 解决重要设计选择，已有模式明确时直接沿用。
- 直接实现，或将值得并行的独立工作交给子代理并检查产物。
- 运行与改动相称的项目检查，必要时验证界面或集成路径。
- 修复问题并交付可审阅结果。只有获得授权才提交或开 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-*，由上面的技能在需要时引用 |
展开 21 条原则
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） |
和 CLAUDE.md / AGENTS.md / .cursorrules 有什么区别？
那几个是常驻的项目规则，每次会话全量塞进 context，所以只能写短、写笼统（"用 TypeScript"、"测试放 tests/ 下"）。
pstack 技能按需加载。描述用于选择技能，正文提供必要约束，较长的条件流程放在引用文件中。feature 不强制委派，refactoring 优先复用已有行为测试。
两者不冲突：CLAUDE.md 写你这个项目的事实，pstack 写通用的工程方法。
只支持 Claude Code 吗？
不是。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 里加一项就行。
44 个全装会不会把 context 撑爆？
不会。常驻的只有每个技能的 description 那一行，正文按需加载。
Codex 那边有个硬限制：技能索引最多占 context 的 2% 或 8000 字符（取小），超了会先截断长描述。pstack 的描述都控制得比较紧，但如果你还装了别的技能包导致被截断，用 pstack add 挑一部分装，别 --all。
和 Trellis 这类框架冲突吗？
分工不同，但有一块会打架。
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 都欢迎。