企业官网建设流程全解析

pstack的how技能详解：走读子系统工作原理的完整方法

【免费下载链接】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 Code、Codex、Copilot、Pi 等智能体运行时的技能栈，其中的how 技能专门回答"某个子系统是怎么工作的"这类问题。它把"走读代码"变成一套可复用的标准流程：判断复杂度、按需派出并行探索代理（explorer）、再由讲解代理（explainer）合成一份让资深工程师快速建立心智模型的系统性说明。这篇文章带你完整看懂 how 技能的工作原理与产物结构。

什么是 how 技能，适合什么时候用

how 技能的定义写在 SKILL.md 的元数据里，它的适用场景非常明确：

• 代码走读：在动手改代码之前，先弄清"X 是怎么工作的"
• 归属与分层问题："这段逻辑应该放在哪里""哪个包负责这件事""这是正确的分层吗"
• 架构讲解：面向新接触某个子系统的工程师，解释其架构与运行时流程

一句话概括：how 技能产出的是"资深工程师入职某个子系统时需要的架构级讲解"——足以建立可用的心智模型，但不会写成逐行源码注释。

需要注意它与why技能的分工：how 解释"系统如何运转"，why 解释"当初为什么这么设计"。在 poteto-mode 的路由规则中，"不确定的架构决策"或"我们确认一下？"这类情况会直接路由到 how 技能，见 poteto-mode/SKILL.md。

第一步：评估复杂度，决定走哪条路径

how 技能的第一步不是读代码，而是判断问题复杂度：

一个实用原则写在技能定义里：拿不准时就走简单路径，避免为小问题付出编排成本。

简单问题：单代理直讲

直接生成一个general-purpose子代理（readonly: true，只读访问代码库），用 explainer-prompt.md 模板去掉"探索发现"部分后构造提示词，探索与解释一步到位，随后进入呈现环节。

复杂问题：并行探索 + 集中合成

这是 how 技能最核心的设计——分而治之：

1. 分解视角：把大问题拆成 2~4 个探索角度（angle），每个角度对应子系统的一个独立切面
2. 并行派出：所有 explorer 在同一条消息中一次性启动，每个都用 explorer-prompt.md 模板填入各自的角度
3. 合成讲解：等所有 explorer 返回后，启动一个 explainer 子代理，把所有发现填入 explainer 模板，整合成一份统一说明

explainer 的提示词明确要求它调和各 explorer 之间重叠甚至矛盾的描述：合并重复内容，遇到冲突时自己查代码裁决，把碎片拼成一张完整图景。

探索代理的五步走读法

explorer 提示词模板规定了一套严谨的探索方法论，值得单独拿出来看：

1. 找到入口点：什么触发了这个行为？用户操作、API 调用还是定时任务？
2. 追踪流程：从入口沿调用链走下去，读每个函数，弄清数据如何流转和变形
3. 梳理关键抽象：哪些类型、接口、服务是核心？读懂它们的定义与存在理由
4. 找出边界：子系统与外部如何交互？什么进、什么出
5. 留意不显而易见之处：有历史遗留吗？有什么新人容易误解的点吗？

模板里还有两条很有分量的纪律：

• 不要凭名字猜，去读代码（"Don't guess from names. Read the code."）
• 查不到就明说——"我无法确定 X 如何连接到 Y"比编造答案好得多

最终每个 explorer 返回结构化发现：组件清单（名称+文件路径+一句话职责）、执行流程、读过的文件、边界、非显而易见的细节，以及诚实列出的未解问题（Open Questions）。

讲解产出：固定的五段式输出

how 技能的最终说明采用固定的章节结构，不适用的部分可以省略：

提示词对文风也有硬性要求：用具体语言（"UserService 调用 AuthClient.refresh()"而不是"服务委托给客户端"）、复杂的东西要解释为什么复杂、简单的事物不要注水、有用的类比才用，没有就别硬凑。

模型与推理努力度配置

how 技能的两个角色在 models.json 中都有默认值：

• how explorer：opus
• how explainer：opus

你可以在本地覆盖表（pstack-models.md）中按角色改配模型，甚至指定推理努力度，例如opus @xhigh；通过/setup-pstack技能即可完成配置。在 Claude Code 上，带努力度后缀的角色会被调度到插件对应的pstack:effort-<level>或pstack:poteto-agent-<level>代理，模型名不受影响。

how 技能在整体工作流中的位置

how 不是孤立技能，它在 pstack 的多个剧本中反复出现：

• Bug 修复：用 how 对受影响子系统建立认知，配合 why 查回归历史，再开始二分定位，见 bug-fix.md
• 功能开发：动手前第一步就是"对受影响子系统运行 how"，见 feature.md
• 性能调优：先跑 how 确定真实负载维度，再选可复现的基准用例，见 hillclimb.md
• 调查研究：只读问题的标准入口，产出即 how 的五段式格式，见 investigation.md

完整的斜杠命令对照（/how、/why、/teach等）可查阅官方文档 docs/reference.md。

总结：how 技能值得借鉴的三点设计

1. 先分类再动手：用复杂度评估避免"大炮打蚊子"，简单问题单代理一次搞定
2. 读写分离：explorer 只负责采集事实（强调准确与彻底），explainer 只负责成文（强调结构与可读），职责切分让两边都能做到极致
3. 诚实优先：模板把"承认不知道"写成了明确的输出要求（Open Questions 章节），保证讲解的可信度

如果你想在自己的项目中实践这套方法，可以 clone 仓库后从 plugins/pstack/skills/how/SKILL.md 开始走读，它是理解 pstack 整套工作流技能的最佳入口。

【免费下载链接】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