代码库才是最大的 prompt：深模块的第二春，接口归人、实现归 AI
一段视频文案讲「对 AI 产出影响最大的不是 prompt，是你的代码库」，引用《软件设计的哲学》的深模块概念。溯源到原文：Matt Pocock（Total TypeScript / AI Hero 作者）的《How To Make Codebases AI Agents Love》（aihero.dev）。这篇用…
代码库才是最大的 prompt：深模块的第二春，接口归人、实现归 AI
一段视频文案讲「对 AI 产出影响最大的不是 prompt，是你的代码库」，引用《软件设计的哲学》的深模块概念。溯源到原文：Matt Pocock（Total TypeScript / AI Hero 作者）的《How To Make Codebases AI Agents Love》（aihero.dev）。这篇用素材海关过一遍，然后接进接口税主线——因为它讲的其实是同一件事：什么结构应该穿过人机边界。
一、素材海关：转述保真度裁决
视频文案 vs 原文逐条核对（原文实抓）：
| 视频文案声明 | 原文对应 | 裁决 |
|---|---|---|
| 「对 AI 产出影响最大的不是 prompt，是代码库」 | "Your codebase, way more than your prompt or your AGENTS.md file, is the biggest influence on AI's output" | 属实，原文还多砍了一刀：AGENTS.md 也不行 |
| 三代价：反馈慢/难导航/认知透支 | Poor feedback loops / Hard to navigate / Cognitive burnout | 属实 |
| 像《记忆碎片》男主 | "like the guy from Memento stepping into your codebase" | 属实，原文原话 |
| 深模块出自《软件设计的哲学》 | "comes from A Philosophy of Software Design" | 属实，Ousterhout 2018，深模块=简单接口后藏大量实现 |
| 灰盒模块：接口留给自己，实现交给 AI | "You own the interface. AI owns the implementation. Tests keep it honest." | 属实，原文还有视频没转的第三句：测试当公证人 |
| 脑子里只装七八个大块 | "seven or eight chunks" | 属实 |
| AI 是每天入职 20 次的新员工 | "You're spawning 20+ new starters a day" | 属实 |
| 20 年老实践，对人类有效对 AI 同样有效 | "This is how good codebases have been designed for 20 years. What works for humans is also great for AI." | 属实——但这是全文最值得推敲的一句，见下文 |
| Effect 让无缝模块化变简单 | "I've been using Effect more and more" | 口径注意——Pocock 是 Effect 重度布道者，这段是自荐，方案之一不是唯一解 |
/improve-codebase-architecture skill，让 agent 自动审计重构代码库朝深模块模式收敛——文章的处方已经产品化成 agent 自己能执行的 skill；以及 Reddit 上流传的他的工作流（GitHub Issues 当看板、窄垂直切片）。二、核心论点的结构：为什么代码库压过 prompt
Prompt 和代码库的关系，用接口税的语言一句话说清：prompt 是一次性参数，代码库是常驻接口。每次 spawn 新 agent，prompt 决定它「这次干什么」，代码库决定它「能看到什么、能走多快、错了之后多久知道」。前者的作用域是一次会话，后者是所有会话的共同环境。三个代价翻译过来：
- 反馈慢 = 验证带宽的延迟税：AI 改完不知道对不对，就继续在错误上堆叠
- 难导航 = 上下文窗口的接口税：拍平进窗口的 token 里，多少在描述结构、多少在描述噪音
- 认知透支 = 人类验证带宽被实现细节吃光：你在替 AI 补它的上下文
三、深模块的第二春：从「藏」到「委托」
Ousterhout 2018 年说深模块是「大量实现藏在简单接口后面」，批评浅模块宽接口「不消除复杂性，只是把它转移给使用者」。这个概念沉寂多年后，在 agent 时代被 Pocock 做了一次语义反转——「藏」变成了「委托」：
- 20 年前：复杂实现被接口藏起来，使用者不用关心
- 2026 年：复杂实现被接口圈起来，AI 负责写，你不用关心
Memento 隐喻值得升级一层：男主没有长期记忆，靠纹身和照片这些外部物理记忆运转——LLM 是 session 级失忆 + 代码库级持久，这不是缺陷，是记忆的架构分层。代码库是人类与 AI 共享的外置记忆，而且是策划型外存最老的形态——比 CoE 的 trail、Synapse 的联想图、Wayfinder 的 map 早了二十年，只是 agent 时代才反过来被发现「原来它一直是干这个的」。
四、类比失效处：「对人类有效对 AI 同样有效」——同结论，异机制
全文最聪明也最含糊的一句话。结论对，机制不同，分不清这个就学不到迁移条件：
- 深模块对人类有效，因为人类工作记忆装不下几百个模块——是认知瓶颈
- 深模块对 AI 有效，因为接口签名是上下文窗口里信息密度最高的 token：一个函数签名 + 类型标注，几十个 token 承载一个模块的全部可调用语义，实现是按需检索的——是上下文经济学，也就是接口税最小化
对照 Prime Agent 正好凑成谱系两极：Prime 把接口数量坍缩成一个（ipython，结构由代码承载）；深模块把接口收敛到七八个大块（结构由模块边界承载）。两个方向的公共假设是同一个——结构要活在代码里，不活在上下文描述里。AGENTS.md 之类的静态文件为什么被原文点名压不过代码库：它是「关于结构的自然语言转述」，而模块边界是结构本身。
编辑观察
这篇文章的真正贡献不是「代码库重要」（这在 agent 工程圈已是共识，jamescroft、moderndescartes 等都在写同题），而是把人机分工说成了产权问题：接口归人、实现归 AI、测试公证。往主线里放：这是验证带宽经济学最干净的工程化样本——测试把「审 AI 写的代码」变成「跑断言」，人只在边界上花带宽；接口设计是人的品味税，实现是 AI 的 token 税，两条税线第一次分账。值得留档的反方：Ousterhout 本人的深模块是为人写的，他书的最后一章还在讨论「AI 会怎么改变设计」这种当时还抽象的问题；如果模型继续变强，深模块的「深」是否还有必要——接口变浅、实现靠模型长上下文直接啃，也是一条可能的坍缩路线（M5 Ultra 硬件极那边的 512GB 统一内存就是给这条路铺的）。给一个可打脸预测：12 个月内主流 agent 工具会把「模块地图」做成一等公民——agent 自动维护结构化 codebase map（Pocock 的 /improve-codebase-architecture skill 是雏形），届时「给 agent 画地图」从人肉布道变成工具默认，深模块文章里的手工纪律一半会被自动化。
*核查备注：原文 aihero.dev/how-to-make-codebases-ai-agents-love（2026-09-03 实抓全文）；Ousterhout 深模块定义经多源交叉（softengbook/dev.to/sandordargo）；平行观点 jamescroft.co.uk（2026-04）、moderndescartes.com（2025-10）；Reddit r/vibecoding 有其工作流讨论。Effect 段落已按利益相关标注。*
下一步选项： 1. /improve-codebase-architecture skill 解剖：拉 mattpocock/skills 仓库读这个 skill 的实现，看「让 agent 自动重构代码库朝深模块收敛」的 prompt 和审计规则长什么样（GitHub 直取，20 分钟出短评）； 2. 无类型语言的接口税实测：找同功能的 JS/TS 开源库对比（有类型 vs 无类型），用 Claude Code 跑同样的修改任务对比 token 消耗和成功率（半天出实测数据帖）； 3. 反方路线深挖：长上下文+统一内存（M5 Ultra 那条线）是否会拍扁深模块的必要性——把「接口深浅 vs 上下文长度」的 tradeoff 写成专帖（纯分析，无实测）。