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

# 单会话研发流

一程研发通常在一个会话里走完：人主导的定义期，代理自主的交付期，中间一段交接期。交接期像接力赛的接力区：设计会话在区里和人定好这一程的承诺与大小，把棒交出去；这一程交回来之后，人回到设计会话收回。定义期与交付期也可以分两个会话顺序交接，见「边界」。本技能只定阶段、顺序、交接期和每个环节加载哪个技能，环节的做法归各环节技能。

## 一句话

先在动手前把不确定性尽量消掉，再把执行放手给代理，再用固定节拍从顶层回看。人的注意力只花在定义边界和高层判断上。

## 怎么想：六个思维模型

流程回答现在走到哪一步，思维模型回答做这一步时怎么想。六个模型各回答一个问题，各是一个技能，随时可以单独加载，不走这条流时也适用。各环节技能与模板在要用到的那一步上有一行指路；哪个环节用到哪个模型，全表在仓库 README 的「思维模型」一节，机读的唯一源是 `design/context-map.json`。

| 模型 | 回答的问题 | 技能 |
| --- | --- | --- |
| 应然与实然 | 这件事的工作到底是什么 | `think-ought-vs-is` |
| 正交、分形、矩阵 | 这个问题的空间怎么拆 | `think-orthogonal` |
| 建模先于代码 | 代码该长成什么形状 | `think-model-first` |
| 先做对，再做好 | 按什么顺序建，怎样算好 | `think-right-then-well` |
| 用确定性证据说话 | 怎么知道它是真的 | `think-evidence` |
| 闭环 | 这件事该由谁做，一次做多大，多久看一次 | `think-closed-loop` |

放在一件事上的自然次序是拆、找差异、定形、建、证。一程、一个切片、一次小修走的都是这五步，只是篇幅不同。闭环讲这件事在人和代理之间转手，任何一步要交出去时用：交接期、派发、上下文压缩、向人汇报。

另有一个流程轴上的横切技能 `candid-friend`（诤友），它不是思维模型。六个模型管代理自己怎么想，诤友管代理对人说什么：需求不清、不值得做，或一程大过人验得完的量时，说一次，带依据和建议，人定了就照做。

六个模型与诤友各压成一句，就是[常驻卡片](resident-card.md)。接入的项目把它原样放进自己的常驻入口文件，代理在加载任何技能之前就看得到。

## 写代码的四条

这四条对一切写代码的工作适用，走不走这条流都一样；主代理自己写、派子代理写都按它。出处是 ub-mode 的「先做对，再做好，守实践」，完整原则加载技能 `ub-mode`。每条是一句结论，道理与做法在所属的思维模型技能里。

1. **先做对。** 先让需求要的能力正确兑现，验收标准逐条过，测试先红后绿，这一轮不打磨。先做对，再单独做好一轮。做法加载技能 `think-right-then-well`。
2. **再做好一轮。** 做对之后单独留一轮，不加能力，只改实现，spec 写明的性能要求不退化。先做对，再单独做好一轮。做法加载技能 `think-right-then-well`。
3. **不过度设计，不提前优化。** 差异之外的不做：只建当前需求要的东西，不变式排除的状态不处理，没有测量证明的瓶颈不优化。先答三问：应然、实然、差异。做法加载技能 `think-ought-vs-is`。
4. **找本质解。** 本质解就是应然与实然的差异本身，同一个前提下两次修补都失败就写出那个前提并推翻它。先答三问：应然、实然、差异。做法加载技能 `think-ought-vs-is`。

## 风险前置

设计错了，越晚发现越贵，损失按已经投入的量放大。所以写代码之前先论证设计是对的：定义期第 5 步的「方案论证」、每个切片开工包里的「方案论证」，论证不过不进下一步。领域建模与 SOLID 的对象建模每次设计都做；全化表碰到状态与操作就做；模型检查与证明只在命中第 4 步的触发时加做。先把状态与操作写成偏函数并全化，再翻成领域模型与对象模型。做法加载技能 `think-model-first`。工作量越大，论证越要做足。

## 圈外的问题

一程只对自己的承诺负责。定义期第 2 步把受影响的领域分成重点、次要、连带三级，按的是它们与本程改动的关系：重点是为兑现本程承诺而改的；次要、连带是因为本程的改动而必须跟着改或跟着验的，包括本程改动的每一个承诺的消费者。spec 的「责任分级」一节把这三级写成路径，那是写 spec 时的枚举，不是定义。三级之外都是圈外：改它的理由与本程的改动无关。

