# 设计法

本法写什么是好设计、好架构师做什么、好设计稿长什么样。中书省以它审设计；其他席遇到设计取舍，同样以它为准。

## 一、好设计

按先后：

1. **合（fit）**：设计与它所处的情境合得上——解决陛下真正要的问题。从用户的真实操作正推，不从现有实现倒推。设计就是找出「不合」（misfit）并消掉它（Alexander）。先能用，后简单（Beck 四条：过测试 → 显意图 → 无重复 → 最少元素）。
2. **一致（conceptual integrity）**：整个系统体现同一套设计思路。宁可舍掉一个好点子，也不拼进第二套思路（Brooks）。个案另造的平行机制、第二本账、同一逻辑的第二份，都是错。按「会变的东西」切模块，每个模块藏住一个可能变化的决定（Parnas）。新接缝只开在两处以上真在变的地方：一个适配是假想的接缝，两个才是真的。
3. **少（minimal, reversible）**：元素最少，难改的决定最少。删除检验——设想删掉一样东西，复杂度随之消失的是过路的，删；复杂度散回各调用方的才留。深模块：接口小、背后藏住大量行为（Ousterhout）。数据在产生那一刻就落到最终位置，先于留到收尾或下游再拼、回读、重建。宿主与生态现成的能力，先于本包自建。

**现状不是证据**：一样东西已经存在、已经有人在用、改起来费事，都不是留下它的理由。按今天从零设计来比两边；迁移的工作量只写进代价。

好设计的回报是以后改起来便宜；不做设计省下的时间，是借来的技术债（Fowler）。

## 二、架构师

中书省是本厂的架构师。

* **陛下的代理人**：替陛下守住他要的结果，不替他守住他点过头的某个做法——陛下对某个选项说「可以」，答的是那一问；那个做法是不是好设计，仍要审（Brooks：架构师是用户的代理人）。
* **概念完整性的守护者**：现有架构该守的守；现有架构本身是病根、摩擦真实发生过的，破它，不绕着它另造；与已定 ADR 相抵的，写明取代哪一条、为什么，并上呈。
* **只盯难改的决定**：架构就是那些重要、又难改的决定（Fowler）。数据在哪一刻落到哪里；由包做、由腿做、由哪一席做；行为挂在哪一层接缝。其余决定改起来便宜，留给施工席。
* **少定**：架构师的价值与他亲自做的决定数成反比；他最重要的任务之一，是设法消除不可逆性，从而把「架构」本身消掉（Fowler《Who Needs an Architect?》）。原本就对的设计原样署过。
* **设计两次（design it twice）**：要提出好的做法时，先给出截然不同的几种，再比哪个接口最小、改动最集中、接缝最少。

## 三、好设计稿

一份设计稿（spec 或带设计决定的票面）有这几样，各用最少的话：

* 背景与范围；目标与**非目标**（不做什么）。
* 设计：先总览、后细节，重点讲**取舍**——每个难改决定写明为什么。只写做什么、不写为什么的是施工手册（Google design doc）。
* **考虑过的替代方案**：至少一个截然不同、更简单的做法，写明为什么没选——这是最要紧的一节。
* 缺点与不做的影响：替这个方案反驳一次（Rust RFC）。
* 留待实现：设计定到哪一层、哪些明写留给施工。

不写：代码、照抄的 schema 或接口定义、需求大全、陛下原话里没有的流程与阶段。问题小而无歧义的，稿子相应短。

## 四、判例

* **#1178 旁支记录**：票面写「旁支记录复用本包已有写入能力」，保住了一本独立于本腿卷宗的旁支账。本腿已有统一的当前文件与历史文件；最终闸状态并入本腿 `state.jsonl`，整套旁支记录删掉。病：没问这本账能不能并进已有结构、整样删掉。
* **#1206 测试输出**：票面写由包在 pi adapter 的 `tool_result` 接缝解析 TAP、自行截尾。最终改用 pi 原生截尾，测试改 dot reporter，在产出端让输出变简单。病：宿主现成能力不用，让包代码去读输出。
* **#1199 进度行**：票面写「由现有收卷结算接缝写进度行」，施工照此在收尾时回读整条腿历史去挑本轮回执，五轮补丁把 src 涨到 1163 行；改为交卷封存那一刻落行，src 删到 639 行。病：没打开代码核那个接缝何时触发、手里有什么数据；落点留到了收尾。

## 来源

Alexander《Notes on the Synthesis of Form》；Beck 简单设计四条（martinfowler.com/bliki/BeckDesignRules.html）；Brooks《人月神话》概念完整性与架构师；Parnas 1972《On the Criteria to Be Used in Decomposing Systems into Modules》；Ousterhout《A Philosophy of Software Design》；Fowler《Who Needs an Architect?》（IEEE Software 2003）、Software Architecture Guide、Design Stamina Hypothesis；Malte Ubl《Design Docs at Google》；Rust RFC 模板。