module-decomposition

name	module-decomposition
description	独立的“无损修剪式”模块拆解方法论：用于在规划或实现过程中，对既有模块/超大文件（默认阈值≥1000 LOC）做渐进式无损拆解，把单体逻辑拆成互斥子模块以降低耦合与冲突面；支持两种拆分形态：单一主体用 *.*.ts 平铺、子系统用目录组织；以思想/输出协议为主、脚本为辅，可被上层 agent 嵌入任意工作流（不依赖 plan.md 等固定产物）。

Module Decomposition（无损修剪式模块拆解）

目标：在不改变语义与对外 API 的前提下，把“过大/过杂”的文件或模块拆成互斥子模块；把拆分的边界、命名与依赖拓扑显式化，支撑上层 agent 做规划、排任务与渐进式重构。

本 skill 是“思想指导工具为主、脚本为辅”：

• 思想：拆分决策树、无损修剪不变量、互斥子模块边界设计、依赖拓扑约束。
• 工具：可选的 LOC 扫描脚本 + 可复制的 Markdown 模板/清单。

快速开始

1. 运行扫描脚本列出候选大文件（默认阈值 1000 行）：
   • python .codex/skills/module-decomposition/scripts/scan_large_files.py --min-lines 1000 --top 30 packages/logix-core/src packages/logix-react/src --format md
2. 对每个候选目标，先产出一份可复用的“Decomposition Brief”（只写方案，不急着动代码）：
   • 使用 references/large-file-decomposition-template.md 作为模板（可直接复制到任意文档/Issue/PR 描述/对话）。
3. 若要落地到代码，再执行“无损修剪”流程：一次只落地一个互斥子模块（见下文）。

上层 agent 对接（输入/输出协议）

把本 skill 当作“可插拔的拆解子流程”，上层 agent 只需要提供：

• 输入：
  • 目标文件/目录（或符号列表）
  • 本次目的（行数治理 / 职责治理 / 子系统抽象）
  • 必须保持的不变量（对外 API、性能/诊断预算、单向依赖规则等）
  • 预计会触及的相邻文件/调用方（用于评估改动波及面）
• 输出（标准化，建议用 Markdown）：
  • Decomposition Brief：互斥子模块清单 + 命名/落点 + 依赖拓扑 + 渐进迁移步骤 + 验证策略

该输出不绑定任何固定产物：你可以把它粘贴到任意载体（设计文档、任务系统、handoff、PR 描述、spec-kit plan 等），也可以单独落为 decomposition.md。

决策树（拆分形态）

判断拆分原因与形态（必须二选一，避免混合导致目录漂移）：

• 单一主体，为行数/职责治理拆分：用 *.*.ts 平铺在同目录。
  • 例：ModuleRuntime.ts → ModuleRuntime.hubs.ts / ModuleRuntime.txnContext.ts / ModuleRuntime.runtimeStore.ts
• 一大类子模块/子系统：用目录承载子模块，并在目录内再按子能力细分。
  • 例：runtime/core/process/*（已是目录）继续在其内拆分 ProcessRuntime.*.ts

工作流（规划 → 实施）

Step 0：先定“无损修剪”不变量（必须）

• 对外导出与语义保持不变（除非明确是 breaking change 且有迁移说明）。
• 拆分只改变文件组织与依赖关系，不引入新行为、新缓存、新调度策略。
• import 拓扑保持单向；出现循环依赖视为“边界设计失败”，回到 Step 2 重画边界。

Step 1：盘点与切面（只读）

• 用脚本确认是否满足阈值（≥1000 LOC）或预计本次会超过阈值（“必然会被本需求触及”也算）。
• 识别“可稳定切面”（用于形成互斥子模块；按职责拆，不按作者习惯拆）：
  • 纯类型/协议、纯工具、组装/wiring、执行循环、诊断/事件、缓存/索引、IO/平台适配。
• 识别硬约束：
  • import 单向拓扑、内部/外部边界（例如 internal/** 深层不得反向依赖浅层）。
  • 运行时核心路径的性能/诊断约束（新增开销必须可度量、事件必须 Slim 可序列化）。

Step 2：设计互斥子模块（写计划）

• 产出 Decomposition Brief（必须互斥；不要“都能放这里/先放着”）：
  • 文件名（遵循平铺/目录规则）
  • 单一职责（SRP），输入/输出（导出符号）
  • 允许的依赖方向（谁 import 谁）
  • 原文件保留的内容：通常只保留顶层 make()/对外导出/最薄 glue
• 载体选择：
  • 任意你正在使用的“事实源”（设计文档/任务系统/PR 描述/spec-kit 产物/handoff），只要可追踪、可交接即可。

Step 3：实施拆分（无损修剪）

• 以“移动/提取”为主，不在拆分过程中顺手做语义重写（避免混淆 diff）。
• 优先策略：
  1. 先新建目标文件，移动一组互斥能力（保持导出签名不变）。
  2. 原文件改为 import 并 re-export/组装（必要时）。
  3. 连续小步：每次拆 1 个子模块就做一次类型/测试验证，避免最后一次性爆炸。

Step 4：验证与交接

• 至少完成：类型检查 + 相关测试（按项目约定）。
• 更新事实源：把“已拆/未拆/下一处拆分”同步回你选定的载体（便于交棒）。

反模式（禁止）

• 为了“顺手优化”在拆分过程中引入新的行为/调度/缓存（会破坏无损修剪原则）。
• 引入双真相源（同一份状态/协议/事件定义出现在两个地方）。
• 让拆分后的模块职责重叠，或产生循环依赖（应回到 Step 2 重画边界）。

资源

• 模板：references/large-file-decomposition-template.md
• 检查清单：references/safe-pruning-checklist.md
• 扫描脚本：scripts/scan_large_files.py