你是不是也遇到過這種情況用 AI 編程助手比如 Cursor、GitHub Copilot時(shí)精心寫了半天 prompt結(jié)果生成的代碼要么跑不通要么和你的項(xiàng)目上下文完全不搭邊。你開始懷疑是不是自己的 prompt 技巧太差或者 AI 模型還不夠聰明但 Matt Pocock一位知名的 TypeScript 專家和開發(fā)者布道師提出了一個(gè)顛覆性的觀點(diǎn)真正決定 AI 編程效果的往往不是你的 prompt而是你的代碼庫本身的結(jié)構(gòu)。換句話說如果你的代碼寫得一團(tuán)糟AI 再聰明也讀不懂。他引入了一個(gè)叫做“深模塊”Deep Module的架構(gòu)設(shè)計(jì)理念認(rèn)為這是“治療”AI 讀不懂你代碼的良方。這篇文章要解決的正是這個(gè)被很多開發(fā)者忽略的核心問題。我們花了太多時(shí)間研究“如何向 AI 提問”卻很少思考“如何讓 AI 更好地理解我們已有的代碼”。本文將深入拆解 Matt Pocock 的觀點(diǎn)并結(jié)合大量實(shí)際開發(fā)場(chǎng)景為你講清楚為什么“深模塊”架構(gòu)比“神 prompt”更重要背后的邏輯是什么“深模塊”具體是什么它與“淺模塊”有何本質(zhì)區(qū)別如何在實(shí)際項(xiàng)目中無論是前端 React/TypeScript還是后端 Node.js/Java應(yīng)用“深模塊”思想來重構(gòu)代碼有哪些立即可用的代碼示例和重構(gòu)技巧能立刻提升 AI 在你項(xiàng)目中的表現(xiàn)如果你已經(jīng)受夠了 AI 生成無關(guān)代碼、無法理解業(yè)務(wù)邏輯的窘境那么改變代碼結(jié)構(gòu)可能是你接下來最值得投入的一項(xiàng)“基礎(chǔ)設(shè)施”投資。本文不僅有理論更有能直接復(fù)制粘貼到項(xiàng)目中的實(shí)踐方案。1. 問題的本質(zhì)AI 如何“閱讀”你的代碼庫在討論解決方案前我們必須先理解問題。當(dāng)你向 Cursor 的 Chat 或 Copilot 提出一個(gè)需求時(shí)AI 并不是像人類一樣通讀整個(gè)項(xiàng)目然后深思熟慮。它的工作流程更接近于一種“受限的上下文檢索與模式匹配”。1.1 AI 編程助手的上下文處理機(jī)制以目前主流的 AI 編程工具為例有限的上下文窗口無論是 GPT-4 還是 Claude都有 token 限制如 128K。工具會(huì)智能地選取與你當(dāng)前編輯文件最相關(guān)的代碼片段、打開的文件、最近的修改等填充到這個(gè)窗口里作為 AI 的“短期記憶”。基于嵌入的檢索更高級(jí)的工具如 Cursor 的“引用代碼庫”功能會(huì)為你的代碼庫建立向量索引。當(dāng)你提問時(shí)它會(huì)檢索語義上最相關(guān)的代碼塊并將其作為上下文提供給 AI。模式匹配與補(bǔ)全在行內(nèi)補(bǔ)全場(chǎng)景AI 主要關(guān)注當(dāng)前文件的前后文和語言慣例進(jìn)行“下一個(gè) token 預(yù)測(cè)”。關(guān)鍵洞察AI 對(duì)代碼的理解深度嚴(yán)重依賴于它所能“看到”的上下文的質(zhì)量和清晰度。如果你的代碼結(jié)構(gòu)混亂、職責(zé)不清、接口復(fù)雜那么即使被檢索到AI 也很難提取出準(zhǔn)確的意圖和模式。1.2 糟糕的代碼結(jié)構(gòu)如何“毒害”AI假設(shè)你有一個(gè)用戶管理模塊代碼分散在多個(gè)文件且互相緊耦合// 文件src/utils/helpers.ts 一個(gè)什么都放的“工具雜貨鋪” export function validateEmail(email: string): boolean { /* ... */ } export function formatUserName(user: any): string { /* ... */ } export function sendEmail(to: string, subject: string, content: string) { /* ... */ } export function calculateUserScore(orders: any[]): number { /* ... */ } export const APP_CONFIG { /* ... */ }; // 文件src/components/UserProfile.tsx import { formatUserName, calculateUserScore } from ../utils/helpers; // 同時(shí)這個(gè)組件還直接調(diào)用了 API 層和狀態(tài)管理當(dāng)你在這個(gè)UserProfile組件里問 AI“幫我在用戶頭像旁邊添加一個(gè)根據(jù)最近活躍度顯示的徽章”。AI 可能會(huì)看到calculateUserScore但不知道orders參數(shù)具體是什么結(jié)構(gòu)從哪里來。看不到“活躍度”的業(yè)務(wù)定義在哪里。可能會(huì)錯(cuò)誤地復(fù)用formatUserName的邏輯或者生成一個(gè)全新的、與現(xiàn)有工具函數(shù)重復(fù)的calculateActivityBadge函數(shù)。結(jié)果生成的代碼需要你大量修改才能集成或者引入了新的重復(fù)邏輯。你感覺 AI 很“笨”但實(shí)際上是你的代碼沒有給它提供清晰的“地圖”。2. 解藥深模塊Deep Module架構(gòu)設(shè)計(jì)這個(gè)概念并非 Matt Pocock 獨(dú)創(chuàng)它源自 John Ousterhout 的經(jīng)典著作《A Philosophy of Software Design》。其核心思想是評(píng)價(jià)一個(gè)模塊好壞的標(biāo)準(zhǔn)不是行數(shù)多少而是接口的簡(jiǎn)潔度與內(nèi)部功能的強(qiáng)大度之間的比值。2.1 深模塊 vs. 淺模塊一個(gè)直觀對(duì)比特性淺模塊 (Shallow Module)深模塊 (Deep Module)接口復(fù)雜、龐大、暴露大量細(xì)節(jié)簡(jiǎn)單、小巧、隱藏復(fù)雜細(xì)節(jié)實(shí)現(xiàn)可能很簡(jiǎn)單與接口復(fù)雜度不匹配內(nèi)部可能很復(fù)雜但對(duì)外接口簡(jiǎn)潔認(rèn)知負(fù)荷高。使用者需要了解很多接口細(xì)節(jié)才能使用。低。使用者通過簡(jiǎn)單的接口就能獲得強(qiáng)大的功能。對(duì) AI 的影響AI 需要處理大量無關(guān)接口信息難以理解核心職責(zé)。AI 通過簡(jiǎn)潔接口就能把握模塊核心功能易于正確調(diào)用和擴(kuò)展。類比一臺(tái)面板上有100個(gè)按鈕但只能播放音樂的“播放器”。一臺(tái)只有一個(gè)“播放”按鈕但內(nèi)部集成了高品質(zhì)音響、降噪、網(wǎng)絡(luò)流媒體的智能音箱。2.2 深模塊的四個(gè)關(guān)鍵特征強(qiáng)大的抽象模塊提供一個(gè)高層次的、解決問題的抽象而不是一系列低層次的操作步驟。簡(jiǎn)潔的接口暴露給外部的 API 或方法數(shù)量盡可能少參數(shù)清晰。隱藏的實(shí)現(xiàn)將復(fù)雜性、算法、數(shù)據(jù)轉(zhuǎn)換、第三方依賴等封裝在模塊內(nèi)部。明確的職責(zé)一個(gè)模塊只做一件事并把它做到極致。3. 實(shí)戰(zhàn)重構(gòu)將“淺模塊”代碼轉(zhuǎn)化為“深模塊”讓我們用一個(gè)具體的例子看看如何重構(gòu)代碼使其對(duì) AI 更友好。場(chǎng)景一個(gè)電商應(yīng)用中的“價(jià)格計(jì)算”邏輯。3.1 重構(gòu)前分散且透明的“淺模塊”代碼// 文件1: src/utils/priceCalculations.ts export function applyDiscount(price: number, discountRate: number): number { return price * (1 - discountRate); } export function addTax(price: number, taxRate: number): number { return price * (1 taxRate); } export function formatPrice(price: number, currency: string): string { return new Intl.NumberFormat(en-US, { style: currency, currency }).format(price); } export function isFreeShipping(subtotal: number, threshold: number): boolean { return subtotal threshold; } // 文件2: src/components/Checkout.tsx import { applyDiscount, addTax, formatPrice, isFreeShipping } from ../utils/priceCalculations; function Checkout({ items, userDiscount }) { // 業(yè)務(wù)邏輯散落在組件中 const subtotal items.reduce((sum, item) sum item.price, 0); const discountedPrice applyDiscount(subtotal, userDiscount); const finalPrice addTax(discountedPrice, 0.08); // 硬編碼稅率 const shippingEligible isFreeShipping(subtotal, 50); return ( div pSubtotal: {formatPrice(subtotal, USD)}/p pFinal Price: {formatPrice(finalPrice, USD)}/p pShipping: {shippingEligible ? Free : $5.99}/p /div ); }問題AI 在Checkout組件里看到一堆零散的函數(shù)調(diào)用和硬編碼的數(shù)字。如果讓它“添加一個(gè)會(huì)員雙倍積分功能”它很難判斷積分應(yīng)該基于subtotal、discountedPrice還是finalPrice計(jì)算邏輯該加在哪里。3.2 重構(gòu)后封裝良好的“深模塊”代碼我們創(chuàng)建一個(gè)PriceEngine深模塊。// 文件: src/lib/price/PriceEngine.ts export interface PriceCalculationParams { items: Array{ price: number; }; discountRate: number; taxRate: number; freeShippingThreshold: number; } export interface CalculatedPrice { subtotal: number; discountedAmount: number; taxAmount: number; finalAmount: number; isEligibleForFreeShipping: boolean; } export class PriceEngine { private params: PriceCalculationParams; constructor(params: PriceCalculationParams) { this.params params; } calculate(): CalculatedPrice { const subtotal this.calculateSubtotal(); const discountedAmount this.applyDiscount(subtotal); const taxAmount this.calculateTax(discountedAmount); const finalAmount discountedAmount taxAmount; return { subtotal, discountedAmount, taxAmount, finalAmount, isEligibleForFreeShipping: this.checkFreeShipping(subtotal), }; } format(price: number, currency: string USD): string { return new Intl.NumberFormat(en-US, { style: currency, currency }).format(price); } // 私有方法隱藏實(shí)現(xiàn)細(xì)節(jié) private calculateSubtotal(): number { return this.params.items.reduce((sum, item) sum item.price, 0); } private applyDiscount(subtotal: number): number { return subtotal * (1 - this.params.discountRate); } private calculateTax(amount: number): number { return amount * this.params.taxRate; } private checkFreeShipping(subtotal: number): boolean { return subtotal this.params.freeShippingThreshold; } }現(xiàn)在組件中的使用變得極其簡(jiǎn)潔// 文件: src/components/Checkout.tsx import { PriceEngine } from ../lib/price/PriceEngine; function Checkout({ items, userDiscount }) { // 所有復(fù)雜邏輯被封裝 const priceEngine new PriceEngine({ items, discountRate: userDiscount, taxRate: 0.08, freeShippingThreshold: 50, }); const price priceEngine.calculate(); return ( div pSubtotal: {priceEngine.format(price.subtotal)}/p pFinal Price: {priceEngine.format(price.finalAmount)}/p pShipping: {price.isEligibleForFreeShipping ? Free : $5.99}/p /div ); }3.3 為什么重構(gòu)后對(duì) AI 更友好接口極簡(jiǎn)AI 在Checkout組件里只看到一個(gè)PriceEngine的導(dǎo)入和兩個(gè)方法調(diào)用calculate,format。它立刻明白這里是處理價(jià)格的。意圖明確當(dāng)你想讓 AI“添加會(huì)員雙倍積分”時(shí)你可以直接在PriceEngine類上下文中提問。AI 看到calculate()方法返回CalculatedPrice類型它會(huì)自然地建議在這個(gè)類型中添加pointsEarned: number字段并在calculate()方法內(nèi)部添加積分計(jì)算邏輯。所有相關(guān)邏輯都聚集在一個(gè)文件里AI 的上下文高度相關(guān)。隱藏變化稅率、免郵閾值等細(xì)節(jié)被封裝在參數(shù)和私有方法中。AI 不會(huì)在業(yè)務(wù)組件里被這些細(xì)節(jié)干擾從而更專注于核心業(yè)務(wù)流。4. 跨技術(shù)棧的深模塊設(shè)計(jì)模式深模塊是一種思想不限于 TypeScript 或前端。4.1 后端Node.js with NestJS服務(wù)層封裝// 淺模塊風(fēng)格控制器里充滿邏輯 Controller(users) export class UsersController { constructor(private usersService: UsersService) {} Post(register) async register(Body() dto: RegisterUserDto) { // 驗(yàn)證、業(yè)務(wù)邏輯、加密、郵件發(fā)送全堆在這里或分散在多個(gè)服務(wù)方法中 const exists await this.usersService.findByEmail(dto.email); if (exists) throw new ConflictException(Email exists); const hashedPwd await bcrypt.hash(dto.password, 10); const user await this.usersService.create({ ...dto, password: hashedPwd }); await this.mailService.sendWelcomeEmail(user.email); return user; } } // 深模塊風(fēng)格一個(gè)清晰的“用例”服務(wù) Injectable() export class UserRegistrationService { // 依賴注入其他服務(wù) constructor( private userRepo: UserRepository, private mailService: MailService, ) {} // 一個(gè)強(qiáng)大的公共方法隱藏所有復(fù)雜性 async execute(dto: RegisterUserDto): PromiseUser { await this.validateRegistration(dto); const user await this.createUserEntity(dto); await this.userRepo.save(user); await this.sendWelcomeNotification(user); return user; } // 私有方法封裝細(xì)節(jié) private async validateRegistration(dto: RegisterUserDto): Promisevoid { // ... 檢查郵箱唯一性、密碼強(qiáng)度等 } private async createUserEntity(dto: RegisterUserDto): PromiseUser { // ... 密碼哈希、生成驗(yàn)證令牌等 } private async sendWelcomeNotification(user: User): Promisevoid { // ... 發(fā)送郵件、記錄日志等 } } // 控制器變得非常薄 Controller(users) export class UsersController { constructor(private registrationService: UserRegistrationService) {} Post(register) async register(Body() dto: RegisterUserDto) { return this.registrationService.execute(dto); } }對(duì) AI 的益處AI 在修改注冊(cè)邏輯如添加手機(jī)號(hào)驗(yàn)證時(shí)只需關(guān)注UserRegistrationService這個(gè)深模塊無需跳轉(zhuǎn)查看控制器、倉庫、郵件服務(wù)等多個(gè)文件上下文集中生成代碼的準(zhǔn)確性大幅提高。4.2 通用原則創(chuàng)建“領(lǐng)域語言”深模塊的終極目標(biāo)是讓你的代碼庫形成一套高級(jí)的“領(lǐng)域特定語言”DSL。當(dāng)你的模塊提供了像PriceEngine.calculate()、UserRegistrationService.execute()這樣高層次的抽象時(shí)AI 就能用這種高級(jí)語言和你對(duì)話而不是糾纏于底層的applyDiscount或bcrypt.hash。5. 結(jié)合 AI 工具的最佳實(shí)踐工作流理解了深模塊我們可以優(yōu)化使用 Cursor/Copilot 的工作流。5.1 第一步在正確的上下文中提問錯(cuò)誤在龐大的App.tsx里問“如何實(shí)現(xiàn)價(jià)格計(jì)算”正確打開或創(chuàng)建src/lib/price/PriceEngine.ts文件然后問“在這個(gè)PriceEngine類中如何添加一個(gè)計(jì)算會(huì)員積分的方法積分規(guī)則是每消費(fèi)1美元得1積分折扣后金額計(jì)算。”5.2 第二步利用 AI 進(jìn)行重構(gòu)你可以直接給 AI 指令“將當(dāng)前這個(gè)分散的utils/priceCalculations.ts和Checkout組件中的邏輯重構(gòu)為一個(gè)深模塊PriceEngine。” 一個(gè)設(shè)計(jì)良好的 AI 能夠根據(jù)現(xiàn)有代碼生成類似于第 3.2 節(jié)的初步結(jié)構(gòu)。5.3 第三步定義清晰的接口和類型這是幫助 AI 理解模塊邊界的關(guān)鍵。在創(chuàng)建新模塊時(shí)先讓人或 AI 寫出主要的接口Interface和類型Type。// 先定義清楚模塊要做什么 export interface Campaign { id: string; name: string; discountType: percentage | fixed; value: number; } export interface PricingResult { original: number; discounted: number; applicableCampaigns: Campaign[]; } export interface PricingCalculator { calculateFinalPrice(items: LineItem[], campaigns: Campaign[]): PricingResult; }然后讓 AI 去實(shí)現(xiàn)PricingCalculator。有了清晰的接口約束AI 的實(shí)現(xiàn)會(huì)更符合預(yù)期。5.4 第四步迭代與封裝AI 生成代碼后檢查是否有暴露過多的內(nèi)部細(xì)節(jié)。將不必要公開的輔助函數(shù)改為private將配置參數(shù)收攏到構(gòu)造函數(shù)或配置對(duì)象中。不斷問自己“這個(gè)模塊的接口還能更簡(jiǎn)單嗎”6. 常見問題與排查思路問題現(xiàn)象可能原因排查方式解決方案AI 生成的函數(shù)總是操作錯(cuò)誤的數(shù)據(jù)結(jié)構(gòu)模塊接口混亂數(shù)據(jù)結(jié)構(gòu)不一致或未隱藏。檢查相關(guān)模塊的輸入輸出類型定義是否清晰、統(tǒng)一。定義并導(dǎo)出清晰的 DTO數(shù)據(jù)傳輸對(duì)象或領(lǐng)域模型讓所有函數(shù)都基于這些標(biāo)準(zhǔn)類型操作。AI 無法理解跨多個(gè)文件的業(yè)務(wù)邏輯邏輯過于分散形成“淺模塊”網(wǎng)絡(luò)。尋找一個(gè)業(yè)務(wù)流程如“用戶下單”看它涉及了多少個(gè)文件。將該業(yè)務(wù)流程重構(gòu)為一個(gè)“深模塊”服務(wù)、用例或管理器聚合相關(guān)邏輯。AI 在補(bǔ)全時(shí)提供完全不相關(guān)的建議當(dāng)前文件職責(zé)不單一包含太多不同領(lǐng)域的代碼。審查當(dāng)前文件是否混合了視圖、邏輯、工具等多種代碼。使用“抽取函數(shù)”或“抽取類”重構(gòu)將不同職責(zé)的代碼分離到不同的深模塊中。使用“引用代碼庫”功能后AI 引用了無關(guān)代碼代碼庫中命名相似但功能無關(guān)的模塊太多。檢查被引用的無關(guān)代碼的命名和位置。采用更具描述性、唯一性的模塊名和文件名。遵循功能分區(qū)目錄結(jié)構(gòu)如/lib/auth,/lib/payment。對(duì) AI 描述需求很費(fèi)力需要寫很長(zhǎng) prompt代碼抽象層次太低缺乏領(lǐng)域語言。嘗試用一句話描述你想讓某個(gè)模塊做的事如果這句話很長(zhǎng)且包含“和”、“然后”、“首先”等詞說明抽象不夠。將這一連串操作封裝到一個(gè)新的深模塊方法中并用那句描述來命名這個(gè)方法。7. 最佳實(shí)踐與工程建議從領(lǐng)域驅(qū)動(dòng)設(shè)計(jì)DDD中汲取靈感聚合根Aggregate、實(shí)體Entity、值對(duì)象Value Object和領(lǐng)域服務(wù)Domain Service天然就是深模塊。它們定義了清晰的邊界和職責(zé)。依賴注入DI是好朋友它強(qiáng)制你定義清晰的接口并將模塊的依賴關(guān)系顯式化這極大地幫助了 AI 理解模塊的上下文和職責(zé)。如上文 NestJS 示例。編寫簡(jiǎn)潔的模塊文檔JSDoc/TSDoc在模塊和類級(jí)別用一兩句話說明它的核心職責(zé)。AI 在檢索時(shí)會(huì)讀取這些注釋從而更好地理解模塊用途。/** * 核心定價(jià)引擎負(fù)責(zé)計(jì)算訂單的各類價(jià)格、折扣、稅費(fèi)及運(yùn)費(fèi)資格。 * 封裝了所有定價(jià)規(guī)則和計(jì)算邏輯。 */ export class PriceEngine { ... }為深模塊編寫單元測(cè)試測(cè)試即文檔。清晰、覆蓋全面的測(cè)試用例向 AI 展示了模塊在各種邊界條件下的預(yù)期行為是極佳的上下文。避免“上帝對(duì)象”和“工具類陷阱”一個(gè)包含 50 個(gè)靜態(tài)方法的Utils類是典型的淺模塊。應(yīng)該按領(lǐng)域?qū)⑵洳鸱譃镾tringUtils、DateUtils、PriceUtils等并最終演進(jìn)為更深的領(lǐng)域模塊。循序漸進(jìn)不必一步到位不要試圖一次性重構(gòu)整個(gè)項(xiàng)目。下次當(dāng)你需要 AI 協(xié)助修改某個(gè)功能時(shí)就以那個(gè)功能為起點(diǎn)將其重構(gòu)為一個(gè)更深的模塊。積少成多代碼庫對(duì) AI 的友好度會(huì)逐漸提升。8. 總結(jié)與后續(xù)方向Matt Pocock 的觀點(diǎn)之所以深刻是因?yàn)樗赋隽巳藱C(jī)協(xié)作中的一個(gè)根本性轉(zhuǎn)變?cè)?AI 時(shí)代代碼的可讀性對(duì)象不再僅僅是人類同事還包括 AI 智能體。“深模塊”架構(gòu)本質(zhì)上是在為 AI 優(yōu)化代碼的“可檢索性”和“可推理性”。提升 AI 編程效率從癡迷于編寫“完美 prompt”轉(zhuǎn)向精心設(shè)計(jì)“清晰代碼結(jié)構(gòu)”是一個(gè)更高杠桿率的投資。這不僅能讓你更好地駕馭 AI 工具更能從根本上提升代碼質(zhì)量降低維護(hù)成本讓團(tuán)隊(duì)協(xié)作也更順暢。你的下一步行動(dòng)可以是審計(jì)一個(gè)模塊在你的項(xiàng)目中找一個(gè)經(jīng)常讓 AI“犯糊涂”的功能點(diǎn)用本文的“深模塊”標(biāo)準(zhǔn)評(píng)估它。進(jìn)行一次小規(guī)模重構(gòu)花 30 分鐘嘗試將這個(gè)功能點(diǎn)重構(gòu)成一個(gè)接口更簡(jiǎn)潔、職責(zé)更明確的模塊。測(cè)試 AI 協(xié)作效果在重構(gòu)后的模塊上向 Cursor 或 Copilot 提出一個(gè)新的、相關(guān)的功能需求感受生成代碼的準(zhǔn)確度變化。記住最好的 prompt 工程可能就是從寫好你的下一條代碼注釋、設(shè)計(jì)好下一個(gè)函數(shù)接口開始的。當(dāng)你開始像為一位強(qiáng)大的、但注意力有限的合作伙伴編寫文檔一樣去編寫代碼時(shí)你就已經(jīng)走在了人機(jī)協(xié)同編程的前沿。