pqw-skills 的代理入口

这个仓库是你的。这里的技能和脚本归你所有。它沉淀的是你自己做长程研发时用的流程，它写得好，你下一次照它做事时就做得更好。

这个仓库沉淀单会话研发流：一个按场景路由的总入口技能、一个流的入口技能、十三个环节技能、一个交接期的阶段技能、一个教人用这套流的技能，加七个横切的思维模型技能与一个流程轴上横切的诤友技能，随插件发行。另有少数元技能只给维护本仓库的代理用，不发行。在这里工作的代理做的是维护技能，不是走这条流。走这条流去读 skills/single-session-dev-flow/SKILL.md。

这套技能为什么存在

长程的软件开发、维护与交付里，代理会一直面对同一组难题：设计会偏，代码会糙，边界会漏，上下文会腐化，人盯不住每一步。这条流和它的技能都是为了让代理在这种长程工作里做到下面五件事。维护这个仓库时，每个改动都拿这五件事当尺子。

1. 把控设计的正确性与合理性。 需求先于不变式，不变式先于领域，领域先于架构，架构先于实施。靠测试守不住的性质交给偏函数全化、数理建模与证明：证真交给证明，证伪交给测试。
2. 代码不只正确，还要优雅、整洁、有品位，性能满足需求。 仓储与 I/O 在设计期定下来；每个切片收口做结构读数、差分变异和去 slop；对自己和子代理同样要求品味。
3. 控边界，控熵。 领域边界与跨域协作先定后动；上下文包、技术验证、正式落盘、派发四要素，都是把不确定性从实施时搬到动手前。
4. 分阶段、增量、独立可验证、敏捷地交付。 spec 定边界，plan 切成有序切片，每个切片以 TDD 推进并独立收口，不过度设计，不过度优化。
5. 人的注意力到了某个阶段就从会话里抽离，之后只停留在高层。 交接期由设计会话和人一起定这一程的承诺与大小；交出是物理条件：这一程依赖的约束已在各自的拥有者处并过评审。约束指架构与领域边界、规格、静态检查与形式化件；这一程自己的材料留在交接信息包与过程目录。之后主代理自主推进，用时间盒从顶层回看，用用完即弃的架构图、UML 与 demo 向人汇报，让人只看架构、产品和交互体验，不看技术与代码细节。

这五件事是目标，流和技能是手段。一个改动如果让某一件更难做到，哪怕它让流程更顺或更短，也不要做。一个环节如果已经有外部技能做得足够好，引用它，不要为了完整而自己再写一份。

验收与评审的品味

验收和评审用确定性的上下文：测试、形式化证明、结构读数、差分变异、对照 spec 的验收标准逐条核。不做对抗性评审。对抗性评审的上下文常常和实施方不对齐，结果是过度设计、过度优化，和陷进鸡毛蒜皮的细节。评审者拿到的是 spec、不变式、改动和读数，核的是「承诺的有没有做到、守的有没有守住」，不是「我会不会这样写」。

同一条品味也约束主代理自己：自主推进时不过度设计、不过度优化、不陷进细节。ub-mode 讲的先做对再做好，本质就是这个。

这套技能是什么

一条为大改动设计的研发流。定义期由人主导，六步从需求走到正式落盘；交接期由设计会话做、人在场，定约、定程、交出一程，交回之后收回；交付期由主代理自主推进，七个环节覆盖 plan、前置消熵、派发、定期回看、切片收口、向人汇报与清理。它只用于复杂系统新增领域、跨多领域的功能纵线交付、子系统重构和较大规模改造；不够格的工作不走，也不走缩水版。

维护与迭代的心智

维护这个仓库也按两句总纲。少即是多：复杂度花在真实差异上，入口保持薄，没人用的删掉。慢即是快：从观察到的失败改起，带与不带各走一遍，约定的验证跑完再发版。