长程交付中会碰到圈外的东西：别的模块已有的缺陷、产品上设计了但还没实现的机制、和本程无关的失败用例、别人文档里与本程不一致的说法。它们不是本程的职责，也不是本程要先解决的冲突。修它要别人的设计上下文，还会越过原拥有者的治理权；为它停下来，要花人的注意力，而人的注意力最贵。

碰到问题时，先判它在哪一级，再按下表处置。主代理自己做和派出去的子代理都按它。

| 它在哪 | 处置 |
| --- | --- |
| 重点 | 是本程的，修 |
| 次要、连带 | 只做 spec 写定的那类改动（次要：契约与消费者同步；连带：接口与回归）。需要超出这类的改动，而且它不是本程的改动带出来的，按圈外处置，它是别人的设计 |
| 本程改动的承诺有未列出的消费者 | 它是连带，不是圈外：把路径补进 spec 的责任分级并升修订，照连带同步 |
| 圈外，不挡本程任何一条验收标准 | 在 plan 的「圈外发现」记一行：位置、现象、一条证据。然后继续。不调查、不修、不停、不问人 |
| 圈外，挡住了某条验收标准 | 先找圈内的绕法：替身、按现有契约的保守做法、把这条验收按 spec 待决规则收窄并写明。有绕法就绕，再记一行。没有绕法，只停依赖它的切片，在「圈外发现」写清挡住了哪条，把它列进收口时交给人的清单，其余切片继续 |

判圈的几条：

- 先问关系，再看路径：它要改、要验，是不是因为本程的改动？是，就在三级之内，路径没列就补上。不是，再看它落在「责任分级」哪一行的路径下，都对不上的就是圈外。例：本程改了「依赖不可用时等待」这条承诺，循环的转移表要为它加一条边，转移表是连带，哪怕 spec 没列它的路径；同一个转移表里一条与本程无关的旧缺陷是圈外。
- 产品正文写了、但 spec 没有采用的机制是圈外，不是本程的缺口。
- 「挡住」只看 spec 的验收标准：没有它，某条验收做不到或证不了。「有了它更好」「顺手就修了」不算挡住。
- 圈外发现在一程收口时一次交给人，不中途逐条上报。人要在中途知道的只有一类：圈外的东西挡住了验收而且没有绕法。

## 先判断够不够格

| 走这条流 | 不走这条流 |
| --- | --- |
| 复杂系统新增一个领域 | 小的缺陷修复 |
| 跨多个领域的功能纵线交付 | 快速原型，验证一个想法 |
| 子系统重构 | 小规模的增量接口设计与实现 |
| 较大规模的改造 | 一处局部修改，影响范围一眼看得清 |

判据是影响范围：改动会触及领域边界、跨域协作或系统全局的架构时才走。够格也有上限：一程的大小由人在一个验收窗口里验得完多少决定。这里只粗判，量明显超出时在第一条回复里说；细核在交接期的定程，见 `candid-friend` 的「一程的大小」。不够格的工作整条流都不走，不走缩水版，但思维模型照用，各一句话写在回复里：先答三问：应然、实然、差异。做法加载技能 `think-ought-vs-is`。先做对，再单独做好一轮。做法加载技能 `think-right-then-well`。每个结论带证据，证据要真的检验了它声称检验的东西。做法加载技能 `think-evidence`。然后直接按各自的技能做：加载技能 `mattpocock-skills:tdd`、`mattpocock-skills:prototype` 或 `mattpocock-skills:diagnosing-bugs`。人问的是这条流怎么用、自己该做什么，不是要开工，加载技能 `teach-pqw-skills`。

## 开工动作

