workflow_design_elegance

道-方法 · 道层 skill 全文

本页是 <code>rules/skills/drafts/workflow_design_elegance.md</code> 的逐字投影（仅隐私清洗，零改写）。

name: workflow_design_elegance
status: draft (Beta) — 2026-07-07 从 job 内 skill_draft 晋级到 rules/skills/drafts/ 并注册路由（INDEX + _DAO_ROUTING + dao_shu_matrix），落地横切需求 XC-04/UP-97/XC-07/XC-08。真源设计 `adhoc_jobs/context_infra_base_tooling_buildout_20260615/ddp_creation_skill_and_audit_20260620/design_elegance/`（放置决策 Family A + 方法论综合）。晋级到 production 顶层（rules/skills/）仍需一次真实设计 worker 加载 dogfood + `workflow_version_evolution`，本轮只做 draft 注册不做顶层 evolution。
tier: 道（方法 / 设计决策级，设计派发 worker 加载的协议）
description: 设计优雅性 + 反过度工程化方法论（道）。两件事：① 产出设计时优先选「用一个设计元素满足多个相容需求」的方案降复杂度；② 反过度工程化操作判据——做减法信号（禁堆叠 hook/审查环节/加新不删旧/引入"可能有用"复杂度）、新机制验收四问、overdesign 审计锚点。触发：设计 worker 产出一个 domain 的设计、要在多个需求间做设计取舍、要加一个 hook/gate/审查环节/新机制、判断某设计或工具是不是过度工程化、要做减法。给判断，不替代填设计文档的结构协议（workflow_design_doc_protocol），也不替代写代码时的代码级模块化（workflow_modular_design_entropy_control）。

设计优雅性 + 反过度工程化：一个设计满足多需求、降系统复杂度

诚实定位（先说，不许跳过）

这套方法论是机制论证强 + 五个权威跨书独立收敛的工程启发式，不是统计数据证明的定律。诚实事实：APOSD（Ousterhout）/ Out of the Tar Pit / Modern SE（Farley）/ Pattern Language（Alexander）/ Mythical Man-Month（Brooks）都没有「设计简单度 ↔ 缺陷率 / 维护成本」的受控相关研究；Ousterhout 本人三次声明其「10-20% 投入 / 回报周期」数字「没有数据支撑、只是我的看法」。加载本协议当强启发式用，做设计时绝不把这些原则当数据引、绝不把论断装成数据（这正是本系统反 bad-behavior 的核心纪律之一）。它的力量来自机制可论证 + 五个互相独立的权威各自推到同一结论。

一句话

产出一个设计时，先问「能不能用一个设计元素覆盖多个相容需求」，而不是给每个需求各加一段特化逻辑。一个设计服务多需求之所以降复杂度，是因为它消除了本会互相交互的多个特化部件，把复杂度增长从超线性压回线性。

何时用 / 不用

用：设计派发 worker 产出一个 domain 的设计；任何要在多个需求 / 多个实现路径间做设计取舍的场合；要加一个 hook / gate / 审查环节 / 新机制、或判断某设计·工具是不是过度工程化、或被要求"做减法"时（反过度工程化操作判据一节）。

不用：填设计文档骨架（那是 workflow_design_doc_protocol，怎么填字段）；写 / 重构具体代码（那是 workflow_modular_design_entropy_control，代码级补丁vs重构「度」门）；trivial 单需求设计。

核心原则 + 机制（为什么有效，按机制加载不当数据）

优先选「一个设计元素满足多个相容需求」的方案。两条机制解释为什么这降复杂度：

• M1 复杂度由交互主导，不由部件数量主导（Out of the Tar Pit）：复杂度的主导项是部件间交互（特化部件之间超线性增长），不是部件数量（互不交互的统一部件只线性增长）。一个设计统一 N 个会互相交互的特化部件 → 把增长曲线从超线性压回线性。
• M2 成本不对称（APOSD AX_51 pull-complexity-downward）：接口复杂度被 N 个调用方 × K 个参数放大，吸收进模块内部的复杂度只付一次。一个深 / 通用设计把复杂度从被放大的接口侧，挪到只付一次的实现侧。

概念框架：一个设计服务多需求，消除的是 accidental complexity（N 个需求各自特化时那 N-1 段重复胶水 / 各自分支），不是 essential（问题本身固有的）。

怎么做（有序操作判据）