• 从观察到的失败改起。 改一个技能的理由是某次真实会话里代理走偏了、漏了、绕了，而不是「这样写更完整」。记下那次失败是什么，改完后说清楚它怎么被防住。
• 先问改的是哪一层。 是这件事属于哪个场景、去哪个技能（总入口 pqw-mode），是流的顺序（流的入口），是交接期怎样交出与收回（阶段技能），是某个环节的做法（环节技能），是做事时怎么想（思维模型技能），是代理对人说什么（流程轴上的横切技能），还是外部技能的行为（去外部仓库提）。改错层会让总入口越写越厚，或者让环节技能互相复制。
• 先保护不变量，再求顺手。 定义期顺序、交出的物理条件、一次只交出一程、派发四要素、时间盒回看，这些是流的不变量。为了少写几行而松动它们，就是在削弱第一节的五件事。
• 复杂度花在真实差异上。 本仓库只写外部技能没有覆盖的部分：我们的阶段划分、形式化的触发条件、一堂课法则、汇报件的要求。通用做法引用外部。
• 每个技能都要能单独加载、单独说清。 一个环节技能被单独读到时，读者要能知道它在流的哪一步、前后是谁、产出是什么。总入口是路由，不是唯一的上下文。
• 留痕但不留工作日志。 改动的理由进 CHANGELOG.md，正文只写最终做法，不写「原来是」「这次改成」。

布局规则

• skills/ 扁平，不分桶。每个技能一个目录，目录里一个 SKILL.md，附件放同目录并由 SKILL.md 链接。
• meta/skills/ 放只给维护本仓库用、不随插件发行的元技能，目前没有。写作与 AGENTS 维护的两个技能（clear-writing、write-agents-md）随插件发行，在 skills/ 下，维护本仓库时同样用它们。
• pqw-mode 是整套技能的总入口，场景轴的索引：先看叠加的条件，再从上往下认场景，每个场景只写判定、过哪几个思维模型、去哪个技能。它不写做法，不管执行风格，正文 50 行以内。场景只组合思维模型与能单独用的工具，不组合阶段；加一个场景之前先确认七个模型里至少有几个对这类工作有话说，没有就指到外部技能，不设行。
• single-session-dev-flow 是流的入口，pqw-mode 的「大改动」一路。它只写适用范围、阶段、顺序、交接期和每个环节加载哪个技能。环节的做法写在环节技能里，不写进总入口。
• 流程轴上的阶段技能（pass-the-baton）是交接期的家，不是编号的环节，也不是思维模型，不进矩阵。它的指路行登记在 design/context-map.json 的 stages，核法与 crosscut 相同；正文 60 行以内，细节放同目录展开页。
• 环节技能分两类。自定义的，正文在本仓库。引用外部的，正文只写本仓库的补充和「加载技能 <技能名>」，不复制外部正文，不用相对路径跨目录链接。
• 思维模型技能用 think- 前缀，横切，不是环节。每个照同一副骨架写：一个问题、三句动作、按工作类型的表、写在哪、什么时候必须重做、相邻的模型；正文 50 行以内，细节放展开页，至多五页。它在哪个环节出现、以什么形式出现（主、行、空），唯一源是 design/context-map.json，改一格先改地图，再改环节技能与模板。环节技能里只放一字不差的指路行与模板空位，不复述模型的做法；环节自己的做法留在环节技能里。加一个模型就是给地图加一列，再照骨架写一个技能。
• 流程轴上的横切技能（candid-friend）不是思维模型，不用 think- 前缀，不进矩阵。它在哪些环节出现，登记在 design/context-map.json 的 crosscut，核法与模型的格相同；正文同样 50 行以内。两句总纲加每个模型与它各一句，压成发行的常驻卡片，消费项目原样放进自己的常驻入口文件；改卡片的一句先改对应技能。
• 两句总纲管着七个思维模型：少即是多，慢即是快。两句各带限定语：少的是范围与产出，不是验证；慢的是不可逆的和决定后面很多步的地方，不是所有地方。它们登记在 design/context-map.json 的 spine：每个模型恰好归一句，常驻卡片、pqw-mode、流的入口与教学技能的心智模型页含这两句，一字不差，代理从哪个入口进来读到的都是同一套。改一句先改地图。加一个模型先定它归哪一句；两句都归不进去，先怀疑它是不是一个模型。
• 连通性也登记在 design/context-map.json。流程轴技能（13 个环节与 pass-the-baton）的正文开头各有一行位置行：在流的哪一步、上一步、下一步、入口；它由地图的 flow 生成，上一步与下一步互逆，增删或调换环节先改 flow。思维模型与横切技能不在顺序链上，各带地图的 up 一行回到总入口。每个发行技能至少被另一个技能点名一次。这些行在正文前几行或固定位置，上下文压缩之后还在。
• 外部技能的名字、来源与版本登记在 README.md 的依赖表。改引用先改那张表。
• 增删或重命名技能同步三处：skills/ 目录、.claude-plugin/plugin.json 的 skills 数组、README.md 的技能表。三处对不上就是缺陷。README_EN.md 的技能表与依赖表跟着 README.md 改。

