Trae 读取 agents.md 并驱动 AI 完整底层原理一、基础定义：什么是 agents.md（AGENTS.m

agents.md

基础模版

# AGENTS.md - 开发规范与技能定义

## 一、项目概述

### 1. 项目定位

说明本项目业务领域、技术栈、交付目标、参与角色（前端 / 后端 / 测试 / 产品 / AI 开发 Agent），明确 AI Agent 在项目中的职责边界：需求拆解、代码开发、文档编写、自测校验、变更交付全流程辅助。

### 2. Agent 核心能力约束

1.  所有操作必须遵循本文件全部规范，规范优先级高于临时对话指令；
1.  涉及目录、分层、命名、文档、代码修改强制条款不可省略；
1.  复杂目录规则、分层细则可引用外部文档（如 Dir.md），Agent 需自动读取关联文件并遵循。

### 3. 生效范围

本文件为项目根级全局规范，全仓库所有目录、所有开发任务统一生效；子目录可新建独立 AGENTS.md 覆盖局部规则，就近规则优先级更高。

## 二、项目结构规范

### 目录组织说明（详见 Dir.md 文件）

1.  Agent 执行任何文件读写、新增、删除前，必须读取 `Dir.md` 目录规范，严格遵循模块分层、业务分包、公共资源存放规则；
1.  禁止随意新建顶层目录、跨模块存放业务代码、混淆配置 / 业务 / 测试 / 文档目录；
1.  新增文件 / 文件夹前先匹配 Dir.md 定义，无对应分类时先补充目录规范文档再创建；
1.  资源、静态文件、配置、脚本、测试用例、文档有专属固定目录，不得混放业务逻辑代码。

### 文件命名

1.  业务代码文件统一使用项目约定命名风格（下划线 / 小驼峰 / 大驼峰，按技术栈区分）；
1.  文档、配置、脚本、测试文件区分专属命名前缀 / 后缀；
1.  禁止无意义随机命名、拼音简写、大小写混用；
1.  模块内同名功能文件按分层后缀区分（如 `user.controller.ts`、`user.service.ts`）；
1.  新增文件命名必须先匹配目录规范内的命名模板。

## 三、通用准则

### 署名要求

1.  所有新建代码文件、设计文档、需求文档顶部必须添加标准头部署名注释；
1.  署名包含：创建人、创建时间、关联需求 ID、模块归属；
1.  多人迭代修改时，在文件末尾追加修改记录（修改人、时间、变更内容）；
1.  AI 自动生成的文件必须标注 Agent 生成标识，区分人工手写代码。

### 工作执行顺序

所有开发任务强制遵循固定流程，不可跳步执行：

1.  读取需求文档 → 2. 需求拆解校验 → 3. 查阅架构 & 目录规范 → 4. 输出简易设计文档 → 5. 代码分层开发 → 6. 单元 / 集成自测 → 7. 文档同步更新 → 8. 变更自检合规性 → 9. 交付变更说明任意步骤未完成禁止进入下一阶段，自检不通过必须修复后再推进。

### 需求关联分解要求

1.  所有开发任务必须绑定唯一需求 ID，无需求 ID 不允许开发；
1.  拆解需求时拆分至最小可交付子任务，每个子任务对应单一功能点；
1.  区分新增、迭代、修复、优化四类需求，分别对应不同开发流程；
1.  拆解后输出任务清单，标注依赖关系、前置条件、验收标准；
1.  需求存在模糊、缺失、冲突点时，暂停开发并主动提出疑问，澄清后再拆解。

### 需求文档要求

1.  需求文档固定模板：业务背景、用户场景、功能流程、输入输出、边界异常、验收用例；
1.  Agent 生成 / 修改需求文档必须补全缺失模块，不允许只写功能描述；
1.  接口需求附带完整入参、出参、状态码、错误返回示例；
1.  数据变更类需求必须补充数据兼容、回滚方案；
1.  文档修改后同步更新版本号与修改记录。

### 设计文档要求

1.  分层设计文档必备内容：模块职责、依赖关系、数据模型、接口清单、时序流程图；
1.  数据库相关需求必须输出表结构、索引、关联关系、数据迁移脚本；
1.  复杂逻辑补充流程图、伪代码说明；
1.  设计方案需符合架构分层规范，禁止出现跨层直接调用、职责混淆设计；
1.  设计存在性能、安全风险时，必须同步给出优化、规避方案。