1. 第一条回复先用自己的话复述人的目标、要解决的问题、预计的影响范围，不等确认。加载技能 `pstack:in-your-own-words`。证据排除了人要的改动，或看得出它解决不了人说的那个问题时，给出证据并停下。需求明显是几天的量时，同一条回复里先说一句「这可能要分几程」。看到人这一侧的风险就说一次：提醒、依据、建议、选择。做法加载技能 `candid-friend`。
2. 把下表的 13 个环节与交接期的四件事按表的顺序写进会话的任务清单，排在任何任务专有待办之前。宿主有任务清单工具就用它；没有就在项目 tmp 下本程目录写 `todo.md`。不做的环节留在清单里，写「跳过：<理由>」，不删。
3. 会话中途人说「新任务」或提出另一个需求，重新从够不够格判起。交付中人往这一程里追加范围，不在这一程里谈：回一句它会记成下一程的输入，由设计会话收回时定；一个会话走完时，交回之后同一个代理切回设计会话的角色做这件事。
4. 手里有一份[交接信息包](../pass-the-baton/handoff-pack-template.md)、要从交付期开工时：先跑 [`check-plan --handoff <包>`](../spec-and-plan/scripts/check-plan.mjs) 核结构，包在工单正文里时用 `--handoff -` 从标准输入读；第 1 步的复述改成对照包答四问；第 2 步的清单里第 1 到 6 环节与定约、定程、交出写「跳过：已在设计会话完成，见交接信息包」，收回写「跳过：归设计会话」，从第 7 步开工，不重走定义期。包里答不出四问或与正式文档对不上：退包，写明哪一处对不上，交回设计会话，然后停。这不是谈判，是包没合格。

## 阶段与环节

| 阶段 | 环节 | 加载的技能 | 产出 |
| --- | --- | --- | --- |
| 定义期 | 1 需求与不变式 | `requirement-and-invariants` | 需求与不变式单：用户可见差异、不变式清单 |
| 定义期 | 2 领域影响与顶层设计 | `domain-impact-analysis` | 领域影响分级表：重点、次要、连带领域；总边界 |
| 定义期 | 3 技术调研与复用 | `tech-research-and-reuse` | 复用论证单：直接复用、二次开发、二次封装或自造 |
| 定义期 | 4 形式化守护 | `formal-guard` | 形式化触发建议单；偏函数全化、模型与证明；转契约测试的清单 |
| 定义期 | 5 细化领域设计 | `detailed-domain-design` | 细化设计清单：领域模型、关系模型、仓储设计 |
| 定义期 | 6 正式落盘 | `formal-docs-landing` | 落盘决定表；三层正式文档并过评审 |
| 交接期 | 定约 | `pass-the-baton`；写 spec 加载 `spec-and-plan` | spec.md，人认可 |
| 交接期 | 定程 | `pass-the-baton`；一程多大加载 `candid-friend` | 切片大纲与人的验收窗口；分程时的路线图 |
| 交接期 | 交出 | `pass-the-baton` 的交接点核对单 | 这一程的交接信息包；人可以把注意力移开 |
| 交付期 | 7 plan | `spec-and-plan` | plan.md |
| 交付期 | 8 前置消熵 | `context-pack` | 整程上下文包与关键设计；每切片的开工包：上下文增量、技术设计与验证、细化推进方案、里程碑待办清单 |
| 交付期 | 9 派发 | `delegate-brief` | 过派发门；目标、边界、规格、信息包四件齐全的简报 |
| 交付期 | 10 定期回看 | `one-lesson-rule` | 哨兵定时唤醒的汇报；每 45 到 60 分钟的顶层回看记录 |
| 交付期 | 11 切片收口 | `slice-closeout` | 收口清单：类型检查与 lint、对照 spec、结构读数与差分变异（只打关键位置）、去 slop、证明可用；全部切片收口后一次整程全量读数 |
| 交付期 | 12 向人汇报 | `progress-artifacts` | 可视化、可上手、用完即弃的汇报件 |
| 交付期 | 13 清理 | `cleanup` | 每切片一次中间产物清理；一程交付后一次全盘清理与交付声明 |
| 交接期 | 收回 | `pass-the-baton` | 人的验收结果记进路线图；打回与没做的有了去处 |

## 怎样走

1. 定义期 1 到 6 顺序走，每步加载对应技能，产出填该技能的模板。人在场，代理不替人认可。
2. 交接期：定约写 spec，定程写切片大纲、问人的验收窗口、做尺寸核对，交出走核对单、写交接信息包。一程的承诺、大小与交出收回归交接期，由设计会话做，人在场。做法加载技能 `pass-the-baton`。交出之后人可以离开；交付期可以在同一个会话里接着走，也可以换一个会话从包开工。
3. 交付期先 7 写 plan：切片大纲是起点，可以在本程边界内重切，不改承诺。再 8 的整程包，然后按 plan 的切片循环：切片开工包（8）、做对（TDD，验收标准逐条过）、做好一轮（不加能力，只改实现）、收口（11）、汇报（12）、切片清理（13）。做对与做好一轮的分法加载技能 `think-right-then-well`。10 从第一个切片开工起常驻。9 只在派子代理时加载。
4. 全部切片完成后先做一程全量读数（11），再做一程清理与交付声明（13），出最后一份汇报件（12）。交付声明就是交回的东西。
5. 交回之后人回到设计会话收回：读交付声明，上手验收，记进路线图，按结果修订后面各程，再定约下一程或结束。

