本页判断标准

换一台电脑、重装 TraeCode、只把仓库拉下来,助手能不能按组里的约定动手?

答「不能」,缺的是两样东西之一:六个位置里少放了文件,或者「设置 → 规则 → 导入设置」的开关没开。先数位置,再查开关。

六类文件与落地顺序

顺序不能反:先让助手读到约定,再谈约束它怎么动手。前两步没做完,后面四步写了也不生效。

第一步 · 打开 AGENTS.md 的导入开关在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」。这样自检:开一轮新对话,问助手「本仓库的隔离边界是什么」。它答不出根文件里那句话,就是开关没开,或文件没放在项目根。
第二步 · 写根目录的 AGENTS.md把它控制在 100 到 200 行,只写「不写会做错」的句子。写法见AGENTS.md。
第三步 · 只对某类文件生效的约定放进 .trae/rules/*.md写 alwaysApply: false 配 globs:,改完开一轮新对话再试。见规则。
第四步 · 已经固定的多步流程写成 .trae/commands/*.md文件名就是调用名。在对话里输入 /,从 Commands 里选。见命令。
第五步 · 可复用的做法写成 .trae/skills/<名称>/SKILL.md在 description 里写清做什么、在什么任务里用。见技能。
第六步 · 验收这类独立角色写成 .trae/agents/*.md用 tools 白名单加 disallowedTools 收窄权限,再用 .trae/hooks.json 挡住硬规则。见子智能体与钩子。

演示仓里已有的 OpenSpec 命令是另一套流程,不冲突,但不要混进这六个位置。下面所有例子都用一个按登录用户隔离数据的 Web 服务。

七处位置:三工具对照

同一件事在三套工具里落在不同文件名、不同目录。转工具时最先出问题的就是这几处:位置放对了、名字不对,等于没放。

这一类约定Claude CodeCursorTraeCode最容易混的点
仓库说明CLAUDE.md;.claude/CLAUDE.md 也会读AGENTS.mdAGENTS.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 没有独立的个人约定目录

还差一个大小写:钩子事件名 Cursor 写 preToolUse,Claude Code 与 TraeCode 写 PreToolUse。写错不会报错,只是不触发。各家细节见钩子与规则。

一份可抄的目录结构

下面这棵树就是本组六个页面的落点。点进任意一项,都能看到完整文件。

AGENTS.md

它默认不读取。先在「设置 → 规则 → 导入设置」打开「将 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,助手照样读 .envTraeCode 没有 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/ 为准。见技能
对应知识点 这一组是 上下文与能力 在 TraeCode 里的落地写法。先看完上下文分层与预算,知道约定该放哪三层;本组六页按顺序做完,再接验证与门禁。