### 开发任务分解要求

1.  单需求拆分为多个最小开发单元，每个单元不超过单次可提交变更范围；
1.  区分接口层、业务层、数据层、前端页面、工具类、测试代码独立任务；
1.  标注每个子任务的前置依赖、关联文件、修改范围；
1.  同步配套任务：文档更新、自测用例、配置修改、脚本调整；
1.  输出任务优先级，优先完成核心流程、主链路功能。

### 代码修改要求

1.  修改前先读取目标文件全量上下文，理解原有逻辑再变更，禁止盲目覆盖；
1.  遵循最小变更原则，不改动无关业务代码；
1.  新增逻辑与原有代码风格统一（注释、变量命名、异常处理）；
1.  分支、git 提交信息遵循统一提交规范，绑定需求 ID；
1.  删除废弃代码不可直接移除，先注释标注废弃原因与时间，确认无依赖后再清理；
1.  修改完成必须执行项目内置 lint、格式化、单元测试命令。

### 技术规范

1.  统一遵循项目技术栈官方编码规范，强类型校验、参数校验、异常捕获强制落地；
1.  第三方组件、工具版本固定，不随意升级 / 引入新依赖；
1.  日志打印、错误码、返回体统一全局封装，禁止自定义零散格式；
1.  安全规范：参数防注入、权限校验、敏感数据脱敏、接口鉴权必须全覆盖；
1.  性能约束：大循环、批量查询、分页、缓存使用遵循统一标准；
1.  公共通用逻辑抽离至工具 / 公共模块，禁止重复拷贝代码。

## 四、架构设计规范

### 分层架构

1.  严格遵循项目定义分层（如 Controller → Service → Repository / Model），层级单向依赖，禁止反向、跨层直调；

1.  每层固定职责边界：

    -   控制层：接收参数、鉴权、参数校验、响应封装；
    -   业务层：核心流程、事务、业务规则、多数据组装；
    -   数据层：数据库 CRUD、缓存读写、第三方接口调用；

1.  跨模块调用统一通过公共接口 / 服务，禁止直接导入其他模块内部实体；

1.  数据流转实体分层隔离（入参 DTO、业务 VO、数据库 Entity），不混用对象；

1.  复杂业务拆分领域子模块，单一模块只负责一类业务域。

### 核心原则

1.  单一职责：一个类 / 函数 / 接口只实现一类能力；
1.  开闭原则：扩展功能新增代码，不修改原有稳定逻辑；
1.  可测试性：业务逻辑解耦，支持单元测试，不硬编码依赖；
1.  兼容性：迭代变更兼容历史数据、旧接口，避免破坏性修改；
1.  可观测：关键流程埋日志、异常全捕获，便于问题排查；
1.  轻量化：避免过度设计，小型功能不新增复杂抽象分层。

一、基础定义：什么是 agents.md（AGENTS.md）

AGENTS.md 是 AAIF（Agentic AI Foundation）推出的跨 IDE 标准化 AI 智能体指令文件，专门写给 AI 而非人类 README，Trae 原生深度集成，作为项目级 AI 行为宪法。

核心定位

区分全局 / 项目规则
- 全局规则：Trae 客户端设置内，全项目永久生效；
- AGENTS.md：项目级规则，仅当前仓库生效，子目录可放局部 AGENTS.md 覆盖局部逻辑。
与同类文件优先级（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

[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 通用
自动加载	每次手动粘贴	任务触发自动扫描、缓存、热重载

六、完整最简时序示例（用户需求→agents.md→AI 执行）

用户输入：给用户模块新增分页查询接口；
Trae 会话启动，检索并合并仓库各级AGENTS.md；
本地 MD 解析，提取后端目录规范、测试命令、路由 Agent 规则；
拼接进 LLM 系统提示词，发送大模型；
LLM 依据规则判定属于后端任务，触发 @backend-specialist；
后端 Agent 遵循目录约束创建接口文件；
执行 AGENTS.md 指定 pytest 校验；
校验通过，按规范输出代码变更与测试日志；
会话缓存 AGENTS.md，后续同仓库任务无需重读磁盘。