workflow_modular_design_entropy_control

道-方法 · 道层 skill 全文

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

name: workflow_modular_design_entropy_control
description: 代码级模块化设计与熵从源头控制的道层判断（含补丁 vs 重构的"度"）。用于写新功能、重构、审查代码、判断"该补丁还是该重构还是别动"、保证一个功能只有唯一实现、把复杂度挡在写代码的当下；也用于设计阶段/给需求时前置考虑模块边界与适配归属。区别于 workflow_complexity_drift_detection（运行期任务漂移）——本 skill 是写/改代码时的复杂度源头控制。
type: Workflow（道层 / 设计与维护判断）
status: draft (Beta) — 晋级前需在 ≥1 次真实写码/重构/审查任务里按"度"门做过判断并留证据，且配套检测器 modular_drift_gate 落地、证据到 bounded 以上
created: 2026-06-19
version: 0.1.0 (draft)

代码级模块化设计与熵从源头控制（含"度"）

一句话

复杂度不是写完代码后冒出来的，是一次次"就加这一处特判/再留一个 fallback"在写代码的当下累积进来的。这个 skill 给的不是编码规范清单（那是术，已在别处），是写/改代码时的一个判断系统：怎么让一个功能只有唯一实现、怎么从源头把熵挡住、以及面对一段出问题的代码时怎么判"补丁 / 局部重构 / 大刀阔斧重构 / 暂不动"。

何时用（两期都触发）

• 设计期 / 给需求 / 定具体设计：要前置考虑模块边界怎么切、一个能力归哪个唯一实现、适配逻辑放哪、避免未来臃肿。
• 维护期 / 写新功能 / 重构 / 审查：面对"加个判断就能解决"的诱惑，先过下面的「度」门，判这次该补丁还是该改架构。

非 trivial 的写码/重构/设计任务先按 _DAO_ROUTING 路由到这里再动手；一行琐碎改动不必。

不做什么（边界，本 skill 不重复造）

代码级判断之外的术层已有唯一真源，本 skill 只指针引用，绝不复制（否则自己就破坏了 SSOT）：

• 怎么切深模块 / 怎么写干净代码（deep module、eliminate-special-cases、modify-as-if-designed-from-scratch、design-it-twice、red-flag 词典）→ APOSD 蒸馏 skill：rules/skills/drafts/philosophy_of_software_design/opus_v6/
• 语言级清单（immutability、函数 < 50 行、文件 < 800 行、many-small-files）→ 全局 ~/.claude/rules/common/coding-style.md + python/coding-style.md
• 文件放哪 / 文件级唯一真源（单一文件原则、按交互目的放）→ WORKSPACE.md §文件存放架构 + workflow_file_storage_and_requirement_protocol + fa-3（adhoc_jobs/file_architecture_unification_20260613/）
• 运行期任务漂移检测 → workflow_complexity_drift_detection
• 设计决策级「一个设计服务多需求 / 反过度工程 / 做减法 / 要不要加一个 hook·gate·机制 / 新机制验收 / overdesign 审计」（产设计那一期的优雅性与减法判断，本 skill 只管实现期的代码熵）→ workflow_design_elegance
• 改一个已注册工具/skill 的演进流程 → workflow_tool_skill_evolution

本 skill 也不替你执行删除/重构——它产判断和理由，动手由你按判断做。

一、唯一真源与模块化（设计期那半）

模块化的目的不是"文件多"，是找一个功能的实现时它唯一。判断一个边界切得对不对，用三个问题（来自 APOSD combine-or-separate-decision-rule，按名引用）：信息是否隐藏在知识边界内、依赖是否被这个边界挡住、接口是否比实现浅。

落到"唯一真源"上，三条硬判断：

1. 一个能力一个权威实现（DRY / PP，D3）。要写的逻辑别处已有 → 复用或下沉成共享资源，不复制粘贴改几行。用户原话：「更好的一种实现方式应该是添加一些可复用的资源，不要去做那种非常特异化的补充……从可复用性和实现的有效性上来考虑整体的实现方案」。
2. 按知识边界切，不按执行顺序切（APOSD AX_19）。# Step 1 / # Step 2 式把一长串步骤塞进一个函数再用注释假分离，不是模块化（见陷阱 AP-1）。
3. 复杂度向下沉，不向上漏（APOSD AX_51 pull-complexity-downward / D5）。模块要"接口窄、实现厚"：把不可避免的复杂度在模块内部吸收，给调用方一个简单接口。浅模块（接口和实现一样复杂）等于没封装。

熵的层级（用户原话，常驻 USER.md）：「好的设计就是在合适的层级约束熵。子节点的零熵（确定性需求）限制整体复杂性，每个模块只针对一个具体说法来降低困惑度」。设计期就是在决定"哪个说法归哪个模块"——切对了，每个模块只回答一个问题，整体困惑度才被钳住。

