这次我们来看一个关于 AI 编程的核心观点为什么你的代码库结构比精心设计的 prompt 更能决定 AI 编程助手的产出质量。这个观点来自 TypeScript 专家 Matt Pocock他提出的“深模块架构”是解决 AI 读不懂你代码、生成不准确代码的关键。很多开发者在使用 Cursor、GitHub Copilot 等工具时常常抱怨 AI 不理解项目上下文生成的代码需要反复修改。Matt Pocock 指出问题的根源往往不在于 prompt 技巧而在于代码库本身的结构。一个遵循“深模块”原则的代码库能让 AI 更准确地理解你的意图生成更符合预期的代码从而显著提升开发效率。本文将深入拆解“深模块架构”的核心思想并结合 TypeScript/JavaScript 项目给出具体的实践方法。无论你是正在探索 AI 编程的开发者还是希望优化现有项目结构以更好地适配 AI 工具这篇文章都将提供一套可落地的解决方案。我们会从概念解析开始逐步深入到目录结构设计、接口抽象、依赖管理以及具体的 Cursor 使用技巧让你能立刻着手改进自己的代码库。1. 核心能力速览深模块架构 vs. 传统提示词工程在深入细节之前我们先通过一个对比表格快速理解“深模块架构”方法与单纯优化 prompt 的本质区别以及它能带来的直接收益。对比维度传统“优化 Prompt”方法“深模块架构”方法核心思路通过更详细、更结构化的自然语言描述来引导 AI。通过优化代码本身的结构、命名和抽象让代码“自解释”降低 AI 的理解门槛。关注点对话技巧、上下文长度、示例格式。模块边界、接口设计、依赖关系、命名一致性。效果持续性临时性、针对特定任务。每次新对话可能需要重新教育 AI。系统性、长期性。一旦代码库结构优化所有 AI 交互都会受益。对开发者的要求学习 prompt 工程成为“AI 沟通专家”。学习软件设计原则成为更好的软件工程师。典型问题“为什么 AI 总是忽略我项目里的utils文件夹”、“如何让 AI 记住我们团队的代码风格”“如何设计模块让 AI 一眼就知道哪里该改、哪里不该动”、“如何减少模块间的隐式耦合”适用场景一次性代码生成、探索性编程、快速原型。长期维护的中大型项目、团队协作、需要 AI 深度理解上下文的复杂重构。简单来说深模块架构不是教你如何“问”AI而是教你如何“写”代码让你的代码库本身成为对 AI 最友好的“提示词”。接下来我们将具体展开如何实现这一点。2. 适用场景与使用边界2.1 谁适合采用深模块架构中大型项目维护者项目代码超过 1 万行模块众多新成员包括 AI理解成本高。TypeScript/JavaScript 开发者Matt Pocock 的观点在该生态中尤其适用因为动态类型语言更需要清晰的结构来弥补运行时的不确定性。希望深度集成 AI 编程工具的团队使用 Cursor、Copilot 等工具作为日常开发流程的一部分并希望减少 AI 的“幻觉”和返工。重视代码可维护性和可读性的开发者即使不考虑 AI深模块架构本身也是优秀的软件设计实践。2.2 它能解决什么问题上下文理解不足AI 在分析大型代码库时容易丢失关键上下文导致生成无关或错误的代码。清晰的模块边界能帮助 AI 聚焦。生成代码与现有模式不符AI 可能引入与项目现有架构、命名约定或工具链不一致的代码。良好的抽象能定义清晰的“模式”。重构和修改困难当要求 AI “修改 X 功能”时如果功能逻辑分散在多个紧密耦合的文件中AI 很难进行安全、准确的修改。深模块通过高内聚来避免这个问题。接口滥用和依赖混乱AI 可能会错误地导入或使用内部模块的私有细节。明确定义的公共接口能有效约束 AI 的行为。2.3 不适合什么场景超小型脚本或一次性代码为几十行代码设计复杂架构是过度设计。极度追求原型开发速度在创意验证阶段可能更需要快速试错而非精心设计结构。但即使如此养成好习惯也有益。已固化且无法修改的遗留系统如果代码库结构无法调整此方法的应用会受到限制但依然可以通过在新增模块中实践来获得局部收益。2.4 安全与合规边界代码所有权确保你拥有或有权修改目标代码库。AI 工具使用遵守你所使用的 AI 编程工具如 Cursor、Copilot的服务条款注意代码隐私和数据安全设置。设计原则通用性本文讨论的“深模块”是软件工程通用概念不依赖任何特定 AI 模型或私有 API可安全应用于任何项目。3. 环境准备与前置条件实践深模块架构不需要特殊的硬件或复杂的运行时环境核心在于开发工具链和思维模式的准备。代码编辑器/IDE推荐使用对 TypeScript/JavaScript 和 AI 编程有良好支持的编辑器。Visual Studio Code配合 GitHub Copilot 扩展是主流选择。Cursor内置 AI 能力是实践和测试“代码库即提示词”理念的理想环境。WebStorm等 JetBrains IDE也集成了 AI 助手功能。版本控制Git。这是管理代码结构变更、回溯和协作的基础。项目语言与生态TypeScript强烈推荐。静态类型系统本身就是一种强大的“文档”和“约束”能极大帮助 AI 理解代码意图。确保tsconfig.json配置合理。JavaScript (ES Modules)如果使用 JavaScript应使用 ES Modules (import/export) 而非 CommonJS以获得更清晰的模块化支持。包管理器npm,yarn, 或pnpm。用于管理项目依赖清晰的package.json有助于 AI 理解项目技术栈。AI 编程工具可选但推荐Cursor安装并配置好建议开启“Composer”模式进行实验。GitHub Copilot在编辑器中安装并登录。使用这些工具的目的是为了实时验证代码结构改进对 AI 理解能力的影响。4. 深模块架构核心思想解析“深模块”概念并非 Matt Pocock 独创它源自经典的软件设计思想。其核心是一个模块应该通过简单、清晰的接口接口小来提供强大、复杂的功能功能深。让我们将其拆解为对 AI 友好的具体特征4.1 接口小浅是什么暴露给外部的 API 数量少、参数简单、意图明确。对 AI 的好处AI 在编写调用代码时选择很少不容易用错。它只需要理解少数几个函数或类的公开方法。例子差一个ImageProcessor类暴露了_loadBuffer,_applyFilter,_saveToDisk,process等十几个公共方法。好ImageProcessor类只暴露一个process(inputPath, outputPath, options)方法。所有复杂性隐藏在内部。4.2 功能深深是什么模块内部封装了大量的实现细节、复杂的算法、状态管理或第三方库的集成。对 AI 的好处当 AI 需要修改或扩展该模块的功能时它知道所有相关的代码都高度内聚在这个模块内部无需在项目里到处寻找关联文件。这减少了上下文搜索的负担和出错概率。4.3 高内聚低耦合高内聚模块内的代码共同完成一个明确的、单一的责任。低耦合模块之间通过明确的接口通信避免隐式依赖如全局变量、隐式上下文传递。对 AI 的好处AI 在进行功能变更时可以清晰地评估影响范围。修改一个高内聚模块大概率不会意外破坏其他模块。4.4 一致的命名与目录结构命名变量、函数、类的名字准确反映其职责和类型。例如fetchUserData比getData更好isValid前缀用于布尔值。目录结构按功能/领域组织文件而不是按技术类型。例如/features/user/下包含UserAPI.ts,UserList.vue,useUserStore.ts而不是/api/,/components/,/stores/下分别存放。对 AI 的好处AI 通过文件名和路径就能推测代码的职责能更准确地进行文件导航和上下文关联。5. 实战将现有代码库改造为“AI 友好”深模块我们以一个常见的、结构混乱的“用户管理”功能为例演示如何一步步将其重构为深模块。5.1 改造前典型的“浅模块”或“碎片化”结构假设项目结构如下问题很多src/ ├── api/ │ └── index.ts // 导出所有 API 请求函数包括 fetchUsers, fetchUserById, updateUser... ├── components/ │ ├── UserList.tsx │ ├── UserForm.tsx │ └── UserAvatar.tsx ├── stores/ // 或 contexts/ │ └── userStore.ts // 一个巨大的 store管理用户列表、当前用户、加载状态等 ├── utils/ │ └── userHelpers.ts // 包含 formatUserName, validateUserEmail 等工具函数 └── types/ └── index.ts // 包含 User, UserFormData 等类型定义问题分析关注点分离但物理分离与“用户”相关的代码散落在 5 个不同的目录中。接口复杂userStore可能暴露了多个state和actionsapi/index.ts导出了一堆函数。高耦合UserList组件需要导入api/、stores/、types/和utils/下的内容。AI 很难理清完整依赖。对 AI 不友好当你让 AI “在用户列表中添加一个禁用按钮”它需要跨越多个目录理解 API、Store、Component 和类型极易遗漏或出错。5.2 改造后按功能划分的深模块结构我们创建src/features/user/目录将所有相关代码内聚于此src/ └── features/ └── user/ # 深模块用户功能 ├── api/ # 模块内部使用的 API 通信层 │ ├── types.ts # 用户相关的请求/响应类型 │ ├── requests.ts # fetchUsers, fetchUserById 等具体请求函数 │ └── index.ts # 只导出模块对外提供的 API 接口可能很少 ├── components/ # 模块内部使用的组件 │ ├── UserList.tsx │ ├── UserForm.tsx │ └── UserAvatar.tsx ├── store/ # 模块内部的状态管理 │ └── index.ts # 创建并导出唯一的 userStore 实例及其类型 ├── utils/ # 模块内部的工具函数 │ └── helpers.ts ├── types.ts # 用户相关的核心领域类型定义如 User └── index.ts # **关键**模块的“浅接口”。只暴露外部需要使用的部分。关键文件src/features/user/index.ts内容// 深模块的“浅接口” export type { User } from ./types; export { useUserStore } from ./store; export { UserList, UserForm } from ./components; // 注意不直接导出 api/ 下的底层请求函数它们被 store 或 components 内部消化了。 // 外部只需要知道 UserList 组件和 useUserStore Hook。5.3 改造效果与 AI 交互对比现在当你在项目根目录的某个页面中让 AI “添加一个用户禁用功能”时会发生什么场景在src/pages/HomePage.tsx中你写下注释或对 AI 说“在这里引入用户列表并添加一个禁用按钮。”AI 的行为改造后它看到你要操作“用户列表”。它扫描导入语句发现项目有一个features/user模块。它查看features/user/index.ts发现对外提供的接口很简单UserList组件和useUserStore。它很容易地添加导入import { UserList } from /features/user;。对于“添加禁用按钮”AI 知道需要修改UserList组件。它导航到features/user/components/UserList.tsx。关键优势所有与“禁用用户”相关的逻辑——UI 按钮、事件处理、状态更新调用 store、乃至最终的网络请求在 store 中调用 api——都高度可能存在于features/user/这个目录树下。AI 的搜索和修改范围被极大地约束和明确了成功率大幅提高。而在改造前AI 可能需要在你给定的有限上下文里盲目地猜测应该修改components/UserList.tsx然后还要去stores/userStore.ts里找disableUseraction再去api/index.ts里找对应的请求函数整个过程极易断链。6. 在 AI 编程工具中验证与运用6.1 在 Cursor 中利用深模块Cursor 的“Composer”和“Chat”模式都能从清晰的模块结构中受益。项目级理解当你打开一个深模块结构清晰的项目Cursor 在初始化项目上下文时能更快地建立模块地图。精准的代码生成在features/user/目录内新建文件或编写代码时Cursor 提供的自动补全和代码建议会更准确因为它参考的上下文高度相关。高效的重构使用 Cursor 的“重构”或“解释代码”功能时对于深模块内的代码它能给出更精确的重构建议因为依赖关系清晰。实践提示在 Chat 中你可以直接引用模块路径。例如“请查看/features/user/store中的状态设计为UserForm组件添加一个自动保存草稿的功能。” AI 能精准定位。6.2 编写对 AI 友好的代码注释与文档深模块架构之外代码内的“微观”清晰度同样重要。JSDoc/TSDoc为公开的接口、函数、复杂类型添加清晰的注释。说明用途、参数、返回值、示例。AI 会阅读这些注释。/** * 根据用户ID和角色权限获取用户可见的个人资料数据。 * param userId - 目标用户的唯一标识符 * param viewerRole - 当前查看者的角色用于权限过滤 * returns 一个Promise解析为过滤后的用户资料对象若未找到或无权访问则返回null * example * ts * const profile await getVisibleUserProfile(123, admin); * */ export async function getVisibleUserProfile(userId: string, viewerRole: Role): PromiseUserProfile | null { // ... 实现 }避免魔术数字与字符串使用常量或枚举定义。AI 更容易理解UserStatus.ACTIVE而不是直接写1。函数单一职责一个函数只做一件事。这本身是好的编程实践也能让 AI 在修改或调用时意图更明确。7. 高级模式领域驱动设计DDD与 AI 编程的结合深模块架构可以自然地延伸到领域驱动设计。DDD 强调以业务领域为核心组织代码这与“按功能划分”的深模块不谋而合且对 AI 更友好。领域Domain对应一个顶级的features/或domains/目录如user,order,payment。聚合根Aggregate Root领域内的核心实体其所在模块就是一个天然的“深模块”。例如features/user/UserAggregate。值对象、领域服务、仓储这些 DDD 概念都可以组织在各自的深模块中通过清晰的接口交互。对 AI 的好处DDD 提供了更严格的架构约束和通用语言Ubiquitous Language。当整个团队包括 AI都使用“用户”、“订单”、“支付”等一致的领域术语时AI 生成的代码在概念一致性上会大大提升。8. 常见问题与排查方法在向深模块架构迁移或与 AI 协作时你可能会遇到以下问题问题现象可能原因排查方式解决方案AI 仍然生成无关代码或无法理解上下文1. 模块接口仍然过于复杂不够“浅”。2. 模块间存在隐藏的循环依赖或全局依赖。3. AI 工具的上下文窗口已满未包含关键文件。1. 检查模块的index.ts看是否导出了太多内部细节。2. 使用tsc --noEmit或madge等工具分析依赖图。3. 在 Cursor Chat 中使用手动引用相关文件。1. 进一步重构收紧公共接口。2. 打破循环依赖明确注入所需依赖。3. 确保在正确的文件/目录下与 AI 对话或提升上下文窗口容量。重构后项目启动报错导入路径错误文件移动后导入路径未更新。检查终端报错信息定位第一个无法解析的模块。使用 IDE 的重构功能如 VS Code 的“重命名文件”自动更新导入或全局搜索替换。TypeScript 路径别名/可以减轻此问题。团队不习惯新的目录结构改变了长期形成的开发习惯和文件查找路径。团队讨论中遇到阻力。1.渐进式迁移不要求一次性全部重构从新功能或问题最多的旧模块开始。2.提供清晰的架构图和新旧路径对照表。3.展示收益用实际案例展示新结构下 AI 生成代码准确率的提升。深模块导致某些“通用”工具函数无处安放过度细分模块导致一些真正通用的、不属于任何特定领域的函数难以归属。发现多个模块都需要导入同一个“通用”函数。1. 区分“领域通用”和“项目通用”。领域通用的可放在领域模块内项目通用的可保留一个shared/或lib/目录但需严格控制其质量和依赖。2. 审视该函数是否真的通用或许它可以被拆分并融入某个领域模块。AI 生成的代码不符合项目的代码风格如命名、缩进AI 未学习到项目的代码风格约定。对比 AI 生成代码与项目现有代码的风格差异。1. 在项目根目录提供强约束的配置文件如.eslintrc.js,.prettierrc。AI 工具会参考这些配置。2. 在关键的深模块中放置一个example.ts或style-guide.md文件展示本模块的代码风格范例。9. 最佳实践与使用建议从小处着手迭代演进不要试图一次性重构整个巨型代码库。选择一个新的功能特性或一个最令你头疼的旧模块开始实践深模块设计。“接口先行”设计在编写模块内部实现之前先思考并定义好它的公共接口index.ts。这迫使你思考模块的边界和职责也让 AI 从一开始就有清晰的“使用说明书”。充分利用 TypeScript严格的类型定义是给 AI 最好的“规格说明书”。尽量使用interface和type来定义契约避免使用any。为 AI 提供“导航标”在复杂的深模块中可以在目录内添加一个README.md简要说明模块的职责、核心接口和内部结构。AI 在阅读文件时也能看到这些信息。统一团队认知在团队内推广深模块思想和 AI 友好的编码规范。统一的模式能让 AI 助手在为不同成员服务时表现更一致。持续观察与反馈注意观察在结构良好的模块和结构混乱的模块中AI 助手的表现差异。将这些案例作为持续改进代码结构的依据。10. 总结Matt Pocock 的观点揭示了一个本质在 AI 编程时代优秀的软件架构不仅服务于人类开发者也服务于我们的 AI 协作者。与其花费大量时间钻研变幻莫测的 prompt 技巧不如投资于构建一个清晰、内聚、接口明确的代码库。“深模块架构”就是这样一套直击要害的方法论。它通过创建功能强大但接口简单的模块显著降低了 AI 理解代码上下文的认知负荷。当你的代码库本身就是一个结构良好的“提示词”时AI 编程工具如 Cursor 或 Copilot 就能从一个容易出错的“实习生”转变为一个理解力强、产出可靠的“高级工程师”。实践起来可以从将代码按功能领域组织、收紧模块的公共 API、编写清晰的类型和注释开始。立即审视你的项目找一个模块尝试重构你很快就能感受到 AI 生成代码的准确性和可维护性的双重提升。这不仅是适应 AI 的趋势更是通往更好软件设计的一条经典路径。