---
name: teach-pqw-skills
description: 教人用 pqw-skills：讲这条流的心智模型、哲学与协作范式，人在每个环节做什么、代理做什么，第一条提示怎么写，跑偏了怎么纠。人问「这套流怎么用」「pqw-skills 是什么」「教教我」「我该做什么」，或装好后第一次提问时加载；只回答并给示例提示，不开工。要求干活的请求走 single-session-dev-flow，不加载。
---

# 教人用 pqw-skills

人问的是怎么用，不是要你开工。回答他的问题，给一条可以直接发出去的示例提示，说明答案来自哪个文件。一程研发要花真实的 token，什么时候开由人决定。要求干活的消息，例如「用这条流做 X」，不是提问：加载技能 `single-session-dev-flow`，在它之下工作。

## 先弄清他要什么

从消息和对话推断。能推断出来就直接答那一节。推断不出就问一个单选，只答选中的那节：

- 理解这条流的心智模型与哲学
- 第一次走一程，我要做什么、说什么
- 某个环节里人和代理怎样配合
- 跑偏了怎么办
- 接到我自己的项目

同时看两件事，只在影响答案时提：项目 AGENTS.md 有没有「pqw-skills 接入」一节，没有则收口里的结构读数、差分变异、文档检查会按「未提供」跳过；本机有没有装 pstack、ub-mode、mattpocock/skills，没有则引用它们的环节会断。

## 怎样教

从他正在做或打算做的事出发，不从流的第一步讲起。先给最小完整的答案，一两句，停下让他追问；他追问再加一层。讲机制不讲比喻：说清这一步为什么存在、少了会出什么事。三个以上部分的东西分几张图逐步画，每张在上一张之上加一个部分，不画一张全图。不出测验，不说「这里很重要」「关键在于」。用地道中文短句，一句一个意思。

## 心智模型与哲学

先读 [心智模型与哲学](mental-models.md) 再讲。它按这几个问题组织：这条流在解决什么、为什么分两期一区、人的注意力为什么要抽离、你的验收产能是瓶颈、为什么验收是确定性的、为什么默认不派子代理、为什么要定时回看、三级与圈外、两条轴：流程与思维、为什么不走缩水版；最后一节「AI 主导研发交付的心智」十条，给他设计项目自己的合入检查、分支与人审规则时用。回答时只取他问到的那一两条。

问到「代理该怎么想」「这套流的品味是什么」时，读心智模型页的「两条轴：流程与思维」一节。流程轴是 13 个环节，回答走到哪一步；思维轴是六个思维模型技能，回答这一步怎么想：`think-orthogonal`（拆）、`think-ought-vs-is`（找差异）、`think-model-first`（定形）、`think-right-then-well`（建）、`think-evidence`（证）、`think-closed-loop`（转手）。人可以直接点名它们，例如 `/think-ought-vs-is`。

问到「代理为什么质疑我」「它为什么让我分程」时，讲 `candid-friend`（诤友）：别的技能防代理的失败，它防人的失败。代理看到需求没有使用证据、一程大过他验得完的量、他离开前交接缺项、上一程没验就要交下一程，会用四行说一次：提醒、依据、建议、你可以。他定了，代理就照做，不打折扣，不在后面反复提。道理在心智模型页的「你的验收产能是瓶颈」。看到人这一侧的风险就说一次：提醒、依据、建议、选择。做法加载技能 `candid-friend`。

## 第一次走一程

按 [谁做什么](who-does-what.md) 讲人的部分：