二、补丁 vs 重构的「度」门（维护期那半，本 skill 最承重）

先破除朴素二分：不是"补丁=坏、重构=好"。寄望"一次性大重构"逃出复杂度，大重构本身缺设计纪律时会复现同样的螺旋（APOSD AX_25 实证）。所以"度"是在四个动作里按问题性质选，不是一律重构。

动手加代码修一个问题前，按顺序问（这是判定门，顺序影响结论；一个没上下文的 agent 据此能对一个具体场景判出动作 + 理由）：

1. 这是 throwaway / prototype / 即将被替换的 legacy 吗？ 是 → 补丁随意，跳过后面（债会随它退场消失）。

1. 这点新复杂度是 essential 还是 accidental？（Out of the Tar Pit / D7，最干净的判据）。essential = 问题/外部现实本身就有这个情况；accidental = 为补我自己早先的实现选择而引入的。accidental 复杂度不是"补还是重构"的问题，是"消除"的问题——它本不该存在。

1. 修复落在模块边界，还是模块核心逻辑里？（用户原话："适配在模块间、模块内出问题直接重构架构"）按 essential/accidental × 边界/核心 四象限定动作，四格都给：
• 边界 + essential → 适配器 / anti-corruption layer 是对的。处理"另一个模块或外部 API 确实不同的契约"的转换，放在边界、保持薄（D5 / Ports & Adapters）。这是合法的"兼容在模块间"。
• 核心 + essential（最常见） → 情况是真的，但它落在函数核心逻辑里：别在函数头加 if 把它当特例，重设计这个函数让该情况变成正常的输入 / 参数值（APOSD eliminate-special-cases）。这是用户原话"函数出问题就改函数，不在函数里堆判断逻辑"的精确落点。（例：parse_card 偶遇新格式崩 → 不加 if format=='new'，而是让解析器把新格式当一种正常输入变体收下。）
• 核心 + accidental → 抽象本身错了，这点复杂度本不该存在：改函数消除它，不是加分支绕过。
• 边界 + accidental → 这条边界适配本不该存在（常是为补内部错误抽象、在边界打的补偿补丁）：删掉它、回去修内部，别让边界堆补偿逻辑。

1. 若该重构，重构的"度"（防过度工程）：目标不是把一切重写完美，是在你触碰的尺度上"让最终结构逼近——如果一开始就这样设计会怎么写"（APOSD modify-as-if-designed-from-scratch / D2），让系统至少不更差。爆炸半径分两层（JESA）：
• object-level（函数/类内部结构）：随时做，这是日常纪律。
• architecture-level（跨模块的结构/流向）：只在问题确实是架构性的、且处在可承受风险的窗口时才"大刀阔斧"。局部问题局部修，别升级成 heroic 全系统重写（那会复现螺旋）。

1. 若 2–4 判定该重构、但确有 deadline 压力：允许一次性 tactical 补丁，但必须显性记债——在 commit / 代码注释写明"绕过了什么、欠了什么、什么时机该还"。一个可见可追踪的补丁 ≠ 螺旋；隐形累积才是螺旋（APOSD AX_24/25 实践建议）。

三、熵从源头控制（贯穿一、二的原理）

• 复杂度是增量累积的，没有无害的小让步，要零容忍态度（APOSD AX_04 / D1）。
• "源头" = 写 / 改代码的当下。熵从这里进，就在这里挡。修复要落在产生问题的错误抽象处，不在症状显现的下游（用户原话"问题出现处直接调架构"）。
• 控熵成本梯度：设计期最便宜 → 下次触碰这段代码时次之（顺手 modify-as-if-from-scratch）→ "以后再说"最贵（会变成 never，进入螺旋）。所以最好的控熵时机不是事后审查，是每次写下/改动代码的那一刻。

已知陷阱（真实案例，非编造；来自 tarot_agent 反例 + 本仓自审）

外部反例 tarot_agent（主 agent 亲验 file:line）：

• AP-1 God 函数假分离：backend/app/services/tarot/reading_pipeline.py:61-624，create_reading_stream 单函数 564 行，8 个业务步骤用 # ===== Step N ===== 注释假装分离。无法单步测试、无法局部重构。违反「按知识边界切」。正确做法：每步抽成深模块，函数变成对它们的编排。
• AP-2 复制粘贴 fallback：backend/app/services/chinese/bazi/retrieval/retriever.py（1208 行），retrieve_balance_yongshen:358 与 retrieve_qishi_yongshen:502 签名结构近乎相同；_get_ditiansui/qiongtong/ziping_rule_fallback（779/857/889）三个同模式。新增一个数据源就 copy 整套。违反唯一真源。正确做法：参数化成一个实现，差异（book 名）做入参。
• AP-3 吞错补丁、根因永不修：reading_pipeline.py:562-574（在 AP-1 巨函数内），DB update 失败后在 except 里循环逐字段弹 payload 重试，内层再 except Exception: continue 吞掉所有错。根因（schema 缺字段）永远不暴露、永远不修。这是 AX_25 螺旋的活标本：补症状不补源头。
• AP-meta 并行版本不删：备份/归档代码 ~76668 行 ≈ 活跃代码的 2 倍，多套 _organized_project/ 并存。违反唯一真源——旧版本该物理删除/归档，不是和真源并排放着。

