AGENTS.md 进阶：如何让 AI 从「被动听从」变为「主动查阅」

关注

原创最新推荐文章于 2026-11-02 11:22:46 发布 599 阅读 AI 写同款· GEO 优化 ›

删掉你的 Agent.md！一份让 AI 变笨的“避坑指南” AI辅助编程中的上下文管理误区：Agent.md文件可能适得其反最新研究发现，AI编程中常见的Agent.md或Claude.md等上下文文件不仅效果有限，甚至可能降低模型性能。测试显示，这些文件仅带来4%的性能提升，而AI生成的版本反而使任务完成率下降3%，并增加20%的计算成本。问题根源在于：冗余的架构信息会分散AI注意力（“粉红大象效应”），而过时的静态文件可能误导模型。优化建议：减少冗余：依赖代码自述（如package.json）而非手动编写全局规则。精准干预：仅在AI重复犯错时更新上下文文阅读详情

你写好了 AGENTS.md，但 AI 还是不会自己查文档？问题的关键不在于有没有写，而在于「有没有教会 AI 怎么查」。

写在前面

上个月我写了一篇关于 AGENTS.md 实践的文章，收到了不少读者的反馈。其中一个问题被反复提起：

「我按照模板写了 AGENTS.md，也把项目结构、编码规范都写进去了，但 AI 好像还是只会从我给的上下文里找答案，不会自己去翻项目里的其他文档。怎么办？」

这个问题问得很好。它触及了 AGENTS.md 理念中一个常被忽略的深层问题：

「地图而非手册」的前提是——AI 得学会看地图。

如果你只是把规则写进 AGENTS.md，那 AI 确实会遵守。但如果你希望 AI 遇到不懂的东西时能主动去翻 docs/ 目录、用 git grep 搜索代码库、甚至读取参考项目的源码，你就需要多做一步：把「查阅」本身也写成 AI 能执行的指令。

这篇文章就是来填这个坑的。

前置条件：AI 是怎么知道要看 AGENTS.md 的？

在深入「如何让 AI 主动查阅」之前，有必要先厘清一个前置问题：

AI 并不是自己「决定」去读 AGENTS.md，而是被迫在每次对话中都「已经看过」它了。

工具链的自动注入机制

主流 AI 编程工具（Cursor、Qoder、Claude Code、GitHub Copilot 等）的工作原理包含一个关键环节：

监听项目文件：当你打开一个项目时，工具会自动扫描根目录
查找约定文件：主动寻找 AGENTS.md、CLAUDE.md、.cursorrules 等特定文件名
注入到上下文：在每次对话或代码编辑请求发出前，自动将文件内容作为系统提示词的一部分，静默塞给 AI

所以，你不需要显式告诉 AI「请查阅 AGENTS.md」。当你在那个项目里问任何问题时，AI 已经看过这份文件了。它的回答前提就是「已理解 AGENTS.md 中的项目规则」。

如何验证你的工具确实在注入？

在 AGENTS.md 的第一行写一个明确的指令：

markdown

# AGENTS.md

**重要指令：在回答任何关于本项目的第一个问题时，请务必先回复：
「已理解项目规则，将遵循 AGENTS.md 中的约定。」**

保存后，重启 AI 编辑器，问一个简单的问题（比如「这个项目是做什么的？」）。

如果 AI 回复了那句特定的话 → 注入成功
如果没有 → 检查文件名是否正确、位置是否在根目录、工具是否支持该文件名

为什么必须依赖工具注入？

AI 不会主动去翻你的文件系统，原因有三：

原因	说明
无目的性	AI 只能对用户当前的问题作出反应，没有「我先整体了解一下项目」的主动意识
上下文有限	AI 不知道 `AGENTS.md` 是否比 `package.json` 或当前打开的文件更重要
安全协议	AI 不能随意读取磁盘文件，所有文件访问都基于工具提供的函数调用

因此，「文件自动注入」是 AGENTS.md 机制的底层基石。没有这个，AGENTS.md 就只是一份躺在项目根目录的普通文档。

你的职责：让注入能成功

作为开发者，你只需要确保两件事：

文件放对地方：AGENTS.md 必须放在项目根目录（不是 docs/ 或 src/ 下）
使用标准文件名：AGENTS.md 是目前的事实标准，各工具的兼容情况如下：

工具	识别的文件名
Claude Code	`CLAUDE.md`（可通过软链接兼容 `AGENTS.md`）
Cursor	`AGENTS.md` / `.cursorrules`
Qoder	`AGENTS.md`
GitHub Copilot	`AGENTS.md`
灵码	`AGENTS.md`

一、问题的本质：AI 不会「主动探索」

好，现在 AI 已经读过你的 AGENTS.md 了。然后呢？

来看一个典型场景。

你在 AGENTS.md 里写了这样一段：

markdown

## WebUI 开发

Chromium 的 WebUI 使用 `chrome.send()` 与 C++ 通信。
详细说明请参考 `//docs/webui_explainer.md`。

然后你问 AI：「帮我写一个 WebUI 页面，从 C++ 后端获取一些数据。」

