一、基础定义：什么是 agents.md（AGENTS.md）
AGENTS.md 是 AAIF（Agentic AI Foundation）推出的跨 IDE 标准化 AI 智能体指令文件 ，专门写给 AI 而非人类 README，Trae 原生深度集成，作为项目级 AI 行为宪法。
核心定位
-
区分全局 / 项目规则
- 全局规则：Trae 客户端设置内，全项目永久生效；
AGENTS.md：项目级规则，仅当前仓库生效，子目录可放局部 AGENTS.md 覆盖局部逻辑（monorepo 多分包隔离）。
-
与同类文件优先级（Trae 加载顺序，由高到低）子目录
AGENTS.md> 项目根AGENTS.md>CLAUDE.md> Trae 客户端全局规则 > LLM 内置系统提示词。 -
文件内容分类（AI 可直接解析的结构化 Markdown）
- 项目元信息：技术栈、目录结构、架构约束；
- 行为约束：编码规范、注释、文件命名、导入规则；
- 工作流指令：启动 / 测试 / 构建 / 校验命令、提交规范；
- 多智能体路由规则：定义协调 Agent 如何分派前端 / 后端 / 测试 / 运维专项 Agent；
- 执行校验规则：修改后必须运行的 lint、单元测试、静态检查；
- 工具权限约束：限制 bash 读写、文件删除、网络调用范围。
二、Trae 读取 agents.md 完整流水线（7 层底层执行链路）
第 1 层：会话初始化 ------ 自动扫描文件系统（无人工触发）
用户发起任务（聊天 / 文件编辑 / 自动 Agent 任务）时，TraeAgent入口类自动触发文件检索器：
- 检索起点：当前操作文件所在目录；
- 向上递归遍历：逐级向上查找
AGENTS.md，直到仓库根目录； - 多文件合并：收集所有层级
AGENTS.md，按就近覆盖合并（子目录规则覆盖根目录冲突项）； - 开关校验：读取 Trae 设置→规则面板，确认「将 AGENTS.md 包含在上下文」开关开启，关闭则直接跳过加载；
- 缓存持久化：文件内容存入会话内存
AgentExecution状态容器，会话全程复用，避免重复磁盘 IO。
第 2 层：解析层 ------Markdown 结构化抽取与规则归一化
Trae 内置轻量 MD 解析器，不依赖大模型，本地预处理：
-
分块切割：按
## 标题分割指令块，标记块类型（项目规范 / 路由策略 / 校验流程 / 权限限制）； -
冲突去重：相同约束以更深子目录文本覆盖上层；
-
约束量化：将自然语言规则转为 LLM 易识别的强制指令前缀（
MUST必须/SHOULD建议/NEVER禁止）； -
令牌压缩：过滤冗余人类注释、排版空行，优化 Token 占用，防止上下文溢出；
-
分层存储：拆分为两类数据：
- 静态元数据（项目架构、目录、技术栈）；
- 动态行为规则（工具调用、代码输出、任务流程）。
第 3 层：提示词注入层 ------ 拼接进 LLM 系统上下文（核心驱动环节）
Trae 采用前置系统 Prompt 注入机制，每一轮 LLM 调用都会携带 agents.md 规则，分三段拼接顺序：
plaintext
css
[Trae底层内置基础Agent系统提示词]
+
[合并后的AGENTS.md全部规则（项目宪法）]
+
[用户当前会话历史+本次用户提问+仓库代码上下文]两种注入模式
- **单 Agent 模式（Solo Agent）**AGENTS.md 作为全局约束，全程管控代码生成、文件编辑、命令执行、输出格式；
- **多智能体编排模式（Orchestrator 路由架构）**AGENTS.md 中定义
@specialist路由表（前端 / 后端 / 测试 / 安全），协调 Agent 读取路由规则，自动分派子 Agent 执行细分任务，子 Agent 会同步继承 AGENTS.md 约束。
关键机制：LLM 每一次思考、工具调用、代码输出都会先匹配 AGENTS.md 约束，规则属于硬提示约束，模型遵从优先级高于用户普通提问。
第 4 层：决策编排层 ------ 用 agents.md 规则重塑任务规划逻辑
Trae 新版移除固定前置 Plan 阶段，采用动态迭代决策，agents.md 全程干预每一步判断：
- 需求理解阶段：读取 AGENTS.md 的项目架构描述，自动定位对应模块代码，不会跨目录乱修改；
- 任务拆解阶段：遵循文件内定义的标准工作流，强制插入校验步骤（例如：修改代码后必须执行单元测试）；
- 工具选择阶段：依据权限约束块，过滤禁止使用的工具（如禁止 rm -rf、禁止外网搜索）；
- 输出约束阶段：强制对齐命名、注释、文件结构规范，不产出不符合项目风格代码。
示例链路：用户「新增用户接口」
- 读取 AGENTS.md：后端接口统一放在
src/api/v1，使用 Pydantic 校验，写完必须执行pytest api； - Agent 自动规划：创建路由文件→编写 Schema→实现接口→运行测试→输出测试日志；
- 跳过不符合规范的步骤（不会直接写根目录文件、不会省略测试）。
第 5 层：工具执行层 ------agents.md 管控 Tool 调用行为
Trae 工具执行器ToolExecutor在调用任何工具前，读取 AGENTS.md 权限规则做拦截校验：
- 文件操作：限制读写目录黑名单、禁止修改配置文件；
- Shell 命令：仅允许文件内指定的构建 / 测试脚本，拦截高危系统命令；
- MCP 外部服务：仅启用 AGENTS.md 允许的第三方 API；
- 修改后置校验：文件修改完成后，自动执行 AGENTS.md 指定的校验脚本（lint、格式化、测试），校验失败自动进入修复循环。
第 6 层：反馈闭环层 ------ 基于 agents.md 验收交付标准
任务接近完成时，Agent 会复用 AGENTS.md 交付规则做自检：
- 比对所有修改是否符合编码规范；
- 检查是否遗漏强制测试、文档更新；
- 校验 git 变更是否符合提交格式；
- 不满足标准则自动迭代修复，直至匹配 AGENTS.md 全部约束后，才输出
task_done结束任务。
第 7 层：会话生命周期管理 ------ 缓存、更新、重载机制
- 实时热重载：用户修改本地
AGENTS.md文件，Trae 文件监听进程自动重新读取、重新注入下一轮 LLM 请求； - 会话隔离：不同仓库会话独立缓存各自 AGENTS.md，互不干扰；
- Token 节流：超长 AGENTS.md 自动做摘要压缩，保留核心强制规则，避免上下文超限；
- 轨迹记录：
TrajectoryRecorder记录每一轮遵循 / 违反 AGENTS.md 的行为，用于调试 Agent 行为。
三、多智能体场景下 agents.md 特殊工作逻辑
Trae 是原生多 Agent 架构，AGENTS.md 承担智能体调度中心角色：
- 根目录 AGENTS.md 定义中央协调 Agent（Orchestrator）的路由表；
- 协调 Agent 启动时先完整读取 AGENTS.md 路由规则；
- 根据用户任务分类，自动唤醒对应专业子 Agent（Debugger/DevOps/Frontend）；
- 所有子 Agent 执行时，继承全部 AGENTS.md 项目约束；
- 子目录 AGENTS.md 可局部改写路由规则，实现分包专属智能体逻辑；
- 支持引用
.trae/agents/*.md拆分专项 Agent 配置，主 AGENTS.md 做统一调度入口。
四、底层核心技术原理总结（Harness Engineering 工程范式）
Trae 读取 agents.md 本质是给大模型加装标准化工程约束外壳（Harness） ，解决 LLM 无项目认知、输出不可控问题：
- 记忆层：AGENTS.md 作为项目长期静态记忆，替代零散 README 人工阅读；
- 执行层：规则约束工具调用边界，把纯文本模型转化为可安全操作系统的执行体；
- 反馈层：内置校验流程形成自动化闭环，减少人工审核；
- 编排层：标准化任务流程，统一单 / 多 Agent 执行范式。
五、与普通 prompt 的本质区别
表格
| 维度 | 普通临时 Prompt | AGENTS.md 项目文件 |
|---|---|---|
| 生效范围 | 单次对话 | 全仓库永久，会话自动加载 |
| 执行强度 | 软性建议，模型容易忽略 | 硬性系统前置约束，优先级最高 |
| 结构化 | 自由文本，无机器解析逻辑 | 标准 Markdown 分块，本地预解析 |
| 多 Agent 适配 | 不支持调度路由 | 原生定义多智能体分工、分派规则 |
| 跨工具兼容 | 仅 Trae 私有 | AAIF 行业标准，Cursor/Claude Code 通用 |
| 自动加载 | 每次手动粘贴 | 任务触发自动扫描、缓存、热重载 |