AGENTS.md：Agent 的指令本

本章摘要：

AGENTS.md 是用户写给 Agent 的规矩——多层 AGENTS.md 拼接后包装为系统提醒插入用户消息之前。AGENTS.md 是软约束，不是硬配置——Agent 尽力遵循但不保证严格遵守。

每个现代 Agent 系统通常都允许用户在项目根目录放置一个 AGENTS.md 之类的文件（Claude Code 用 CLAUDE.md 文件）作为指令本：编码标准、项目架构、工作流约定。启动时加载到上下文，Agent 尽力遵循。

AGENTS.md 是上下文而非强制配置——Agent 尽量遵循但不保证严格遵守。硬阻止某个操作需要更底层的机制（如钩子系统，详见后续章节）。

该写什么 / 不该写什么

适合写

• 反复需要解释的内容（以开发为例：编码风格、测试命令、提交规范）
• 团队新人需要知道的背景（以开发为例：架构决策、命名约定）
• 反复犯的错误：避免重复沟通

不适合写

• 多步骤过程（应拆为技能）
• 仅对部分代码重要的内容（应使用条件规则）
• 长篇文档（应单独维护，通过引用导入）

好的指令	模糊的指令
"使用 2 空格缩进"	"正确格式化代码"
"提交前运行项目的测试套件"	"测试你的更改"

具体性让 Agent 更容易遵循——模糊的指令让 Agent 自行揣测，结果往往不一致。

一些实践经验

注释：可通过块级 HTML 注释（<!-- 维护者笔记 -->）语法写"维护者笔记"，注入上下文前被移除，不消耗 token。

导入其他文件：用 @path 语法引用其他文件，被引用文件会与主文件拼接注入（不是文本内联——原文中的 @xxx 文本保留不变，新文件会被拼接在后面，以 xxxx/xxx 文件的内容如下： 打头）。导入有最大嵌套层数限制（推荐最多 5 层）。

AGENTS.md 的分层来源

系统按作用范围从大到小收集多个层级的 AGENTS.md：

层级	作用范围
组织托管	整个组织
用户级	当前用户所有项目
项目级	团队共享（提交到版本控制）
本地级	仅自己（不提交到版本控制）

所有层的 AGENTS.md 文本拼接在一起同时生效。多层之间是拼接而非覆盖——每一层都加上一道约束。出现矛盾时，Agent 自行判断，越具体、越靠近工作目录的指令通常越优先。没有硬性覆盖规则——避免矛盾、定期审查。

注入方式

系统启动时收集所有层的 AGENTS.md，拼接后包装成一条用户消息插入对话开头（仅一次，不会每轮都重新插入）。

为什么 AGENTS.md 不放在系统提示词中？ 核心考虑是权限隔离——系统提示词定义不可逾越的安全红线，AGENTS.md 是用户编写的项目规范；混在一起若遇恶意 AGENTS.md 可能劫持安全指令。放在用户消息中则语义明确：系统提示的优先级始终最高。

包装后的消息形如：

<system-reminder>
{所有层 AGENTS.md 拼接后的文本}
{其他动态上下文}
</system-reminder>

<system-reminder> 标签的作用是告诉 Agent"这是元信息，不是用户的真实话语"，但消息的角色仍是 user。Agent 像读用户消息一样读取 AGENTS.md，尽力遵循，但没有系统层面的强制力。

拆分到 rules 子目录

较大项目中，将指令拆分到专门的 rules 子目录（如 .agents/rules/），模块化且易维护。拆分文件纯粹是为了模块化维护——技术实现上与写在 AGENTS.md 中完全等价。

your-project/
├── AGENTS.md               # 主项目指令
└── .agents/
    └── rules/
        ├── code-style.md   # 代码样式
        ├── testing.md      # 测试约定
        └── security.md     # 安全要求

条件规则：paths 字段

如果项目某条规则只在处理特定类型文件时才相关（比如"TypeScript 项目的代码审查清单"），可以使用 paths 字段做条件加载——Agent 读取匹配路径的文件时，该规则才被注入上下文。

条件加载的核心价值是减少噪音。如果所有规则都常驻上下文，无关规则会稀释模型对当前任务的关注。

paths 是写在 Markdown 文件开头元数据头（frontmatter）中的一个字段。Markdown 文件可以带一段 YAML 格式的元数据头（称为 frontmatter），用于声明该文件的元信息——paths 是其中一种元信息。

本章要点

• AGENTS.md 是用户写给 Agent 的指令本，启动时加载到上下文
• AGENTS.md 是软约束，不是硬配置——Agent 尽力遵循但不保证
• 多层 AGENTS.md 拼接在一起，不覆盖——所有层的指令同时生效
• AGENTS.md 被故意放在用户消息而非系统提示——为了权限隔离
• 条件规则（paths 字段）按需注入，减少无关规则的噪音
• 写指令要具体、可验证，避免模糊措辞