本仓自审 implementation_atlas_v2（主 agent live 验证；说明再讲究的系统也会积累冗余，所以要有源头纪律）——四个可命名的冗余模式：

• build-but-never-wire（接线漏最后一步）：建了但没接上消费端就当完成。实例：todo_merge_driver 在 .gitattributes:5 声明了 merge=todo-union，但 git config merge.todo-union.driver 为空（live 验 exit 1），driver 永不触发，脚本零功能还误导。
• superseded-but-alive（重构后旧版只标 deprecated 不删）：V1→V2 后 V1 还在，平行两套真源。
• stale-derived-as-parallel-truth（派生文档脱离真源变陈旧）：tools/todo/IMPLEMENTATION_STATUS.md:13 记 todo.py 646 行，实际 2171 行（3.4×），成了误导人的平行陈旧真源。
• duplicate-registration（同一注册多次）：review_domains_cron.sh 在 crontab 行 85/86/87 字节相同注册三遍，并发跑 3 个相同实例。

四个模式的共同根因 = 缺一个"完成 = 接线 + 被消费 + 删旧"的验收门，"建了/写了"的完成感掩盖了"没接线/没删旧"的真实未完成。这正是源头纪律要顶住的地方。

验收标准（一次写码/重构判断是否过关）

• 结果导向：面对一个"加判断就能修"的具体场景，能依"度"门判出动作（补丁/局部重构/架构重构/不动）并说出理由（命中门的哪几步）。判不出 = 没真正用 skill。
• 唯一真源核验：本次改动没有新增同功能的并行实现（无 _v2/_new/复制粘贴函数）；新逻辑别处已有时是复用而非重写。
• 边界归属核验：新增的适配/兼容逻辑落在模块边界（essential），核心逻辑里没有为"本不该特殊"的情况堆 accidental 分支。
• 记债核验：若本次确做了 tactical 补丁，commit/注释里有"绕过什么/欠什么/何时还"。
• 配套检测器（落地后）：modular_drift_gate——确定性壳扫 diff（新增并行实现 / 函数核心加 N+ 分支 / 复制粘贴函数体）+ 第二 agent regulator（forbidden_read 含作者"修好了"叙事）判这次是 essential 边界适配（PASS）还是 accidental 核心补丁本该重构（FLAG，给可定位反例）。遵循 workflow_complexity_drift_detection V1–V6。当前未落地，列为残差。

可用资源

• 术层（按名引用，不复制；路径 rules/skills/drafts/philosophy_of_software_design/opus_v6/）：APOSD skills（eliminate-special-cases / modify-as-if-designed-from-scratch / design-it-twice / combine-or-separate-decision-rule / shallow-module-trap / red-flag-glossary）+ axioms（AX_51=复杂度向下沉 pull-complexity-downward、AX_09/AX_10=深模块 module-depth、AX_04/AX_24/AX_25=熵增量/战略/战术螺旋）；Tar Pit 蒸馏（essential/accidental、MS_03_complexity-intervention）；coding-style.md；fa-3 文件架构。
• 原理锚溯源：adhoc_jobs/coding_modularity_ssot_skill_20260619/research/positive_benchmarks.md（七条哲学 → 权威原则 D1-D7）、feedback_synthesis.md（用户原话）、tarot_antipatterns.md + buildout_redundancy.md（陷阱实例）。

诚实 claim ceiling / 缺口

• 证据等级 bounded：原理锚扎实（APOSD/Tar Pit/PP/Simon/JESA 已蒸馏 + 主 agent 亲读核验）、陷阱来自真实 verified 案例（tarot 2 条 + 本仓 3 条 live 验），但本 skill 作为判断系统未经真实写码/重构任务大规模检验。晋级 production 需 ≥1 次真实任务按"度"门判断并留证据。
• 配套检测器 modular_drift_gate 只设计、未实现（需 Codex 实现 + held-out 验证），是 landing-grade follow-on，不在本轮假装 landed。
• ⑥适配归属、⑦"度"在用户原话里佐证薄，本 skill 的对应判据是从 APOSD/Tar Pit 推演（方向经 R2/R5 交叉确认），非用户逐字主张。