AGENTS.md 进阶：如何让 AI 从「被动听从」变为「主动查阅」
文章摘要：本文探讨了如何让AI真正学会查阅AGENTS.md文档而非仅被动接受内容。关键在于将"查阅"行为转化为可执行指令：1)将文档链接改写为强制执行的查阅任务；2)提供具体的命令行工具集；3)建立明确的查阅触发条件。进阶技巧包括要求AI输出查阅日志和设置自动验证流程。最终目标是让AI形成"查阅-验证-输出"的闭环，使AGENTS.md成为真正的知识导航系
你写好了 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` 命令。*更多推荐
13
0- 0
已为社区贡献1条内容
所有评论(0)