AI 的典型反应是：它会直接基于训练数据中的通用 WebUI 知识来写代码，完全不会去读你提到的那份 webui_explainer.md。

为什么会这样？

因为 AI 的工作模式是「基于当前对话上下文生成回答」。除非你明确告诉它「去读那个文件」，否则它没有动机去主动探索。AGENTS.md 里的「详细说明请参考 xxx.md」——在 AI 看来只是一句普通文本，而不是一个需要执行的指令。

要让 AI 主动查阅，你必须把「查阅」这个动作，写成 AGENTS.md 中的「行为规则」。

二、核心解法：将查阅动作「指令化」

2.1 把「链接」变成「任务」

❌ 无效写法（只是陈述事实）：

markdown

详细说明请参考 `//docs/webui_explainer.md`。

✅ 有效写法（明确要求行动）：

markdown

## 行为规则

在执行任何 WebUI 相关任务前，你必须先完成以下步骤：

1. 读取 `//docs/webui_explainer.md` 文件
2. 找到与当前任务相关的章节（如「注册 Message Handler」）
3. 基于文档内容而非通用知识来生成代码

执行命令示例：
```bash
cat docs/webui_explainer.md | grep -A20 "RegisterMessageCallback"

text

区别在于：后者把「查阅」从一个可选建议变成了任务的前置条件。

### 2.2 提供具体的查阅「工具」

AI 可以在对话中执行 shell 命令（如果环境允许）。利用这一点，你可以给 AI 提供一套「查阅工具」：

```markdown
## 查阅工具包

当遇到不确定的信息时，你可以使用以下命令自行查找：

### 查文档
```bash
# 查找包含某个关键词的 .md 文件
find docs -name "*.md" | xargs grep -l "关键词"

# 读取某个文档的特定章节
cat docs/xxx.md | sed -n '/## 章节标题/,/## 下一个标题/p'

查代码

bash

# 找某个函数的定义位置
git grep -n "^ClassName::FunctionName" -- "*.cc"

# 找某个 API 的使用示例
git grep -B3 -A10 "某个API调用" -- "*.cc" | head -50

查参考项目

bash

# 在参考项目中搜索
git --git-dir=reference-projects/某项目/.git grep "某符号"

text

当你把这些命令写进 AGENTS.md 后，AI 遇到问题时就可以直接复制粘贴执行，而不是凭空猜测。

### 2.3 建立「何时查阅」的触发条件

AI 需要知道：**什么情况下应该去查，什么情况下可以直接写。**

在 AGENTS.md 中，你可以明确列出触发规则：

```markdown
## 查阅触发规则

遇到以下情况时，**必须先查阅再动手**：

| 触发条件 | 查阅目标 | 查阅命令 |
|----------|----------|----------|
| 任务提及 `chrome.send()` 或 WebUI | `docs/webui_explainer.md` | `cat docs/webui_explainer.md \| grep -A30 "chrome.send"` |
| 需要在 Chromium 中新增线程任务 | `base/task/README.md` | `cat base/task/README.md \| head -100` |
| 涉及 `base::BindOnce` 或回调 | `docs/callback.md` | `find docs -name "*callback*" -exec cat {} \;` |
| 需要继承某个 Views 类 | `chrome/browser/ui/views/` 下的现有实现 | `find chrome/browser/ui/views -name "*类似类名*"` |

**默认规则**：如果不确定某个 API 的用法，先执行 `git grep -n "API名称" -- "*.cc" | head -20` 看真实例子。

这样，AI 在面对任务时就能进行「模式匹配」——识别出关键术语，然后执行对应的查阅动作。

三、进阶技巧：让 AI「自我验证」

仅仅查阅还不够。你需要让 AI 在输出答案前，能够验证自己查对了、理解对了。

3.1 强制输出「查阅日志」

你可以在 AGENTS.md 中要求 AI 在回答时附带查阅记录：

markdown

## 回答格式要求

在给出最终答案前，请先用以下格式输出你的查阅过程：

```markdown
## 查阅记录
- 查阅的文档/文件：[文件路径]
- 关键发现：[从文档中找到的约束或示例]
- 验证命令执行的输出：[相关命令的最后几行结果]

## 最终答案
[你的回答]

text

这样，你不仅能知道 AI 有没有查，还能知道它查到了什么、理解是否准确。

### 3.2 设置「验证检查点」

对于复杂任务，你可以在 AGENTS.md 中嵌入验证步骤：

```markdown
## WebUI 任务验证流程

当你完成 WebUI 相关代码生成后，请执行以下验证：

1. 确认 C++ 端已注册对应的 MessageHandler：
   ```bash
   git grep "RegisterMessageCallback.*你的消息名" -- "*.cc"

确认前端调用使用的消息名与 C++ 端一致：

bash
```
git grep "chrome.send.*你的消息名" -- "*.js"
```
如果上述命令无输出，说明代码存在不一致，请修正后再输出。

text

这个设计的好处是：**验证本身也是通过命令完成的**。AI 不需要人类帮忙检查，自己就能发现问题。

---

## 四、完整示例：Chromium WebUI 任务的 AGENTS.md 片段

下面是一个完整的示例，展示如何将上述思路整合到 AGENTS.md 中：

```markdown
## WebUI 开发协作规范

