你写好了 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 等）的工作原理包含一个关键环节：

  1. 监听项目文件：当你打开一个项目时，工具会自动扫描根目录

  2. 查找约定文件：主动寻找 AGENTS.md、CLAUDE.md、.cursorrules 等特定文件名

  3. 注入到上下文：在每次对话或代码编辑请求发出前，自动将文件内容作为系统提示词的一部分，静默塞给 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 就只是一份躺在项目根目录的普通文档。

你的职责：让注入能成功

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

  1. 文件放对地方：AGENTS.md 必须放在项目根目录（不是 docs/ 或 src/ 下）

  2. 使用标准文件名：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"

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

    bash

    git grep "chrome.send.*你的消息名" -- "*.js"

  2. 如果上述命令无输出，说明代码存在不一致，请修正后再输出。

text

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

---

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

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

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

### 行为准则

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

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

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

    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

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

    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` 命令。*
# 人工智能 # AI
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

2026亲测：AI 印花提取工具有哪些？这个工具让我效率翻倍！

更关键的是,西米AI不支持批量提取,每次只能上传一张图片进行处理,对于电商卖家批量上新、印花厂一次性处理几十张客户图的需求来说,效率太低,且订阅费用叠加后成本较高,不适合高频或批量场景使用。单张约几毛钱,可在线批量提取或云托管批量提取;

avatar AtomGit开源社区
cover

第13节课：基于 LangGraph 搭建企业级基础RAG智能体

avatar AtomGit开源社区
cover

AI 应用实战 —— 打造你的 AI 智能伴侣

avatar AtomGit开源社区