模块化项目管理

要解决的问题

项目膨胀之后，「哪个目录放什么、这个文件归哪个模块」往往只存在于老成员的脑子里。新人接手时，先要在几十层目录里翻找；code review 时，很难一眼看出这次改动波及了哪些模块；重构之前，更是无从判断当前结构的全貌。文档要么缺失，要么更新一次就过期，代码里也没有稳定可引用的模块标识。

核心能力

项目模块管理 通过一次扫描，给项目建立一份持久的模块地图：

• 11 位层级编码：按深度优先遍历分配形如 L PPP OOO FFFF 的编码，目录与同层文件共享编号空间。
• 只追加不回收：新文件获得下一个可用编号，删除的文件保留编码并标记 deleted_at，编号永不复用，外部引用因此不会失效。
• 虚拟分组：根目录下不匹配源码特征的文件（比如几百个 .md 文件）自动归入虚拟的 Documentation 目录。
• 变更追踪：对比前后两次快照，输出新增、删除、修改的文件及体积、行数增量，支持 Text tree、Markdown、JSON 三种格式。
• 框架识别：自动识别 React、Vue、Next.js、Node、Go、Python、PHP、Java 等项目，并遵守 .gitignore。
• 自愈存储：删掉 data/ 目录后，下次运行会自动重建快照。

使用流程很简单：在项目根目录运行一次，拿到模块地图；编码前对照地图确认要动哪些文件；编码后再跑一次，核对变更范围是否与预期一致；用 .modularrc.json 中的 skip_dirs、skip_files 定制跳过规则，并与团队共享以统一模块边界。

适用边界

它适合几千文件以内的常规项目，不是实时监控——按需运行，不会自动感知文件变化。超过 5000 个文件或 15 层以上嵌套时性能会明显下降。模块编码仅作参考，不要接进运行时逻辑。数据按项目路径哈希隔离存放在 data/ 中，需要对该目录的写权限。