实施本身：方法加载技能 `mattpocock-skills:tdd`；执行风格加载技能 `pstack:poteto-mode`。

## 不可商量的

**顺序。** 需求先于不变式，不变式先于领域，领域先于架构，架构先于实施。走了这条流，定义期每一步都要有明确产出或明确的「本次不需要」结论，不能默认跳过。形式化守护里的模型检查与证明由代理建议、人确认，不自行投入；全化表碰到状态与操作就做，不等人确认。

**交接。** 交出是物理条件，不是感觉：没进唯一源、没过评审的边界，不算定好。设计会话是编排者，分不分程、次序与路线图都归它；交付会话只知道自己这一程，不和人谈范围。一次只交出一程。转手会丢信息，回路越紧越稳，一块多大由接的一方验得完多少定。做法加载技能 `think-closed-loop`。

**验收。** 切片和一程的完成只认 spec 的验收标准，不认任何子代理对自己工作的报告。验收与评审用确定性上下文：测试、证明、读数、变异、对照 spec 逐条核。不做对抗性评审。每个结论带证据，证据要真的检验了它声称检验的东西。做法加载技能 `think-evidence`。

**派发。** 主代理自己做是默认。派子代理是例外，要说出 `delegate-brief` 的两个判据落在哪一格、命中派发门哪一问。计划者就是执行者：plan 由主代理写，结果回来就修订，不交给别人规划再交给别人执行。

**自主。** 一程和每个切片都带时间预算，到了预算就回看，不继续跑。自主推进时按[写代码的四条](#写代码的四条)，不陷进细节。一程的大小由人在验收窗口里验得完多少决定，不由代理做得动多少决定，在定程时定；预计收尾滑出窗口时，按规则截程交付，或在处置里写明为什么继续，不问人。人睡前交一程夜里做是允许的：夜里只做机器判得出对错的活，只做人点名授权的不可逆动作，做完就停，早上第一行写等人决定的事。睡前交接与夜里的六样防法见 `candid-friend` 的「夜间一程」。看到人这一侧的风险就说一次：提醒、依据、建议、选择。做法加载技能 `candid-friend`。

**边界。** 一个会话里只有一个主代理和它的子代理。定义期与交付期可以在两个会话里顺序完成：设计会话交出交接信息包，交付会话从包开工，交回交付声明；两个会话之间怎么传，见 `pass-the-baton` 的「跨会话协调」。不做多会话并行协作。汇报件统一放系统临时目录下本会话本程的子目录，不进仓库；一程交付完毕的声明包含清理已做。各环节技能按需加载，不一次全读。项目的命令与位置（含跨会话协调用什么、交接信息包与路线图放哪）从消费者 AGENTS.md 的「pqw-skills 接入」一节取；没填的槽位按「未提供」处理，不猜。

## 容易混的环节

- `pass-the-baton` 管一程怎样交出去、收回来，spec 在它的定约里写；`spec-and-plan` 是写 spec 与 plan 的做法；`context-pack` 写动手前要知道的事。先有 plan，再做整程包与开工包。
- `one-lesson-rule` 是节拍，`progress-artifacts` 是内容。哨兵醒了先回看，回看有结论才出汇报件。
- `slice-closeout` 核承诺有没有做到；`delegate-brief` 的验收防作弊只管子代理交回的东西怎么核，不替代收口。
- `cleanup` 切片级只清中间产物；一程级连汇报件一起清，并出交付声明。
- `formal-guard` 的模型检查与证明是代理建议、人确认的守护；`tech-research-and-reuse` 的调研不替代它。
- 六个 `think-` 技能不是环节，不进任务清单。环节技能在要用到的那一步上指过去，做法仍在环节技能里。
- `candid-friend` 也不是环节，是流程轴上的横切：`one-lesson-rule` 是代理回头看自己，`candid-friend` 是代理回头看人。它只提醒，人定了就照做，不替人判断价值。