panqiwei/pqw-skills

横切技能：诤友，直言一次，然后听你的。看到人这一侧的风险（需求不清或没有使用证据、一程大过人验得完的量、离开前交接缺项、上一程没验就交下一程、交付中追加范围）就对人说一次：提醒、依据、建议、你可以；人定了就照做，不打折扣。接需求复述之后、交接期定程时、交出之前、收回时加载；人说「有顾虑就直说」「值不值得做」「这一程是不是太大」，或点名 /candid-friend 时也加载。清楚的小修不加载，也不拿它当少做事的理由。代理回头看自己归 one-lesson-rule。

交付期第 13 步，清理：每切片清一次不必留给下一切片的中间产物，如子代理工作树、分支、临时数据；一程交付后全盘清理，含临时目录下的汇报件，并出交付声明。切片收口完成、一程交付完毕，或人说「清理一下」时加载。切片进行中不加载。

清晰写作规则：英文按 ASD-STE100，中文按不依赖语言的清晰性原则，用于撰写或改写文档、提示词、工具描述和 agent 指令，保留含义、情态与必需结构。新建或修订文档、规格、技能、提示词时加载；项目有自己的文档写作规则时从接入点读。不用于创意与营销文案。

交付期第 8 步，前置消熵：整程开工前派便宜子代理整理上下文包、主代理自己做关键模块的细化设计与技术验证；每切片开工前做开工包：上下文增量、技术设计与验证、细化推进方案、里程碑待办清单。spec 与 plan 写好之后、每个切片动手之前，或人说「整理上下文」「开工包」时加载。切片已开工不加载；写 spec 与 plan 归 spec-and-plan。

交付期第 9 步，派发：先按两个判据定自己做还是派，再过派发门；派时给齐目标与指令、边界、规格文件、信息包，框住读量，原始结果写进文件、报告限行。主代理准备派写者、评审者或验收者，或人说「派个子代理」「这活派出去」时加载。自己做的工作不加载。为什么默认自己做归 think-closed-loop。

定义期第 5 步，细化领域设计：对受影响的领域做 DDD 领域建模、遵循 SOLID 的对象关系模型，有存储时单独设计仓储与 I/O、写入、查询性能。领域影响与选型定好，或人说「细化设计」「仓储怎么设计」「对象关系」时加载。只改一个模块内部实现不加载。

定义期第 2 步，领域影响与顶层设计：从需求与不变式出发，按 DDD 分出重点、次要、连带领域，判要不要新领域，在全局做最粗粒度的设计作总边界。不变式清单定好，或人说「影响哪些领域」「要不要新领域」「先画个大边界」时加载。只在一个领域内部改实现不加载。

定义期第 6 步，正式落盘：判断哪些设计写成长期维护的正式文档、哪些以源码为文档，按产品、项目顶层、领域包组三层落盘，做五类判据的确定性文档评审；形式化件同样落盘并验证。细化设计完成，或人说「落盘」「写进正式文档」「评审文档」时加载。改代码不改设计不加载。

定义期第 4 步，形式化守护：碰到状态与操作就做偏函数定义与全化表；设计里出现较高性能要求、数据生命周期或状态机、并发与池化、跨领域边界要守的性质时，代理提出模型检查与证明的建议，人确认后数理建模、定理与证明，实施时转契约测试。四类触发之一出现，或人说「这块靠测试守不住」「证明一下」时加载。纯文档、纯界面、无状态无并发的改动不加载。

交付期第 10 步，定期回看（一堂课法则）：派一个便宜档的只读哨兵子代理常驻后台，持有 spec 与 plan，按一程预算定间隔，自己醒来取工作树事实，判偏离（含在圈外做功）、兜圈、腐化与子代理健康，写回看记录并给主代理发十行以内的消息；主代理在停顿点处置并写回 plan。进入自主交付期时加载并常驻，人说「定时回看」「起个哨兵」时也加载。人仍在逐步主导时不加载；回看后的汇报件归 progress-artifacts。

交接期，交棒：设计会话当编排者，和人一起走定约、定程、交出，把一程交给交付期；这一程交回来之后收回，人验收，记进路线图，再交下一程。定义期第 6 步过了、一程交回来了，或人说「交出去」「分几程」「这一程验过了」「交下一程」时加载，也可点名 /pass-the-baton。交付会话从交接信息包开工时不加载，它只读包；一程多大的立场归 candid-friend。

交付期第 12 步，向人汇报：用架构图、UML、可增量更新的快速 demo 等用完即弃的汇报件讲一段时间的关键进展与架构层面的前后差别，放系统临时目录下本会话本程的子目录。每次顶层回看之后、切片收口之后，或人说「汇报一下」「给我看看进展」时加载。人还在逐步看着时不加载。

定义期第 1 步，需求与不变式：把需求说成用户得到的能力与系统前后的差别，再和人一起列出系统永远要守住的不变式。人提出新需求、新能力，说「先把需求定清楚」「不变式是什么」，或流走到第 1 步时加载。已有不变式清单、进入领域分析后不加载。