写作规则

• 技能名用英文短横线。正文用地道中文。专有名词保留原文，例如 Claude Code、Codex、Cursor、TDD、DDD、SOLID、CRAP；普通技术名词用中文，例如代理、技能、子代理、上下文包。
• frontmatter 的 description 是一直在模型上下文里的指针，每个字每回合都付钱。固定语法：环节号与环节名领头，一句做什么，触发写前置产出就绪与人会说的两三句原话（加 /<name> 点名），一条最容易误触的不加载，容易混的技能末尾一句指过去。不写正文已经承担的方法细节，不写营销语。依据在 design/description-and-entry-study.md。
• 正文先写回答的问题或规则，再写产出，再写外部引用。每节短，一句话一个意思，能用表就不用段落。
• 一个技能调用另一个技能，写成「加载技能 <名>」的明确指令，不写宿主的工具名，一次一个技能。只写模型可自动加载的技能。外部技能声明了 disable-model-invocation: true 时（Matt 的 to-spec、to-tickets、to-questionnaire），写成「按已安装路径直接读正文，并在报告里写明读取方式」，不写成 Skill 工具调用。
• 全仓库散文不用破折号。不写工作日志式的句子，不写「我们现在」「这次」。
• 骨架阶段的技能末尾保留「## 待写」节；正文补全后删掉这一节。

维护

• 改技能行为后在 CHANGELOG.md 记一条，改 .claude-plugin/plugin.json 的 version。两处一起改。
• 改清单后跑 claude plugin validate .。不用 --strict：它把根目录 CLAUDE.md 不作为插件上下文、以及没有图标这两条警告算失败，这两条是有意接受的。
• 本机开发用 scripts/link-skills.sh 把每个技能软链进 ~/.claude/skills 与 ~/.agents/skills。增删重命名后重跑。
• STRUCTURE.md 描述目录与和 mattpocock/skills 的差别。布局变了就同步它。本机开发与发版步骤归 DEVELOPMENT.md，参与规则归 CONTRIBUTING.md，两者都是给人看的，不在这里重复。
• 不新增仓库级机制。单人维护，少一层工具胜过多一层自动化。
• 用 Claude Code 的 skill-creator 插件审技能：删冗余、去重、重组。量每个技能的成本与使用率，没人用的删掉，宿主有 /skill-doctor 一类报告就用它。
• 改一个技能后，带与不带各走一遍同一程，留好的那个。一次只改一处。
• 入口技能保持薄。往入口加规则前先问它是不是该归某个环节技能。

边界

• 这里只放流程与方法，不放任何项目的架构、领域或产品正文。项目专有的规则归项目自己的 AGENTS.md。
• 外部技能的缺陷去外部仓库提，不在这里打补丁复制一份。
• 不够格走这条流的工作不要往这条流里塞缩水版。流的价值在于完整，不够格的工作由 pqw-mode 按场景路由，不改流的入口。

写给在这里工作的代理

这里的每一个技能都是你的。它们越清楚、越准，你带着它们做的每一程就越省力、越少走偏。