1. 先判断够不够格，判据是影响范围。不够格就不走，也不走缩水版。
2. 第一条提示写目标、完成判据、已知事实和真实约束，不列技能不列步骤。写法在 [提示怎么写](prompting.md)。
3. 定义期六步，每步代理会问什么、人要拍什么板。人在场，代理不替人认可。第 1 步代理会先问这件事值不值得做，问题一轮问齐，每问带着它的猜测，人答「对」就行。
4. 交接期人要做什么：定约时认可 spec；定程时说清两个数，什么时候回来看、回来之后有多少时间上手验收，不说就按「当天回来，验收一小时」定一程的大小；代理说要分程时，照分、改，或说就按一程做；交出时确认核对单都过了，就可以离开。交接期像接力区：棒在区里交完，接棒的交付会话只跑这一程，不回头和你商量跑多远。一程的承诺、大小与交出收回归交接期，由设计会话做，人在场。做法加载技能 `pass-the-baton`。
5. 离开后人会收到什么、什么时候需要回来。这一程交回来之后，回到设计会话：先按交付声明的「待人验收」上手验，验完告诉设计会话结果，它记进路线图、修订后面的程，再交下一程。

一句话就能开关代理开口的多少：想让它少问，说「这一程我定了，照做」；想让它多说，说「有顾虑就直说」。

## 某个环节怎样配合

先读 [谁做什么](who-does-what.md) 的对应行，再读该环节的 `SKILL.md`，然后才答。不凭记忆说一个环节做什么。

## 跑偏了怎么办

