AGENTS.md
它默认不读取。先在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」。
进入在 TraeCode 里配约定,就是往六个固定位置放文件:仓库说明 AGENTS.md(项目根)、规则 .trae/rules/*.md、命令 .trae/commands/*.md、技能 .trae/skills/<名称>/SKILL.md、子智能体 .trae/agents/*.md、钩子 .trae/hooks.json。个人级的同名目录在 ~/.trae-cn/ 下;小组共用的约定一律放项目里的 .trae/——只放在自己电脑上,换一个同学就全丢了。
有三种情况会打开这一页:刚接手项目,要把这六个位置第一次配齐 → 从「六类文件与落地顺序」的第一步往下做;配好了却不生效 → 直接对「没生效时的现象与修法」那张表;从 Cursor 或 Claude Code 转过来,想知道文件名与目录换成什么 → 看「七处位置:三工具对照」。
写错最多的是两处,先记住它们。一,AGENTS.md 默认不读。文件放进根目录还不够,要先去「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」;这一步没做,根文件里的数据范围和密钥约定一条都不生效。二,钩子里的工具名不是 Bash。TraeCode 里是 RunCommand / Read / Write / Edit,matcher 按正则匹配,名字写错不报错,只是永远不触发。
换一台电脑、重装 TraeCode、只把仓库拉下来,助手能不能按组里的约定动手?
答「不能」,缺的是两样东西之一:六个位置里少放了文件,或者「设置 → 规则 → 导入设置」的开关没开。先数位置,再查开关。
顺序不能反:先让助手读到约定,再谈约束它怎么动手。前两步没做完,后面四步写了也不生效。
AGENTS.md 的导入开关在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」。这样自检:开一轮新对话,问助手「本仓库的隔离边界是什么」。它答不出根文件里那句话,就是开关没开,或文件没放在项目根。AGENTS.md把它控制在 100 到 200 行,只写「不写会做错」的句子。写法见AGENTS.md。演示仓里已有的 OpenSpec 命令是另一套流程,不冲突,但不要混进这六个位置。下面所有例子都用一个按登录用户隔离数据的 Web 服务。
同一件事在三套工具里落在不同文件名、不同目录。转工具时最先出问题的就是这几处:位置放对了、名字不对,等于没放。
| 这一类约定 | Claude Code | Cursor | TraeCode | 最容易混的点 |
|---|---|---|---|---|
| 仓库说明 | CLAUDE.md;.claude/CLAUDE.md 也会读 | AGENTS.md | AGENTS.md,默认不读,需在「设置 → 规则 → 导入设置」打开开关 | 后两家文件名相同,但 TraeCode 要手动开开关才读 |
| 规则目录 | .claude/rules/,可再分 backend/、frontend/ | .cursor/rules/*.mdc | .trae/rules/*.md | 扩展名不同:.mdc 与 .md |
| 命令 | 写成技能 .claude/skills/<名称>/SKILL.md 并加 disable-model-invocation: true | 写成技能 .cursor/skills/<名称>/SKILL.md 并加 disable-model-invocation: true | .trae/commands/<名称>.md,文件名即调用名 | 另两家把命令并进技能,TraeCode 是独立目录 |
| 技能目录 | .claude/skills/<名称>/SKILL.md | .cursor/skills/<名称>/SKILL.md | .trae/skills/<名称>/SKILL.md | 三家的文件名一样,只有根目录不同 |
| 子智能体目录 | .claude/agents/*.md | .cursor/agents/*.md | .trae/agents/*.md | 收权限的写法不同:tools 白名单 / readonly: true / tools 加 disallowedTools |
| 钩子配置文件 | .claude/settings.json 的 hooks 字段(不是 hooks.json) | .cursor/hooks.json | .trae/hooks.json | 只有 Claude Code 把钩子塞进 settings.json |
| 个人级目录 | ~/.claude/ | —— | ~/.trae-cn/ | Cursor 没有独立的个人约定目录 |
下面这棵树就是本组六个页面的落点。点进任意一项,都能看到完整文件。
它默认不读取。先在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」。
进入把项目规则放 .trae/rules/。只对某类文件生效时,写 globs,并把 alwaysApply 设为 false。
放在 .trae/commands/,对话里用 / 调用。步骤还没固定,就先不要建。
放在 .trae/skills/<名称>/SKILL.md。description 里写清什么任务、什么时候用。
放在 .trae/agents/。它适合单独上下文的角色。硬约束不要只写在这里。
项目配置是 .trae/hooks.json。在工具执行前用 PreToolUse 拒绝读密钥、提交 .env。
把整棵树提交进仓库;.env 不进,写进 .gitignore。
my-course/
├── AGENTS.md 项目根;先在「设置 → 规则 → 导入设置」打开开关
├── .gitignore 含 .env
└── .trae/
├── rules/
│ ├── backend.md globs: backend/**/*.go
│ └── frontend.md globs: frontend/src/**/*.ts,frontend/src/**/*.tsx
├── commands/
│ └── check-scope.md 调用名 = 文件名 = check-scope
├── skills/
│ └── trace-retrieval/
│ └── SKILL.md
├── agents/
│ └── verifier.md 只读验收
├── hooks/
│ └── block-env.py 被 hooks.json 调用
└── hooks.json 钩子配置,version 为 1
这四条占了「配了但没用」的绝大多数。看到现象先对号,不用逐项排查。
| 现象 | 原因 | 修法 |
|---|---|---|
根文件写明「SQL 必须写成 WHERE scope_id = ?」,助手仍写出不带条件的查询 | AGENTS.md 默认不读,导入开关没打开 | 在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」,开一轮新对话,问它隔离边界来确认 |
钩子脚本里写了 deny,助手照样读 .env | TraeCode 没有 failClosed 字段,脚本一崩溃、一超时就被当成放行 | 把解析与文件名判断包进 try/except,异常分支也输出 deny JSON 后 exit 0;timeout 写 30(秒),脚本里不做网络请求。见钩子 |
钩子写好了,助手读 .env 时它一次都没触发 | matcher 是正则、匹配工具名;写成 Bash 不会报错,只是不触发 | 改成 "matcher": "RunCommand|Read|Write|Edit",再用一次「让助手读 .env」的对照实验确认被拦 |
| 技能改了一份,对话里用的还是旧的 | 同名技能同时存在于 .trae/skills/ 与 .agents/skills/,.agents 的导入开关状态与预期相反 | 只在 .trae/skills/ 放技能;两者重名时以 .trae/skills/ 为准。见技能 |