1. decide-what-matters：先识别杠杆需求——哪几条需求真正驱动这个设计。不把所有需求等量齐观，先找承重的。
2. 找压缩点：能否让一个设计元素同时覆盖多个相容需求？过 APOSD 通用化 3 问：① 这是覆盖当前所有需求的最简接口吗？② 它会用在 ≥3 个情况吗？③ 通用化引入的 bloat < 30% 吗？三问都过才合并成一个设计。
3. removal-test（Tar Pit，最可操作）：对设计里每个部件问「删了它，用户层面的含义还对吗？」对 = accidental（可合并 / 消除 / 降级为 hint）；不对 = essential。多个特化分支都通过 = 它们本是 accidental，合并即降复杂度。
4. design-it-twice（APOSD）：对关键设计点生成 ≥2 个本质不同的方案，选「更少元素覆盖更多需求」的那个。generality 是显式评估轴，不是事后辩护。
5. pull-complexity-downward（APOSD）：把不可避免的复杂度吸收进模块内部，给调用方窄接口。浅模块（接口和实现一样复杂）= 没封装，不算优雅。

主干一句话（APOSD 蒸馏的 meta-skill seed）：decide-what-matters → 一个深 / 通用抽象 → pull-complexity-downward。

「度」边界（反过度设计，必带）

「一个设计满足多需求」不等于「一个万能 god 设计」。压过头只是把复杂度搬家。边界判据：

• 只压相容 force + 真驱动需求（JESA「just enough」H/H）：Alexander 的压缩是叠相容需求（「重叠的模式让建筑同时更便宜、更小、更有意义」），不是硬塞冲突需求。
• 「and」测试（Farley，反向护栏）：一个设计元素的描述要靠「and」才说得清 = 它在做不相关的多件事，别强行合并。判别线：压缩相关的（cohesion，把相关的拢一起），分离不相关的（and-test）。「一个设计满足多需求」指前者。
• 过度通用化的反例（Farley CM.24）：金融系统过度抽象成递归 name-value schema，导致「成百上千次 DB 交互加载常规数据」——通用过头复杂度没消失，搬到了运行期。第二系统效应 / featuritis（Brooks）是同一病。解药 = YAGNI、频率估计、risk-driven 最小够用。

反过度工程化操作判据（做减法 · 新机制验收 · 审计锚点）

上一节的「度」是设计压缩方向的护栏；本节是系统层面「要不要加这个机制」的减法纪律，落地横切需求 XC-07 / UP-97 / XC-04 / XC-08（provenance 见文末）。加载点同「何时用」：要加 hook/gate/审查环节/新机制、判断某设计或工具是否过度工程、或被要求做减法时，先过这一节。

做减法信号（XC-07）——命中任一条，默认不加，除非能反驳

任务核心默认放在「做减法」上：现在的东西堆砌得太多，有些听起来有用但实际重复且没必要。以下是过度工程化的可观测信号，命中即停下来论证：

• 堆叠 hook：又加一个 hook。先问能不能复用已有触发面 / 已有 hook 加一个分支，而不是新起一个。
• 堆叠审查环节：又加一道 gate / review。先问已有 gate 能不能加一条 predicate，而不是新起一个审查环节。
• 加新机制而不删旧机制：引入新机制时，旧机制若被取代必须同批标弃用 / 删除（守单一真源，见 workflow_modular_design_entropy_control §唯一真源）。只加不删 = 净复杂度增加。
• 引入「可能有用」的复杂度：以「以后可能用得上」为由加的字段 / 参数 / 抽象层。没有当前真驱动需求的通用化就是 YAGNI 违例（对应「度」边界的过度通用化）。

工具：清晰语义说明足矣（UP-97）

构建一个工具（尤其像 git 工具这类）时，不需要为「让大模型会用」而堆额外机制。大模型只要有清晰的工具说明 + 清晰的记录 + 分离的管理，就足以自己决定怎么用工具。为「教模型用工具」而加的包装层 / 状态机 / 引导脚手架，多数是这个工具上的过度工程化。判据：如果一段机制的唯一目的是补工具说明的不清晰，先改说明，别加机制。（呼应 UP-90「工具触发全语义化」——语义描述到位，模型即可自主完成操作。）

新机制验收四问（XC-04）——任何新增设计机制必须逐条答，答不全默认 FLAG

记录详尽不是过度工程化；真正的过度工程化信号是：重复收集、职责不清、机制互相补丁化、无法复用、只能解决单一局部问题。因此任何新增的设计机制在收口时必须显式说明：

