AGENTS.md

TraeCode 的仓库说明固定叫 AGENTS.md。把它放在项目根目录，本课只用这一份。它默认不读：要先在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」，开关打开后智能体才会把这份根文件加进上下文。子目录里的同名文件在本课不参与叠加；只对后端或前端才成立的句子，放到规则里用 globs 限定。

有三种情况会打开这一页：文件写好了，助手却当它不存在 → 从「先开开关，再写文件」的三步走一遍；想往根文件里加一条，拿不准该不该加 → 先过「哪些句子值得写进来」的三问；根文件写到两三百行、助手开始漏后面的句子 → 看「没生效时的现象与修法」的最后一行。

写错最多的是两件事，先记住。一是不开开关就埋头写文件，写了大半天一条也不生效——自检方法在下面第一步里。二是把根文件当 README 写，塞进框架教程、完整目录树和语言风格；篇幅过两百行之后，真正要遵守的句子反而被漏掉。

本页判断标准

开一轮新对话，问助手「本仓库的隔离边界是什么」，它能不能答出根文件里那句话？

答「不能」，先查「设置 → 规则 → 导入设置」里的开关，再确认 AGENTS.md 在项目根。这两样没对上，后面写多少行都不生效。

先开开关，再写文件

TraeCode 不会自动读根目录的 AGENTS.md。漏掉第一步，后面两步全部作废。

第一步 · 打开导入开关打开「设置 → 规则 → 导入设置」→「将 AGENTS.md 包含在上下文中」。同一处还有「将 CLAUDE.md 包含在上下文中」，那是给从 Claude Code 迁移过来的项目用的，本课不开。
第二步 · 把文件放到项目根目录路径就是 AGENTS.md，不要放进 .trae/。放错位置的表现和没开开关一样：约定不生效。
第三步 · 开一轮新对话自检问助手「本仓库的隔离边界是什么」。它答出根文件里的那句话，说明已读入；答不出或答得含糊，回到第一步，并确认文件确实在根目录。

开关跟着设置走，换一台电脑、换一个同学都要重开一次。所以「文件进仓库」和「开关打开」是两件事，把后者写进小组的开工清单。

仓库说明在三个工具里的差别

文件名、读取时机、叠加方式三家都不一样。转工具时最容易出问题的是「何时读」这一行：另两家会自动读，TraeCode 要手动开开关。

项Claude CodeCursorTraeCode
文件名CLAUDE.md（.claude/CLAUDE.md 也会读）AGENTS.mdAGENTS.md
何时读每次会话读项目根每次对话读仓库根默认不读；要在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」
叠加规则沿工作目录向上找到的同名文件全部叠进上下文，靠近启动目录的排在后面；是拼接不是覆盖从仓库根到当前文件，沿途每份都叠加；冲突时以更近的那份为准本课只用根目录一份，子目录同名文件不自动叠加
子目录文件读到该目录的文件时才加载改到该目录时额外生效——
复用已有文件根目录写 @AGENTS.md 引进来————
个人文件CLAUDE.local.md，放 .gitignore————
篇幅参考官方建议 200 行以内100–200 行100–200 行
查看实际加载对话里 /memory 列出本次加载的文件————

TraeCode 没有 /memory 这样的命令来列出已加载文件，所以只能靠提问自检。这一点在AGENTS.md里也提到过。

哪些句子值得写进来

三条都要答「是」才写。有一条答「否」，这句话就不进根文件。

