我最早以为，AI 编程助手读懂一个项目，是像人一样从 README 开始，顺着入口文件一路啃下去。直到有一次，我把一个堆了三百个文件的旧项目丢给 Copilot，它只用了几秒就指出「paymentService 的 mock 应该放在 tests/unit 下面」。那一刻我意识到，它可能根本还没读代码，只是看了目录树。
没错，Agent 理解项目的起点，几乎都是那棵目录树。Anthropic 的工程师在这篇文章里反复强调：让模型理解代码库，不是把全部代码塞进上下文，而是给它一张足够精确的地图。文件树就是最廉价的地图。
| 对比维度 | 人类 | Agent |
|---|---|---|
| 第一次读项目 | 打开 README，找入口文件 | 先抓取整棵目录树 |
| 记忆的单位 | 抽象模块名 | 路径字符串 |
| 理解方式 | 语义联想 + 经验 | 统计模式匹配 |
| 对命名的敏感度 | 高 | 极高 |
一段 tree 输出，几百个 token，就能看出项目是前端还是后端、是不是分层、有没有测试目录、大概有哪些业务领域。而读完整套源码可能要几十万 token。Agent 的策略永远是：先扫地图，再按需深入。
文件名是压缩过的注释
拿 userService.ts 来说，路径本身就藏着三层信息：user 是领域实体，Service 是架构角色，.ts 是语言类型。Agent 会把路径按分隔符切成词，再把每个词映射到它在海量代码里学到的统计语义——这是它判断文件职责的第一证据。GitHub 的官方文档也确认，Copilot Chat 会利用仓库结构，特别是文件名和目录名来组装上下文。
以下几种命名模式，Agent 几乎都能一眼识别：
| 模式 | 含义 | 举例 |
|---|---|---|
*.test.js / *_test.go |
单元测试 | utils/billing.test.js |
*Service / *Controller |
业务服务 / 请求入口 | account/AccountController.ts |
*Repository.php |
数据访问层 | UserRepository.php |
*.d.ts |
类型声明 | models/index.d.ts |
*.mock.* |
测试替身 | services/payment.mock.ts |
这些不是明文标准，而是生态里心照不宣的默认值。Agent 在训练数据里见过数亿次这种模式，所以它看到 AuthController 就能猜到这是处理登录鉴权的地方——虽然它一行代码还没读。
层级关系是压缩过的架构文档
斜杠 / 是天然的分区。顶层目录表达的往往是关注点的切分：src 主代码，tests 测试，docs 文档，scripts 工具。子目录则是进一步的领域划分。比如：
backend/
src/
modules/
payment/
controllers/
services/
models/这个结构在告诉 Agent：支付被单独拆成一个模块，模块内部按 MVC 分层。你可能觉得这没什么可推测的，但 Agent 把这个结构当作一种先验，再用代码内容去验证。即使内容完全陌生，它也会优先相信文件名的提示。
这种约定并不是巧合。Go 的官方代码组织文档强调包名和目录路径严格对应，已经成为整个生态的事实标准。pytest 的官方最佳实践也固定了 tests 目录作为测试包的根。当一种结构被无数项目不约而同地遵循，Agent 的识别几乎不需要额外的思考。
Agent 实际怎么推断？拆给你看
我自己想通这件事，是在观察一个困惑之后。我反复给 Agent 丢命名混乱的文件夹，发现它的表现会一落千丈。后来我发现，它的“目录结构理解”其实是一个固定管线：
- 把路径按
/、-、_、.拆成词。 - 把每个词映射到常见语义角色（module、service、model、test、mock、config……）。
- 结合同级目录中其他文件名，判断当前文件是正常版本还是特殊变体（比如 mock、spec、min）。
- 如果仍不确信，就去瞄最近的 README 或 package.json 这类自描述文件来收束。
换句话说，Agent 的目录结构理解是模式匹配 + 先验填充。它并没有真的“看透”你的架构，而是把你的命名放进一个从几百万开源项目里学来的统计模板。一旦你的项目命名完全不按常理出牌，这个模板就会失效。
这个结论让我松了口气——它证明这玩意儿没有魔法，只是一个非常擅长迁移学习的统计引擎。
看到这里，你可能有个疑问：那我只要把目录结构起得好，Agent 是不是就能真正理解我的项目？别高兴太早。它仍然需要读几个关键文件来验证，但目录结构决定了它从哪里开始验证，以及验证时是不是带着正确的地图。
那它到底会在哪里翻车？
根据我的观察，主要有三类场景：
- 语义黑洞：目录名是 aaa、tmp2、x1。没有可索引的语义锚点，Agent 只能瞎猜。
- 同名文件堆叠：同一个目录下塞了 index.ts、index.test.ts、index.css、index.md。它只能靠扩展名区分，很容易在推理时拿错文件。
- 层级过深：路径全是包名前缀，业务名词被埋到最后。比如 src/com/example/infrastructure/adapters/persistence/repositories/UserRepositoryImpl.java。连人类都要数两遍，Agent 也会把注意力稀释在无用的前缀上。
另外，很多 Agent 工具默认忽略 .gitignore 列出的目录，比如 node_modules。这带来的副作用是：如果某些重要依赖没在源码目录里，Agent 对项目全貌的理解就会有盲区。
想让 Agent 更懂你的项目？让目录树说人话
如果你正在用 AI 编程助手，又觉得它总在无关文件上抓瞎，最好的办法不是给它更多上下文，而是优化你的目录树：
- 目录名用领域词汇，不要用 components2 这种带数字的。
- 测试目录和源码目录平级，让 Agent 一眼就能建立“源码↔测试”的映射。
- 一个模块尽量一个目录，内部按角色命名文件。
- 缩写统一，比如 svc 和 service 不要混用。
- 核心模块放一个短小的 README，比让 Agent 读几十行代码更高效。
有些朋友会问：为什么不让 Agent 直接读代码，非要看目录树？因为 token 是钱，而结构信息是免费的。用几千 token 看全貌，再花几百 token 深入局部，远比一次读几十万 token 便宜得多，也准确得多。Anthropic 那篇上下文工程的文章强调的正是这个思路——把最相关的信息放在最前面，其余的按需检索。
最后我想说一句可能得罪人的话：目录结构混乱，不能全靠 Agent 的“理解能力”来补救。你留下的每一个命名，都是在替自己存一条语义记录；Agent 只是那个读记录的人。你写下的名字越诚实，它读出来的架构就越准确。真正的架构，从来不是靠代码写出来的，而是靠名字长出来的。
原创文章，作者：guanweilu，如若转载，请注明出处：https://guanweilu.cn/article/796.html