1. 它同时满足哪些需求（列 req_id；只满足单一局部需求且不可复用 = 过度工程化信号）。
2. 由哪些模块承担（职责清晰，不与既有机制互相打补丁）。
3. 是否可复用（对所有同类通道成立，还是一次性特异化补丁——特异化补丁禁入，见 UP-92）。
4. 在单 Unit 和长链路 Loop 中是否都有效（只在玩具规模成立、长链路失效的机制不算过关）。

四问是收口自检清单，也是审查者判一个机制是否过度工程化的锚。

overdesign 审计锚点 = 实际使用频率（XC-08）

判一个机制 / 工具 / 字段是不是过度工程化，评判锚点是它在最终用户工作流中的实际使用频率，而非理论设计完整性。「理论上更完整 / 更通用 / 覆盖更多边角情况」不是保留理由；「在真实工作流里没人 / 没 agent 触发它」是删除或不加的理由。可机械取证的使用频率信号：tools/tool_receipts/（工具调用台账 + check_discipline 调用率）、记分牌 gap / 使用列、invocation:manual 且零真实触发面 = 默认未落地。审计一个域是否过度工程，先拉这些使用信号，再对理论完整性做减法。

与既有 skill 的关系（compose 不重复）

• 上游母体（指针引用，不复制，守 SSOT）：APOSD 蒸馏 rules/skills/drafts/philosophy_of_software_design/opus_v6/（deep-module / general-purpose / eliminate-special-cases / design-it-twice / pull-complexity-downward）+ Out of the Tar Pit 蒸馏（essential/accidental / removal-test，contexts/library/out_of_the_tar_pit/）。
• 下游 compose：workflow_modular_design_entropy_control（代码级，写 / 改代码时的补丁vs重构「度」门 + 唯一真源）。本协议管「产出一个优雅设计 + 系统层要不要加机制」，它管「实现这个设计时不积代码熵」，两期接力，不重叠。它的「不做什么」边界显式把设计决策级反过度工程指回本协议。
• 收口消费：新机制验收四问（XC-04）与做减法信号（XC-07）可被设计收口的 Solid Decision 评估轴 / landing 收口检查引用；overdesign 审计（XC-08）锚在 tool_receipts / 记分牌使用信号。

验收（一个设计是否过了优雅性 + 减法判断）

• 杠杆需求被显式识别（不是所有需求平摊）。
• 关键设计点有 design-it-twice 的两个方案对比，选了更少元素覆盖更多需求的。
• 合并的需求过了 removal-test + 通用化 3 问；没有靠「and」硬并不相关需求。
• 没有为通用而通用把复杂度搬到运行期 / 别处（过「度」边界）。
• 新增机制答齐了 XC-04 四问；没有命中做减法信号（或命中但有据反驳）。
• 引用原则时标了「机制 / 工程论断」而非「数据」，没有把论断装成统计。

诚实 claim ceiling

• 证据 observational：方法论本身扎在 5 个权威的机制论证 + 跨书独立收敛（强），但无统计数据、未经真实 DDP 设计 worker 加载验证。
• 母体真源是蒸馏库（APOSD/Tar Pit），本协议是它的设计决策级应用视图（指针引用）。晋级到 production 顶层 skills 需入一次真实加载 dogfood + workflow_version_evolution；本轮只做 draft 注册（路由可见 + dao_shu_matrix 入表），不做顶层 evolution。
• 「度」边界与反过度工程化判据目前靠判据定性，做减法信号 / XC-04 四问尚无确定层检测器（与 modular_design_entropy_control 的 modular_drift_gate 一样列为可落地的 follow-on）。

Provenance（本 skill 落地的横切需求锚，逐条可回连需求真源 adhoc_jobs/context_infra_base_tooling_buildout_20260615/requirements/design/cross_cutting.md）：

• XC-04 §「新机制验收四问」— REQUIREMENTS.md:845 §9.5 过度工程化判断标准（源 SP-XC-3，baseline UP-92 + UP-97）。
• UP-97 §「工具：清晰语义说明足矣」— git-prompts-p001-p100.md P037/P038 session a48ddec7。
• XC-07 §「做减法信号」— REQUIREMENTS.md:801 §9.1 做减法（源 SP-XC-3，baseline UP-97 dedup）。
• XC-08 §「overdesign 审计锚点 = 实际使用频率」— REQUIREMENTS_ORIGINAL_TEXT.md:322 REF-016（父 RD-07）。