1. 不写这句话，助手会在这个仓库里做错吗？ 只为已经发生或必然发生的错误加一条。没有对应的错误场景，就不要写。
2. 这句话能判断对错吗？ 「SQL 必须写成 WHERE scope_id = ?」可以核对。「注意数据安全」核对不了。判不出对错的句子，删掉。
3. 代码、lint 或已有文档里是不是已经有了？ 格式化工具能管的空格与引号，不要写；README 写过的能力，不要抄。根文件写过的句子，.trae/rules/ 里不要再写一遍。
根文件篇幅
100–200 行
超过 200 行，先删「语言风格」与「要做什么」两类句子，把细节移到 .trae/rules/。
可以这么做 写「SQL 必须写成 WHERE scope_id = ?」「.env 不提交」「没有命中时回答「无依据」」——这几句都能逐条核对。
不要这么做 写「注意代码质量」「遵循团队规范」「保持风格一致」——这些话判不出对错，只会白占上下文。

示例根文件与它的守卫

下面这份用一个按登录用户隔离数据的 Web 服务作示例。抄走之后只保留已经能复制执行的启动步骤；还没有固定下来的测试命令就空着，并写明「不要编造参数」。

AGENTS.md

放在项目根。先打开导入开关，这份才会生效。

# AGENTS.md

这是一个按登录用户隔离数据的 Web 服务。隔离边界是用户所属范围。
本文件约 120 行；超过 150 行时先删「语言风格」类句子，细节移到 .trae/rules/。

## 当前阶段

只做 README 里已经写明的能力。README 标成不做的，不要顺手加。
产品里给最终用户使用的功能，不是本仓库的技能文件。
不做：家长端、多校区运营、学科交易市场。

## 数据范围

业务数据带 scope_id。
SQL 必须写成 `WHERE scope_id = ?`，问号绑定会话中的 scope_id。
用户不能读到其他范围的数据。
检索没有命中时，回答「无依据」，不要编造句子，也不要为此调用对话模型。
新增查询前先确认：其他范围读不到，且与记录不存在无法从响应区分。

## 密钥

会话密钥、数据库口令和第三方 API 密钥只放在 .env。
.env 不提交。.env.example 里只能是占位符。
密钥不写进日志、异常信息或前端包。

## 启动

cp .env.example .env
docker compose up --build -d

## 测试

还没有可以复制执行的测试命令。不要编造 go test 或 npm 的参数。
命令固定下来之后，把「怎么跑」补到这里，并写清跑之前要做什么。

## 提交

提交信息用「类型: 一句话」，类型从 feat、fix、docs、refactor、test、chore 里选。
不提交生成物和 .env。

## 不要做的事

不要为了通过检查而删断言、跳过用例或上调阈值——那要单开一个合并请求。
不要把本文件里已有的句子再抄进 .trae/rules/。

CODEOWNERS（保护 AGENTS.md 本身）

根文件决定助手的行为，每次改动都要留一个签名。第一列是路径，第二列是必须签字的人或组。

# 指令类文件：改动必须由指定的人看过
/AGENTS.md            @项目负责人
/.trae/rules/         @项目负责人
/.trae/hooks.json     @项目负责人

仓库说明没被读到的四种现象

看到现象先对号，不用逐项排查。前两条占了「写了却没生效」的多数。

现象原因修法
根文件里写了数据范围，助手仍然写出不带 scope_id 条件的查询AGENTS.md 默认不读，导入开关没打开在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」，开一轮新对话，问它隔离边界来确认
把文件放进了 .trae/AGENTS.md，表现和没开开关一样位置不对：TraeCode 读的是项目根目录的那一份把它移到项目根，路径就是 AGENTS.md；再开新对话自检一次
只在改后端时才该遵守的句子写进了根文件，改前端时也一起进上下文根文件每次会话全量进上下文，没有按文件范围生效的能力把它移到 .trae/rules/backend.md，用 alwaysApply: false 配 globs: backend/**/*.go。见规则
根文件写到三百行，助手开始漏掉「密钥」那一段根文件越长，靠后的句子越容易被忽略压到 200 行以内；超出的按文件范围拆进 .trae/rules/，或移到 README
对应知识点 这一页是 仓库说明 在 TraeCode 里的落地写法。上游是AGENTS.md与上下文分层与预算，先知道该放哪三层；下游是规则（按文件范围的拆分）和验证与门禁。