用途:Modular(无上帝文件)帮助开发者在改动代码时保持模块化,让改动落在小而内聚、归属明确的单元中,优先选择多个清晰文件而非一个仓库式大文件。
主要能力与判断标准:新增或扩展代码前,检查文件是否只有单一变更理由;若两个不相关功能都要改同一文件,就应引入边界(子文件夹、service、hook、adapter),而不是继续扩大上帝文件。文件名应反映职责,避免把 utils.ts、helpers.ts 或 stuff.ts 当作万能堆放区,除非范围足够窄(如只做日期格式化的 date-utils.ts)。顶层路由、页面、容器只编排,不应内联占据所有类型、转换和副作用。导入关系应清晰,若模块广泛导入不相关领域,应按领域或按层(展示、逻辑、IO)拆分。
上帝文件的警示信号:同一文件混有 UI、领域规则、持久化和临时 I/O;难以用一句话描述而不带“还有”;所有人因不相关工单改同一文件并频繁冲突;循环或杂乱的 barrel(一个 index.ts 重导出不相关子系统)。文件长度只是表象,200 行内聚模块可以接受,200 行包含五种不相关行为则不行。
拆分方式:针对不同症状选择最小提取,例如大 React/Vue/Svelte 界面拆出子组件、hooks/composables、视图模型模块;类型与运行时混合拆出 types.ts 或就近 *.types.ts;API/客户端与解析拆出 client.ts、mappers.ts,让组件保持简单;跨功能共享常量先放功能本地,只有明确共享范围再提升;测试复杂度就近放在 .test. 或 tests。就近放置优先,只有当第二个真实消费者出现或契约稳定时才提升到 shared/ 或 lib/。
使用方式:当用户问“这段代码该放哪”,按所有者功能 → 层(ui/domain/data)→ 文件名回答;若尚无所有者,为该功能建最小文件夹,而不是默认塞进最近的大文件。重构时先无行为变更地移动代码,再拆分,保持 PR 可审查。不要用 2k 行文件里的 // SECTION 注释解决结构问题,应直接拆分。
限制:资料未提供具体安装、配置、收费、平台或命令信息;扩展启发式与审查提示见 reference.md。