单会话研发流的总入口：定阶段、顺序、交接期，指出每个环节加载哪个技能，不写环节的做法。用户提出复杂系统新增领域、跨多领域的功能纵线、子系统重构或较大规模改造，说「开一程」「按这条流来」，或点名 /single-session-dev-flow 时加载。小修、原型、小规模增量接口不走这条流，不加载；问这套流怎么用的，加载 teach-pqw-skills。本技能开头的「写代码的四条」（先做对；再做好一轮；不过度设计、不提前优化；找本质解）对一切写代码的工作适用，走不走这条流都一样。

交付期第 11 步，切片收口：主代理自跑类型检查与 lint，对照 spec 验收标准与不变式逐条核，结构读数与差分变异只打开工包写的关键位置，去 AI slop，在真实产物上跑一次；整程改动的全量读数在全部切片收口之后、交付声明之前做一次；全部用确定性上下文验收，不做对抗性评审。一个切片的 TDD 实施完成、全部切片收口完，或人说「收口」「验收这个切片」「全量读数」时加载。切片还在实施中不加载。

交付期第 7 步，plan；另管交接期定约时写的 spec：spec 在定约时和人一起写，定目标、边界与可核对的验收标准；plan 在交付期开头写，把这一程切成有序切片；自带两份模板，项目有模板以项目为准。定约时、交付会话从交接信息包开工时，或人说「写 spec」「出计划」「切片」时加载，也可点名 /spec-and-plan。定义期没走完不加载；分不分程归 pass-the-baton，开工前的上下文包归 context-pack。

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

定义期第 3 步，技术调研与复用：在需求、不变式与总边界之下选技术，先找现成的库、相近系统或社区实现，自造要有论证。总边界定好，或人说「有没有现成的」「选型」「要不要自己写」时加载。实现里顺手选一个库不加载。

思维模型：闭环。一件事要从一方转到另一方之前，先过三句：转手会丢信息，做对它要用到的写不下来的上下文多就不转；回路越紧越稳，决定后面很多步的事放在每一步都看得见的回路里；一块多大由接的一方验得完多少定。准备派子代理、把一件事交给人或另一个会话、定一程或一片多大、上下文快被压缩时加载；人说「这件事你自己做」「一块别太大」「多久看一次」，或点名 /think-closed-loop 时也加载。自己一口气做完、不转手的小活不加载。派发简报的写法与花费归 delegate-brief。

思维模型：用确定性证据说话。每个结论带证据或标签：量过的、推出的、猜的；证据要真的检验了它声称检验的东西，缓存命中、替身、被跳过的步骤和自己或子代理的自述都不算；证真交给证明，证伪交给测试，新测试先看它变红，完成只认 spec 的验收标准。准备说「做完了」「通过了」「是这个原因」、读子代理的交回、写验收或回看结论时加载；人说「证据呢」「先看它变红」「别信自述」，或点名 /think-evidence 时也加载。只是复述人刚给的事实不加载。

思维模型：建模先于代码。写碰到状态与操作的代码之前，先把每个操作写成偏函数，写明它在哪些前置状态下有定义；再全化，定义域之外的每一格给一个确定的答复，不变式排除的格写不可达；最后翻成领域模型与对象模型再写代码，每个类型能指回模型。设计或实现会话、任务、连接、资源这类有生灭的对象，加一个操作或一个状态，或实现里出现「不该发生」的分支时加载；人说「先建模」「全化一下」「状态表呢」，或点名 /think-model-first 时也加载。不碰状态的纯计算与纯文档改动不加载。

思维模型：正交、分形、矩阵。列清单、拆设计、划边界或定位一类反复出现的问题之前，先拆出独立变化的轴，每条轴归一个拥有者；把轴交叉成表逐格看，每格要么有答案要么写明不适用；再问这个结构在大一层和小一层是不是同一个，是就只设计一次。凭感觉列清单、同一个判断在两处各写一遍、一个概念的状态在决定另一个领域的事、特例越补越多时加载；人说「先找轴」「拆成矩阵」「这是同一个结构」，或点名 /think-orthogonal 时也加载。只有一个量在变、没有可拆的不加载。

思维模型：应然与实然。做设计、实现、优化、重构、定位问题，或准备把一件事交给人定之前，先答三问：它应该是什么样，它现在是什么样，两者差在哪；差异就是全部工作。开始一项设计或一个切片、同一类问题第二次出现、一件事做得比预计久、准备重跑贵的命令找原因时加载；人说「先写应然」「本质解」「别缝缝补补」，或点名 /think-ought-vs-is 时也加载。只查一个已知事实不加载。

思维模型：先做对，再做好。写代码分两轮：做对只求验收标准逐条过、测试先红后绿，不打磨；做好一轮不加能力，只改实现；好不好由结构读数、差分变异和一份品味核对单判，核对单每问指到代码位置作答。开始实现一个切片或一个修复、做对之后准备收口、发现自己一边找正确一边打磨时加载；人说「先做对」「做好一轮」「品味呢」，或点名 /think-right-then-well 时也加载。只改文档、不写代码不加载。

指导 AGENTS.md 的撰写与治理：创建、修订、压缩、评审或迁移 AGENTS.md，设计继承的提示作用域，判断内容归属，并协调父子文件的重叠与矛盾。新建或修订任何一份 AGENTS.md（或宿主的同类入口文件）时加载。