teach-pqw-skills
Skill1 starsChanged 10 days agoMITView on GitHub
教人用 pqw-skills:讲这条流的心智模型、哲学与协作范式,人在每个环节做什么、代理做什么,第一条提示怎么写,跑偏了怎么纠。人问「这套流怎么用」「pqw-skills 是什么」「教教我」「我该做什么」,或装好后第一次提问时加载;只回答并给示例提示,不开工。要求干活的请求走 single-session-dev-flow,不加载。
In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- candid-friendSkill
- cleanupSkill
- clear-writingSkill
- context-packSkill
- delegate-briefSkill
- detailed-domain-designSkill
- domain-impact-analysisSkill
- formal-docs-landingSkill
- formal-guardSkill
- one-lesson-ruleSkill
- pass-the-batonSkill
- pqw-modeSkill
- progress-artifactsSkill
- requirement-and-invariantsSkill
- single-session-dev-flowSkill
- slice-closeoutSkill
- spec-and-planSkill
- tech-research-and-reuseSkill
- think-closed-loopSkill
- think-evidenceSkill
- think-model-firstSkill
- think-orthogonalSkill
- think-ought-vs-isSkill
- think-right-then-wellSkill
- think-unknownsSkill
- write-agents-mdSkill
The file
Files
教人用 pqw-skills
人问的是怎么用,不是要你开工。回答他的问题,给一条可以直接发出去的示例提示,说明答案来自哪个文件。一程研发要花真实的 token,什么时候开由人决定。要求干活的消息,例如「用这条流做 X」,不是提问:加载技能 single-session-dev-flow,在它之下工作。
先弄清他要什么
从消息和对话推断。能推断出来就直接答那一节。推断不出就问一个单选,只答选中的那节:
- 理解这条流的心智模型与哲学
- 第一次走一程,我要做什么、说什么
- 某个环节里人和代理怎样配合
- 跑偏了怎么办
- 接到我自己的项目
同时看两件事,只在影响答案时提:项目 AGENTS.md 有没有「pqw-skills 接入」一节,没有则收口里的结构读数、差分变异、文档检查会按「未提供」跳过;本机有没有装 pstack、ub-mode、mattpocock/skills,没有则引用它们的环节会断。
怎样教
从他正在做或打算做的事出发,不从流的第一步讲起。先给最小完整的答案,一两句,停下让他追问;他追问再加一层。讲机制不讲比喻:说清这一步为什么存在、少了会出什么事。三个以上部分的东西分几张图逐步画,每张在上一张之上加一个部分,不画一张全图。不出测验,不说「这里很重要」「关键在于」。用地道中文短句,一句一个意思。
心智模型与哲学
先读 心智模型与哲学 再讲。它按这几个问题组织:这条流在解决什么、为什么分两期一区、人的注意力为什么要抽离、你的验收产能是瓶颈、为什么验收是确定性的、为什么默认不派子代理、为什么要定时回看、三级与圈外、两条轴:流程与思维、为什么不走缩水版;最后一节「AI 主导研发交付的心智」十条,给他设计项目自己的合入检查、分支与人审规则时用。回答时只取他问到的那一两条。
问到「代理该怎么想」「这套流的品味是什么」时,读心智模型页的「两条轴:流程与思维」一节。流程轴是 13 个环节,回答走到哪一步;思维轴是七个思维模型技能,回答这一步怎么想:think-orthogonal(拆)、think-ought-vs-is(找差异)、think-model-first(定形)、think-right-then-well(建)、think-evidence(证)、think-closed-loop(转手)、think-unknowns(问)。人可以直接点名它们,例如 /think-ought-vs-is。
问到「代理为什么质疑我」「它为什么让我分程」时,讲 candid-friend(诤友):别的技能防代理的失败,它防人的失败。代理看到需求没有使用证据、一程大过他验得完的量、他离开前交接缺项、上一程没验就要交下一程,会用四行说一次:提醒、依据、建议、你可以。他定了,代理就照做,不打折扣,不在后面反复提。道理在心智模型页的「你的验收产能是瓶颈」。看到人这一侧的风险就说一次:提醒、依据、建议、选择。做法加载技能 candid-friend。
第一次走一程
按 谁做什么 讲人的部分:
- 先判断够不够格,判据是影响范围。不够格就不走,也不走缩水版:小修、定位问题、重构、调研这些按场景做,加载技能
pqw-mode。 - 第一条提示写目标、完成判据、已知事实和真实约束,不列技能不列步骤。写法在 提示怎么写。
- 定义期六步,每步代理会问什么、人要拍什么板。人在场,代理不替人认可。第 1 步代理会先问这件事值不值得做,问题一轮问齐,每问带着它的猜测,人答「对」就行。
- 交接期人要做什么:定约时认可 spec;定程时说清两个数,什么时候回来看、回来之后有多少时间上手验收,不说就按「当天回来,验收一小时」定一程的大小;代理说要分程时,照分、改,或说就按一程做;交出时确认核对单都过了,就可以离开。交接期像接力区:棒在区里交完,接棒的交付会话只跑这一程,不回头和你商量跑多远。一程的承诺、大小与交出收回归交接期,由设计会话做,人在场。做法加载技能
pass-the-baton。 - 离开后人会收到什么、什么时候需要回来。这一程交回来之后,回到设计会话:先按交付声明的「待人验收」上手验,验完告诉设计会话结果,它记进路线图、修订后面的程,再交下一程。
一句话就能开关代理开口的多少:想让它少问,说「这一程我定了,照做」;想让它多说,说「有顾虑就直说」。
某个环节怎样配合
先读 谁做什么 的对应行,再读该环节的 SKILL.md,然后才答。不凭记忆说一个环节做什么。
跑偏了怎么办
| 症状 | 一行纠偏 | 依据 |
| 小修也被走了整条流,或大改动没过够不够格就开工 | 「这是小修,不走流,按场景做」或「先判断够不够格」 | 入口的适用范围表;pqw-mode 的场景表 |
| 定义期代理替人拍板 | 「这个我来定」 | 定义期人主导,代理不替人认可 |
| 定义期跳步 | 「回到第 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,索引在入口的写代码的四条 |
| 一上来就动手改,或照着现象修 | 「先写应然」「本质解是什么」「别缝缝补补」 | 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 接入」,逐项填下面的槽位。技能正文里写「从项目接入点取」的地方都读这一节;没填的槽位按「未提供」处理,技能跳过该步并在交付声明里写明,不猜命令。这份 AGENTS.md 本身怎么写、怎么分层,加载技能 write-agents-md。
| 槽位 | 谁用 |
| 类型检查与 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 发行的常驻卡片原样放进自己的常驻入口文件,例如根 AGENTS.md:分隔线以下的部分,两句总纲,七个思维模型各一句,诤友一句,每句末尾是技能名。常驻入口文件每个会话都读,小修、原型这些不走流的工作也看得到它们。升级 pqw-skills 之后重新同步这一段。项目不手写第二份,自己的品味写在卡片之外,不重讲这几个模型的做法。
项目要跟着 pqw-skills 改的只有三样:上表的槽位名、交接信息包的节名、常驻卡片。它们合起来是接入约定,列在仓库的 design/consumer-contract.json,带一个整数 version。项目只钉这个 version:它不变的发行版直接换用,不必改项目自己的文件;它涨了,才回来改接入节、工单模板或卡片。
外部依赖按 README 的依赖表装:pstack、ub-mode、mattpocock/skills。
回复
先答。最多一条示例提示,放代码块。说明答案来自哪个文件,给已安装路径。不替人开工,不问「要不要现在开始」。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