### 行为准则

当任务涉及 WebUI（即 `chrome://` 页面）开发时，你必须遵循「查阅先行」原则：

1. **第一步**：读取 WebUI 开发文档
   ```bash
   cat docs/webui_explainer.md | head -200

第二步：在代码库中找一个相似的实现作为参考

bash

# 查找现有的 WebUI MessageHandler
find chrome/browser/ui/webui -name "*handler*.h" | head -10

# 读取一个具体实现
cat chrome/browser/ui/webui/settings/settings_handler.h
cat chrome/browser/ui/webui/settings/settings_handler.cc

第三步：确认消息注册的模式

bash

git grep -B5 -A10 "RegisterMessageCallback" -- "chrome/browser/ui/webui/*.cc" | head -50

查阅触发规则

任务关键词	必须查阅的文档	验证命令
`chrome.send`	`docs/webui_explainer.md`	见下方验证流程
`CrWebUI`	`content/public/browser/web_ui.h`	`git grep "class CrWebUI" -- "*.h"`
`WebUIMessageHandler`	现有实现示例	`find chrome/browser -name "handler.cc"`

验证流程

完成代码后，执行以下验证：

bash

# 1. 验证消息名无拼写错误
git grep "RegisterMessageCallback.*你的消息名"

# 2. 验证前后端消息名一致
git grep "chrome.send.*你的消息名"

若验证失败，请修正后重新输出。

text

---

## 五、特殊情况：当 AI 不遵守查阅规则时

虽然注入机制保证了 AI 会「看到」规则，但有时 AI 会因上下文过长而「遗忘」或忽略底层的系统指令。此时可以**显式提醒**：

> 「根据项目根目录下的 AGENTS.md 中的约定，这个问题应该如何解决？」

这相当于发出一条更高优先级的指令，强制 AI 回溯并应用初始规则。

另外，如果 AI 频繁不遵守查阅规则，可以考虑：
- 在 AGENTS.md 开头用更强烈的语气强调（如「这是硬性要求，不是建议」）
- 在回答格式要求中强制附带查阅记录
- 在任务描述中明确要求「请先执行 XXX 命令」

---

## 六、效果对比

用了这套方法后，AI 处理 WebUI 任务的行为会有明显变化。

**优化前**（AI 凭通用知识猜测）：

> 我来帮你实现一个 WebUI 页面。在 JS 中调用 `chrome.send('getData')`，然后在 C++ 的 `WebUIMessageHandler` 中处理……

**优化后**（AI 先查后写）：

> 我先查阅一下 Chromium 的 WebUI 文档和相关实现。
> 
> **查阅记录**
> - 查看 `docs/webui_explainer.md` 发现：注册消息处理函数必须使用 `web_ui()->RegisterMessageCallback()`，且参数数量必须与 JS 端匹配。
> - 参考 `chrome/browser/ui/webui/settings/settings_handler.cc` 确认了具体的代码模式。
> - 执行 `git grep -n "RegisterMessageCallback"` 验证了该模式在代码库中的一致性。
> 
> **最终答案**
> 基于文档和现有实现，正确做法是……

区别在于：**后者的代码基于项目实际情况，而不是 AI 训练数据中的通用模板。**

---

## 七、注意事项与局限

这套方法有效的前提是：

1. **AI 工具支持执行命令**。Cursor、Qoder、Claude Code 等支持，但纯对话界面（如网页版 ChatGPT）不行。

2. **查阅命令需要提前验证可用性**。`find`、`git grep` 等命令在 Windows 上可能需要调整为 PowerShell 或 `findstr`。

3. **大型代码库中 `git grep` 可能较慢**。建议在 AGENTS.md 中提示 AI 先用 `--max-count` 限制结果数量。

4. **文件自动注入是基础**。确保 `AGENTS.md` 在项目根目录，且文件名被你使用的工具识别。

5. **AI 可能绕过规则**。遇到这种情况，可以按第五节的方法显式提醒，或调整规则措辞使之更强制。

---

## 写在最后

AGENTS.md 的本质不是给 AI 一本「手册」，而是给 AI 一张「地图」——这个比喻很多人都听过。但真正做到这一点，需要经历三个层次：

1. **基础层**：确保 AI 工具能自动注入 AGENTS.md（文件放对位置、用对名字）
2. **进阶层**：在 AGENTS.md 中把「查阅」写成可执行的指令（提供命令、触发条件、验证流程）
3. **高级层**：让 AI 自我验证，并建立「查阅-验证-输出」的闭环

当 AI 学会了查阅，AGENTS.md 才能真正从「一份写满规则的文档」变成「一个能让 AI 自主探索的知识导航系统」。

而这，可能才是「地图而非手册」这句话的真正含义。

---

*本文中的命令示例适用于 Unix/Linux 环境。如果你在 Windows 上使用，请相应调整为 PowerShell 或 `findstr` 命令。*

收录于