pstack的24条原则如何生效：poteto-mode的原则引用机制解析

【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Poteto's pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude

pstack-claude 是 Poteto 的 pstack（Cursor 技能栈）在 Claude Code、Codex、Pi 等 Agent 环境下的移植版，它把严谨的 Agent 工作流封装成一个个「技能（Skill）」。其中最核心的 poteto-mode 技能内置了 24 条工程原则，并设计了一套「触发 → 通读 → 署名 → 只引已读」的引用机制，让原则不再是墙上的标语，而是真正参与每次决策的约束。🎯

先认识 poteto-mode：技能的总入口

你不需要记住 24 条原则的名字。只要你说出目标，例如：

Use poteto-mode to fix the search filter resetting when I change pages.

poteto-mode 会负责整件事：匹配对应的 playbook（如 Bug fix）、调用 how 和 why 做调查、委派子代理实现、再复跑失败的用例验证。它内部还有一条「Non-negotiables（不可协商项）」触发清单，规定了什么场景下必须走哪个技能、哪条原则。

这条清单写在 SKILL.md 中，每条触发项都点名了对应的处理路径，例如：

• 任何代码 → 先命名数据形状，并按principle-model-the-domain选择组织结构
• 跨函数边界的代码 → 走architect技能
• 有争议的设计 → 走interrogate技能（多模型对抗评审）

24条原则的分组：从核心到元原则

24 条原则全部以独立的技能目录存放，按职责分为五组（分组结构见 SKILL.md 的 Principles 小节）：

每条原则的目录名即技能名，位于 plugins/pstack/skills/ 下。以 principle-laziness-protocol/SKILL.md 为例，正文只有几行可执行规则，并附一句「检验标准」：

The test:If a human developer would find the code exhausting to maintain, it is a bad solution.

再如 principle-prove-it-works/SKILL.md 要求：验证要看真实产物（运行功能、读真实值、看 diff），而不是「它能编译」或子代理的自述。每条原则的 frontmatter 里还有一行 description，写明「什么场景下应用」，这既是给模型看的触发条件，也是人类可查的索引。

原则引用机制：触发 → 通读 → 署名

poteto-mode 让 24 条原则生效，靠的是 SKILL.md 中四行关键约束，形成一条完整的引用链路：

① 触发条件内嵌在原则表里。Principles 小节开头写着「Read the leaf skill in full for any principle you apply」——要应用某条原则，必须通读它的叶子 SKILL.md。每条原则条目同时标注适用时机（"when it applies"），让模型能自己判断是否命中。

② 回复中必须署名。Non-negotiables 要求：在你的回复中，点名每条影响决策的原则，以及它具体改变了哪个选择。原则从「背景知识」变成了「可审计的决策依据」。

③ 只引本会话读过的。同一节明确规定：只允许引用本会话中真正通读过叶子 SKILL.md 的原则。想引用却还没读？先去读。这防止模型把没消化过的原则挂在嘴边。

④ 触发清单兜底。Non-negotiables 里的其余触发项（调查用 how、争议设计用 interrogate、长任务留决策痕迹等）与原则表互为补充，构成完整的「路由 + 约束」体系。

对新手来说，这套机制的直接收益是：你看到的每条回复，都能追溯「这个决定是哪条原则、哪一次通读支撑的」，而不是模型即兴发挥。

工程化保障：原则是「叶子」，不进命令菜单

这套机制不是靠自觉维持的，仓库的工具链在发布前就会校验它：

• 24 个principle-*技能的 frontmatter 必须带user-invocable: false，即原则只能被 poteto-mode 按路径引用，不进入用户的斜杠命令菜单，避免 57 个技能目录把菜单撑乱；
• tools/generate.mjs 在生成阶段检查这一约束，违反即报错中止；
• tests/invariants.test.mjs 用单测固化该不变量：任何 principle 叶子缺少user-invocable: false都会让校验失败。

文档中的口径也与此一致：整个包包含 57 个技能目录，其中 33 个是公开技能、24 个是principle-*引用，见 docs/reference.md。

上手路径：如何找到并扩展这些原则

1. 装插件：按 README.md 的三步，在你的运行时里安装 pstack；
2. 查原则：所有原则在 plugins/pstack/skills/ 下按principle-前缀排列，文件名即原则名，正文短小可直接通读；
3. 看路由：触发逻辑与 playbook 清单都在 SKILL.md 的 Playbooks 小节，22 个 playbook 覆盖了 Bug 修复、性能、重构、自动驾驶等场景；
4. 项目级定制：仓库支持在.agents/playbooks/下添加自己的 playbook，用extends声明基于哪个内置 playbook，再逐条修改步骤——这是把项目经验沉淀进原则体系的官方方式，校验脚本为 check-playbooks.mjs。

总结

pstack 的 24 条原则之所以「生效」，关键在于三点：每条原则是一个可通读的独立技能、引用必须署名且仅限本会话已读、工程化校验保证原则只作为叶子被引用。poteto-mode 把「原则」从提示词里的一句口号，变成了有触发条件、有通读义务、有署名义务、有测试守护的可执行约束。对使用者而言，你只需要说出目标，剩下的路由、引用与验证，由这套机制兜底。✅

【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Poteto's pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude