How To Make Codebases AI Agents Love
This article argues that codebase structure matters more than prompts or AGENTS.md files for AI agent output quality. The core idea is applying 'deep modules' from A Philosophy of Software Design: each module exposes a simple interface controlling lots of implementation. The author introduces 'grey box modules'—developers own and test the interface, AI owns the implementation inside. This improves feedback loops (tests are feedback), navigability (filesystem mirrors mental model), and reduces cognitive load (developers only track 7-8 module boundaries). The article notes TypeScript's difficulty enforcing boundaries and recommends the Effect library. For engineers optimizing AI coding workflows.
AI is not a super-powered developer. It's a new starter with no memory. Every time you spawn an agent, it's like the guy from Memento stepping into your codebase going, "Okay, I'm here, what am I doing?"
AI 并不是什么超级开发者。它更像一个没有记忆的新员工。每次你启动一个 AI 代理，它就像《记忆碎片》里的主角走进你的代码库，问道：“好的，我到了，我要做什么？”
Your codebase, way more than your prompt or your AGENTS.md file, is the biggest influence on AI's output. If it's designed wrong, it costs you in three ways.
Poor feedback loops. The AI doesn't receive feedback fast enough, so it doesn't know if what it changed actually did what it intended.
Hard to navigate. The AI finds it super hard to make sense of things, find files, and work out how to test things.
Cognitive burnout. You end up trying to hold together AI and your codebase, patching it all up manually.
相比你的提示词或 AGENTS.md 文件，代码库本身对 AI 输出的影响要大得多。如果设计不当，会带来三重代价。
反馈循环不畅。AI 无法快速获得反馈，因此它无法判断所做的更改是否真正达到了预期目的。
导航困难。AI 很难理解代码结构、找到文件，以及弄清楚如何测试。
认知过载。最终你会试图亲自协调 AI 和代码库，手动修补所有问题。
Imagine this is your codebase:
Each square is a module that exports some functionality — a function, a variable, a component. Inside, you have vague groupings: a thumbnail editor, a video editor, authentication, CRUD forms.
You understand this mental map. But the AI doesn't. What it sees is this:
A bunch of disparate modules that can all import from each other. No groupings, no relationships. And the file system doesn't help — it's all jumbled together.
You're spawning 20+ new starters a day to look at your codebase and make changes. Your codebase needs to be friendly and navigable for them.
假设这是你的代码库：
每个方块都是一个模块，导出某些功能——一个函数、一个变量、一个组件。内部有一些模糊的分组：缩略图编辑器、视频编辑器、认证、CRUD 表单。
你理解这张心理地图。但 AI 不理解。它看到的是这样的：
一堆彼此可以相互导入的零散模块。没有分组，没有关联。文件系统也帮不上忙——全部混在一起。
你每天要启动 20 多个这样的新员工来查看代码库并进行修改。你的代码库需要对它们友好且易于导航。
The file system and design of your codebase needs to match the internal map you have of it. The best way I've found to do that is with deep modules.
Deep modules comes from "A Philosophy of Software Design." The idea is simple: lots of implementation controlled by a simple interface.
Instead of many small modules:
You end up with big chunks of functionality with simple, controllable interfaces. Any exports have to come through that interface.
文件系统和代码库的设计需要与你脑中的内部地图相匹配。我发现实现这一目标的最佳方法是使用深层模块。
深层模块的概念来自《软件设计哲学》。其思想很简单：通过一个简单接口控制大量实现。
不要使用许多小模块：
而是将功能组织成大的代码块，配有简单可控的接口。所有导出都必须经过该接口。
Deep modules create a natural seam in your codebase. You carefully control and design the interface. The implementation inside? Delegate that to AI.
Write tests that lock down the module's behavior. Then you don't need to look inside. You can if you want to — to apply taste, influence the outcome, or improve performance — but as long as the tests pass, you don't need to care.
These are grey box modules. You own the interface. AI owns the implementation. Tests keep it honest.
深层模块在代码库中创建了自然的接缝。你仔细控制并设计接口。内部的实现？交给 AI 去做。
编写测试来锁定模块的行为。这样你就不需要看内部了。当然，如果你想——应用你的判断、影响结果或优化性能——也可以看，但只要测试通过，你就不必操心。
这就是灰盒模块。你拥有接口。AI 拥有实现。测试确保一切如实。
Give each module its own folder with a clear public interface. The AI can see all the services on the file system, read their types, and understand what they do — without digging into the implementation.
We've designed our codebase for progressive disclosure of complexity. The interface sits at the top and explains what the module does. When we need to, we can look inside.
为每个模块创建自己的文件夹，并配有清晰的公共接口。AI 可以看到文件系统上的所有服务，读取它们的类型，并理解它们的功能——而无需深入探究实现细节。
我们将代码库设计为渐进式信息披露。接口位于顶层，说明模块的功能。当需要时，我们可以查看内部。
Instead of holding hundreds of interrelated modules in your head, you keep seven or eight chunks. The AI manages what's inside each one. You only worry about designing the interfaces and how they fit together.
This is still a million miles from vibe coding. You need to apply taste at the boundaries — deciding what goes into which module. But the mental map is radically simpler.
你不再需要在脑中记住数百个相互关联的模块，只需掌握七八个代码块。AI 管理每个块内部的内容。你只需操心设计接口以及它们如何配合。
这仍然与“氛围编程”相去甚远。你需要在边界上运用判断力——决定哪些内容放入哪个模块。但心理地图已经大大简化了。
This is nothing new. This is how good codebases have been designed for 20 years. What works for humans is also great for AI.
Your codebase is probably not ready for AI. Instead of deep modules, you've got a web of interconnected shallow modules:
These are hard to navigate, hard to test, and hard to keep in your head.
The fix is deep modules with clear interfaces and strong tests. Think about module boundaries from your PRDs through to your implementation issues. Tests and feedback loops are essential — they're how your AI new starters know if their changes work.
Some languages make this easier than others. In TypeScript, it's not easy to enforce these boundaries — I've been using Effect more and more because it makes modularizing your codebase simple.
这并非什么新鲜事。20 年来，优秀的代码库一直是这样设计的。对人类有效的方式，对 AI 也同样适用。
你的代码库可能还没有准备好迎接 AI。不是深层模块，而是一个相互连接的浅层模块网络：
这些模块难以导航、难以测试、难以记在脑中。
解决办法是采用具有清晰接口和强力测试的深层模块。从产品需求文档到实现问题，都要考虑模块边界。测试和反馈循环至关重要——它们是 AI 新员工判断更改是否有效的方式。
某些语言对此支持得更好。在 TypeScript 中，强制这些边界并不容易——我越来越多地使用 Effect，因为它让代码库的模块化变得简单。