agents.md

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

主要定位

1. 区分全局 / 项目规则
   • 说到全局规则。Trae 客户端设置内，全项目永久生效；
   • AGENTS.md项目级规则。仅当前仓库生效，子目录可放局部 AGENTS.md 覆盖局部逻辑。
2. 优先级顺序
   1. 子目录 AGENTS.md
   2. 项目根 AGENTS.md
   3. CLAUDE.md
   4. Trae 客户端全局规则
   5. NNM 内置程序提示词。
3. 包含信息：
4. 技术栈、目录结构、架构约束；
5. 编码规范、注释、文件命名、导入规则；
6. 从工作流指令来看，启动 / 测试 / 建立 / 校验命令、提交规范；
7. 多智能体路由规则：定义协调 Agent 如何分派前端/后端/测试/运维专项 Agent；怎么说呢，
8. 执行校验规则的观点是。修改后必须运行 lint、单元测试、静态检查；工具权限约束：限制 bash 读写、文件删除、网络调用范围。

使用者痛点一览

• 文档太长难读：.md,容易忽略细节。

基础模版 & 工作流程概览

🔍 在整个项目中。所有开发任务都遵循同一套固定流程，以避免遗漏与冲突。下面按层级拆解实现细节：

一、项目概述

1. '需求拆解' :每个需求绑定唯一 ID，并拆分成最小可交付子任务；
2. '角色定义' :前端/后端/测试/产品/AI 开发 Agent，各自职责边界明确。
3. 'Agent 主要能力' :所有操作必须遵循 AGENTS.md 中全部规范，并优先于临时对话指令。包括目录结构、分层命名与文档修改等强制条款。当涉及复杂目录规则时可引用外部文档如 Dir.md 并自动读取遵循。
4. '生效范围' :此文件为根级全局规范，覆盖整个仓库；子目录可新建独立 AGENTS.md 覆盖局部规则，近者优先。

二、文件命名与目录结构

• '模块层次' :严格遵循 Dir.md 所述模块分层和业务包划分，不随意创建顶层目录或跨模块存放业务代码。
• '资源隔离' :资源、静态文件、配置脚本等拥有专属固定目录，不得与业务逻辑代码混放。• 当新增文件或文件夹前，需要匹配 Dir.md 定义。如无对应分类则先补充相关规范再创建。• 同一模块内同名功能文件须按后缀区分，例如 `user.controller.ts` vs `user.service.ts`。

   • 禁止无意义随机命名、不规范拼音简写还有大小写混用。 ， **示例**
  

  `src/api/v1/user.controller.ts` → `src/api/v1/user.service.ts`**

三、编码约束

• MUST 必须遵守：SUGGEST 建议做法：NORMAL 不做任何事儿:

---

四、详细工作执行顺序

步骤列表

1. 读取需求文档 → 获取最新需求描述及 ID。
2. 拆解校验 → 将需求拆分为最小子任务并验证完整性。
3. 查阅架构 & 目录规范 → 确认目标位置与模块符合 Dir.md。
4. 输出简易设计文档 → 用 Markdown 或 PlantUML 自动生成基本框架。
5. 代码分层开发 → 按 Controller–Service–Repository 层次实现功能。
6. 单元 / 集成自测 → npm test | pytest | go test 等自动执行。
7. 文档同步更新 → 更新 API 文档及使用说明。
8. 变更自检合规性 → Lint + 格式化 + Git 提交格式检查。
9. 交付变更说明 → 完整提交记录和 changelog。

如果任一步骤未完成，则阻止进入下一阶段。

---

---

五、需求关联与拆解要求

• 每个开发任务必须绑定唯一需求 ID，否则不允许开始开发；• 拆解后形成任务清单，标注依赖关系和验收标准；
• 若发现模糊或冲突点，应暂停并主动提出疑问直到澄清；• 按“新增”“迭代”“修复”“调整”四类区分对应流程，并在设计文档中注明。

---

六、文档编写要求

• ID 必填:'业务背景': 明确目标受众和业务场景；话说回来，• '功能流程': 描述步骤顺序及边界条件；• '输入输出': 包含数据模型及返回码表格；其实，• '异常边界': 列举潜在错误场景和处理方式；• '验收用例': 给出正面与负面案例，用来驱动测试脚本生成。

---

七、设计文档要求

* 模块职责 – 描述每层接口作用
* 数据模型 – ER 图或 JSON Schema
* 接口清单 – 参数类型及校验逻辑
* 时序流程图 – 用 PlantUML 展示关键业务流
* 性能考量 – 缓存策略与分页方案
* 安全风险评估 – 注入防护与鉴权机制
若存在性能瓶颈或安全隐患，还需提供调整方法并附上成本评估表格。

---

八、多智能体任务拆解

  * 分析请求类型后将其路由至相应子 Agent;* 每个子 Agent 均继承 AGENTS.md 全部约束，从代码风格到权限校验一律遵守;* 子 Agent 的任务可进一步细化为接口层/业务层/数据层/工具类等独立小单元，以便快速提交并合并回主干;* 所有子 Agent 必须在完成后向 Orchestrator 汇报状态，并自动触发必要的 lint 与测试环节。其实，

---

九、底层关键技术原理

TREA 的实现基于四大主要理念。将 AGENTS.md 建立成 “工程 Harness”，让 LLM 在项目中安全、高效地工作。

# 序号 # - # 名称 # - # 描述 # - # 示例 # - # 工具链 # - # 文本长度限制
#01# 记忆层 持续保存 AGENTS. 把 README 拆散成可查询索引，以降低上下文负担。📍 ： Markdown Parser + Vector Store 📍 ： 快速检索所需配置，提高推理速度。其实，🟢 ✅ 可 到多语言支持。	#02# 执行层 把文本转换为可安全执行的动作。\t\t\t\t\t\t\t \t\r \t\t\t\t\t\t\t\t\t\t\t \t \r 🔧 👇🏻 本地工具链 ➤ 跨语言 SDK ➤ 云服务 API ➤ 第三方服务 🛠️ 🔗 🛡️ 📦🗝️ 🧩🛠️ 🎯 🤖 ➕ 🚨 \u200c🟩 \u200c🟦 \u200c⚪ \u200c⚫\r \u200c\u200c\u200c\u200c\u201C 🔁 🚀🚨⛑️ 🧬🤖 💻💾✂️💻💾✂️💻 💬⏱💲🔒🤐⚙🔐🛡⣥!\r 📦➡👀😎👍🏽🏅🥇🚚🌎🐝🐞📈👭➗👴🇨🇭❝{?，}?，?，?❞✉↔︎..\\r�，?，?，?，?，?，?，\r?\r，\r?...，?，?，?，?，?，?，?，?，?，?，?，?.. " . "\u000d" "\u000d" "\u000d" "\u000d" "\u000d");echo，echo;echo，echo;echo，

 ​

​

---

---

---