Deep modules for agent-native codebases

核心用法

AI Codebase Deep Modules 是一套系统性的代码库重构方法论，旨在将混乱的"浅层交叉导入文件网"转化为 AI 和人类都易于导航、修改和测试的结构化代码库。

核心操作流程（6 步）：

1. 建立快速反馈循环 — 优先确定最快的验证命令（typecheck、单测、lint），确保重构前有可靠的"是否有效"信号
2. 重建心智模型地图 — 识别 3-10 个自然的产品领域/功能域，标注当前耦合痛点
3. 设计深度模块 — 每个模块遵循"小接口、大实现"原则，明确定义公共 API、内部实现和依赖方向
4. 对齐文件系统 — 按领域重组目录结构，强制外部代码仅从模块公共入口导入
5. 边界测试灰盒化 — 用契约测试锁定公共接口行为，将内部实现视为可替换
6. 渐进式重构 — 采用绞杀者模式，先建接口、再加测试、逐步迁移、最后删除旧代码

边界 enforcement 工具链：

• 约定 + Code Review（基线）
• ESLint no-restricted-imports 等 lint 规则
• 架构测试（如 dependency-cruiser）
• 语言级边界（Go internal/、Rust pub(crate)、Java 模块系统）

显著优点

• 显著降低 AI 的认知负荷：深度模块将"需要同时理解的事项"从几十上百个文件压缩为几个稳定接口
• 防御性架构：明确的导入边界防止代码库重新退化为"意大利面条"
• 渐进式落地友好：支持绞杀者模式，无需大爆炸式重写，降低风险
• 语言无关方法论：核心原则适用于 TS/JS、Python、Go、Java/Kotlin、Rust 等主流语言
• 测试策略清晰：优先契约测试而非实现测试，减少脆弱测试带来的维护负担

潜在缺点与局限性

• 初始认知成本：团队需理解"深度模块"与"浅层工具类"的区别，可能产生概念混淆
• 遗留代码阻力：高度耦合的存量代码可能需要多轮迭代才能完全解耦
• 工具链配置复杂度：ESLint 边界规则、架构测试等需要持续维护规则配置
• 过度工程风险：小型项目或原型阶段过早引入可能增加不必要的结构负担
• 跨域事务处理：严格模块边界与需要跨域协调的分布式事务存在张力

适合人群

• 中大型代码库维护者：单体应用增长至 50+ 模块、导入关系混乱的团队
• AI 辅助开发团队：希望让 Copilot/Cursor 等工具生成更可靠代码的开发者
• 技术债务治理：面临"改一处坏三处"困境，需要结构性解决方案的架构师
• 微服务拆分准备期：计划从单体向服务化演进，需要先理清领域边界的团队

常规风险

• 循环依赖隐蔽性：表面按功能分文件夹，实际通过 shared/ 工具包形成新的隐性耦合
• 接口稳定性误判：过早固化尚不稳定的业务概念，导致接口频繁变动
• 测试覆盖率幻觉：契约测试通过≠集成场景无问题，需保留关键端到端测试
• 团队协作摩擦：新结构可能与部分成员的既有工作习惯冲突，需配套文档和培训
• AI 幻觉叠加：若边界规则未通过 lint 强制约束，AI 可能在重构中无意中破坏架构