代码设计

为什么需要这个工作流

设计的敌人不是简单，而是没有根据的复杂。Code Design 要求先命名真实的设计压力，再选技术：没有观察到压力，就不引入新抽象。任何不常见的写法都要交"新奇税"——在正确性、实测性能、框架一致性或总维护成本上给出具体收益。它的产出是方案，不是代码。

流程逐阶段拆解

下面每一条规则都取自源仓库里的工作流定义——这就是智能体真正被要求做的事。

1. 01

   选择设计模式

   从零设计和完善已有设计，问的问题完全不同。

   • 全新 / 探索：你有目标或问题，但方案还没定下来。
   • 完善：你给出已有的方案或设计文档，需要纠错、补全或简化。
   • 如果要实施的是已经接受的设计，用 Develop；如果是现有行为坏了，用 Diagnose。
2. 02

   建立问题与本地上下文

   把已接受需求、仓库事实、可逆选择和开放决定分清楚。

   • 明确用户问题、期望结果、验收行为、约束和范围外。
   • 有仓库时，读项目指令、权威文档、既有能力、代表性代码和测试。
   • 只询问会实质改变产品行为或可行方案空间的未决问题。
   • 区分开：已接受的需求、仓库事实、可逆的设计选择、开放的产品决定。
3. 03

   探索设计压力

   先命名真实问题，再去找技术手段。

   • 寻找真实压力：难以跟随的控制流；隐藏的修改、I/O、错误或状态转换；应该一起改的语义重复；只是长得像、但应各自演化的规则；沿同一条真实变化轴反复出现的条件分支；不稳定的外部依赖；同一不变式的归属分散；有真实组合的构造与生命周期规则；缺少稳定的公共缝隙。
   • 没有观察到压力，就不引入新抽象。
   • 全新设计给出满足已知行为和可信近期变化的最小连贯架构。
   • 完善已有设计则找出缺失行为、矛盾、归属不清、不可行假设、附带复杂度和缺乏证据的决定。
4. 04

   发展并比较方案

   只有取舍真的不同，才配成为两个方案。

   • 只在取舍实质不同时才给出多个备选方案。
   • 从归属、耦合、内聚、状态与失败行为、兼容性、可测性、可运维性、迁移成本和预期变化压力来比较。
   • 优先沿用仓库既有的语言、框架和边界，除非有具体问题要求改变。
   • 推荐一个方案，并说明它为什么是"必要的最低复杂度"。
   • 对诱人但投机的扩展点和不必要依赖，明确写出拒绝理由。
5. 05

   应用可维护性标准

   熟悉、显式、有名字、局部、可调试、单一归属——而且无聊。

   • 偏好这样的代码：在仓库里熟悉、对分支和副作用显式、用领域概念命名、无需追踪无关模块即可理解、能在有意义的步骤上调试、一条规则只有一个权威归属。
   • 新奇税：不常见的写法、反射、元编程、密集表达式、隐式运行时行为、新依赖、抽象或设计模式，都必须给出具体收益。确有必要时把它隔离在清晰边界后、命名意图、保持副作用可观察，并解释它为什么存在，而不是语法怎么运作。
   • 按语义复用：只有实现同一条领域规则、所有调用方都应共同改变、拟定的归属者拥有相关数据和不变式、参数化不会让结果更难懂、且没有现成抽象够用时，才共享代码。
   • 规则只是碰巧长得像、且会各自演化时，允许重复。
   • 只有真实压力才用模式：多个真实策略用 Strategy；转换逻辑分散用显式状态机；不稳定的第三方接口用 Adapter；真实的构造组合与不变式用工厂或建造者；有序且独立的处理阶段用管道。模式名字本身不是质量证明。
   • 这套标准用来塑造模块边界和契约，而不是提前规定内部类怎么写。
6. 06

   产出方案

   交付边界、契约、取舍和实施顺序，不交付代码。

   • 只写相关章节：问题、目标、已接受行为、约束和范围外；既有上下文与可复用能力；推荐的边界、职责、契约、数据与状态归属、依赖方向。
   • 失败、安全、兼容、迁移和运维行为重要时也要写。
   • 记录决定、取舍、考虑过的备选，以及被明确拒绝的不必要抽象。
   • 列出开放问题与假设，以及验收证据和实施顺序。
   • 不把假设说成已接受的决定，也不在这次调用里实现这个设计。

不可绕过的规则

一次真实调用

从你发出的 token 到你拿回的证据，这次对话实际长什么样。

1. 智能体

   判定为"全新 / 探索"模式，读取仓库里既有的通知和队列能力。

2. 智能体

   命名真实压力：各渠道只有投递方式不同，这是一条真实变化轴；其余规则应该共同变化。

3. 智能体

   给出两个取舍实质不同的方案，从归属、可测性和迁移成本比较，并推荐更简单的那个。

4. 智能体

   明确拒绝"为将来可能出现的渠道预留插件注册表"——没有观察到压力，就不引入抽象。

5. 智能体

   输出边界、契约、数据归属、开放问题、验收证据和实施顺序，不写一行生产代码。

什么时候用它

• 有目标或问题，但方案还没定下来。
• 已有的设计或提案需要纠错、补全或简化。
• 希望在写代码之前，先把取舍比较清楚、把被拒绝的选项记下来。
• 怀疑某个架构方案比问题本身还复杂。

什么时候改用别的

常见问题