| 症状 | 一行纠偏 | 依据 |
| --- | --- | --- |
| 小修也被走了整条流，或大改动没过够不够格就开工 | 「这是小修，不走流」或「先判断够不够格」 | 入口的适用范围表 |
| 定义期代理替人拍板 | 「这个我来定」 | 定义期人主导，代理不替人认可 |
| 定义期跳步 | 「回到第 N 步」 | 顺序不能跳 |
| 交出之后，代理还一直来问 | 「看交接点核对单哪项没过」；都过了说「可以走了」 | `pass-the-baton` 的交接点核对单 |
| 交付会话来和你谈范围或分程 | 「这一程照包做；范围回设计会话谈」 | `pass-the-baton` 的两条规矩 |
| 交接信息包里写了下一程做什么 | 「包里只装这一程」 | `pass-the-baton` 的交出 |
| 派了很多子代理 | 「两个判据落在哪一格」「派发门三个理由是哪一个」 | `delegate-brief` |
| 设计取舍、判断验收、找根因这类事派了出去 | 「这件事你自己做」 | `think-closed-loop` |
| 说完成了但没有证据 | 「对照 spec 验收标准逐条核，贴命令和输出」「证据呢」「新测试先看它变红」 | `slice-closeout`、`think-evidence` |
| 评审变成挑刺，方案越改越大 | 「确定性验收，不做对抗性评审」「不过度设计」 | 入口的验收与自主两条 |
| 一边找对一边打磨，或在一处反复打补丁 | 「先做对，再做好一轮」「找本质解：写出共同前提再推翻它」 | `think-right-then-well`、`think-ought-vs-is`，索引在入口的[写代码的四条](../single-session-dev-flow/SKILL.md#写代码的四条) |
| 一上来就动手改，或照着现象修 | 「先写应然」「本质解是什么」「别缝缝补补」 | `think-ought-vs-is` |
| 清单凭感觉列，或同一个判断写了两遍 | 「先找轴」「拆成矩阵逐格看」 | `think-orthogonal` |
| 实现里出现「不该发生」的分支 | 「先建模」「状态表呢」「全化一下」 | `think-model-first` |
| 做好一轮只说「没有可改的」 | 「品味核对单，每问指到代码位置」 | `think-right-then-well` |
| 上下文压缩之后代理忘了这些想法 | 「重读 plan 的思维模型一行」 | plan 模板的进度总览 |
| 哨兵没有消息来 | 哨兵是后台的便宜档子代理，自己计时；宿主派不出后台子代理时退回备用做法 | `one-lesson-rule/hosts.md` |
| 汇报件看不懂 | 「只讲架构层面和前后差别，不讲代码」 | `progress-artifacts` |
| 交付后留下一堆工作树和临时文件 | 「按一程清理，出交付声明」 | `cleanup` |
| 代理没问值不值得做就开工，或一程大得验不完也直接做 | 「有顾虑就直说」「先做尺寸核对」 | `candid-friend` |
| 代理一件事反复提，或把提醒当成不干的理由 | 「这一程我定了，照做」 | `candid-friend` 的立场：说一次，然后服从 |
| 交付中加了范围，代理默默加进这一程 | 「记成下一程的输入，回设计会话再定」 | `candid-friend` 的「交付期与收回」 |
| 回来面对一大堆没验的东西 | 「先列待人验收，每样要几分钟」「截程交付」；下一次在定程时就分程 | `cleanup` 的交付声明、`one-lesson-rule` 的出口、`candid-friend` 的「一程的大小」 |

## 接到自己的项目

在项目 AGENTS.md 写一节「pqw-skills 接入」，逐项填下面的槽位。技能正文里写「从项目接入点取」的地方都读这一节；没填的槽位按「未提供」处理，技能跳过该步并在交付声明里写明，不猜命令。

| 槽位 | 谁用 |
| --- | --- |
| 类型检查与 lint 命令 | `slice-closeout` |
| 改动成员的合入检查（与项目合入检查同口径、只限改动成员、含全部测试层；没有写「同合入检查」） | `slice-closeout` |
| 结构读数的覆盖率文件、范围与带位线（工具自带，`--lcov`、`--scope`、`--cc`、`--crap`） | `slice-closeout` |
| 差分变异的范围与点名文件（工具自带，`--scope`、`--files`；修复轮 `--base` 取上一轮收口头；由 Stryker 执行，只支持 vitest 项目；多包仓库按成员 `--project`，用例导入构建产物的成员加 `--build-command`） | `slice-closeout` |
| 项目合入检查已按整程改动跑结构读数与差分变异时的命令（没有写「无」，一程全量读数由本流跑） | `slice-closeout` |
| 文档检查命令 | `formal-docs-landing` |
| 文档写作规则（项目自己的写作规范；没填用 `clear-writing` 自带的缺省规则） | `clear-writing` |
| 三层正式文档的位置 | `formal-docs-landing` |
| 统一语言与领域对象的位置 | `requirement-and-invariants`、`domain-impact-analysis` |
| 形式化工具链与声明边界 | `formal-guard` |
| spec 与 plan 的项目模板 | `spec-and-plan` |
| 项目专有的清理项 | `cleanup` |
| 验收处（接受者读证据的地方，例如工单评论；没填为本程目录） | `cleanup` |
| 子代理的模型与档位政策 | `delegate-brief` |
| 跨会话协调用什么（设计与交付分在两个会话时；没填用 GitHub issue，没有 GitHub 又没约定别的退回到文件） | `pass-the-baton` |
| 交接信息包与路线图放哪（一个会话走完或退回到文件时；没填放项目 tmp 下本程目录的 `handoff.md` 与 `roadmap.md`） | `pass-the-baton` |
| 不做与推迟的记录放哪（没填写在需求单里） | `candid-friend`、`requirement-and-invariants` |

接入节之外，项目把 pqw-skills 发行的[常驻卡片](../single-session-dev-flow/resident-card.md)原样放进自己的常驻入口文件，例如根 AGENTS.md：分隔线以下九行，六个思维模型各一句，诤友一句，每句末尾是技能名。常驻入口文件每个会话都读，小修、原型这些不走流的工作也看得到它们。升级 pqw-skills 之后重新同步这一段。项目不手写第二份，自己的品味写在卡片之外，不重讲这几个模型的做法。

项目要跟着 pqw-skills 改的只有三样：上表的槽位名、交接信息包的节名、常驻卡片。它们合起来是接入约定，列在仓库的 `design/consumer-contract.json`，带一个整数 `version`。项目只钉这个 `version`：它不变的发行版直接换用，不必改项目自己的文件；它涨了，才回来改接入节、工单模板或卡片。

外部依赖按 README 的依赖表装：pstack、ub-mode、mattpocock/skills。

## 回复

先答。最多一条示例提示，放代码块。说明答案来自哪个文件，给已安装路径。不替人开工，不问「要不要现在开始」。