AGENTS.md
每次对话都会读。只写删掉就会让智能体做错、又能核对、代码里还没有的事实。
进入同组两人改同一处代码，得到的结果不一致时，能指出差异来自 .cursor/ 下的哪一个文件吗？
指不出，说明约定还在聊天记录里，没进仓库。要补的是一个具体文件，不是在群里再讲一遍。
六页按同一个顺序，每页产出一个放进 .cursor/ 的文件。
每次对话都会读。只写删掉就会让智能体做错、又能核对、代码里还没有的事实。
进入只在某一类文件里才需要。用 .cursor/rules/*.mdc 的 globs 限定范围，别设成始终生效。
用斜杠主动调用。步骤已经固定、能照着做；流程还没定下来就先空着这一页。
进入任务一出现，智能体就该自己想起的做法。在 description 里写清什么任务、什么时候用。
需要单独上下文的角色，例如只读验收。数据范围仍要写进 AGENTS.md。
智能体即将做危险动作时，用脚本直接拦住。密钥和 .env 适合放在这一层。
| 位置 | 放什么 | 什么时候生效 |
|---|---|---|
AGENTS.md | 全仓库都要遵守的事实：数据范围、密钥、启动命令 | 每次对话自动读仓库根那一份 |
.cursor/rules/*.mdc | 只在某一类文件里才需要遵守的句子 | 改到 globs 匹配的文件时 |
.cursor/skills/<名称>/SKILL.md | 任务一出现就该用的步骤；人点名的命令也写这里 | 助手按 description 自动用，或人输入 /名称 |
.cursor/commands/*.md | 旧的斜杠命令写法，仍能加载 | 人输入 /名称 |
.cursor/agents/*.md | 需要独立上下文的角色，例如只读验收 | 父智能体按 description 委派时 |
.cursor/hooks.json | 必须被脚本拦住的危险动作 | 对应事件触发前或触发后 |
.cursor/hooks/<脚本> | 判断逻辑，从仓库根执行 | 由 hooks.json 里的 command 调起 |
同一件事，三个工具的文件名和字段名不一样。改仓库前先在这张表上找到对应的一行，确认 Cursor 这一列怎么写，再去那一页看完整写法——照抄另一个工具，结果是静默不生效。
| 位置 | Claude Code | Cursor | TraeCode |
|---|---|---|---|
| 仓库说明 | CLAUDE.md（.claude/CLAUDE.md 也会读） | AGENTS.md | AGENTS.md，默认不读，要在「设置 → 规则 → 导入设置」打开 |
| 规则 | .claude/rules/，前置元数据用 paths: | .cursor/rules/*.mdc，用 globs: + alwaysApply: false | .trae/rules/*.md，用 alwaysApply: false + globs: |
| 命令 | 技能加 disable-model-invocation: true；旧的 .claude/commands/*.md 仍加载 | 技能加 disable-model-invocation: true；旧的 .cursor/commands/*.md 仍加载 | .trae/commands/<名称>.md，文件名就是调用名，项目命令最多嵌套 3 层 |
| 技能 | .claude/skills/<名称>/SKILL.md | .cursor/skills/<名称>/SKILL.md，长说明放同目录 reference.md | .trae/skills/<名称>/SKILL.md |
| 子智能体 | .claude/agents/*.md，用 tools: 白名单 | .cursor/agents/*.md，用 readonly: true | .trae/agents/*.md，用 tools: 加 disallowedTools: |
| 钩子配置 | .claude/settings.json 的 hooks 字段（不是 hooks.json），事件名 PreToolUse | .cursor/hooks.json，version 为 1；事件名小写 preToolUse | .trae/hooks.json，version 用 1；事件名 PreToolUse |
| 钩子脚本 | 命令里用 "$CLAUDE_PROJECT_DIR" 定位脚本，从仓库根执行 | 从仓库根执行，脚本从标准输入读 JSON、向标准输出写 JSON | 用 timeout 限时，不写默认 30 秒；没有 failClosed |
把上面七个位置放进一个仓库，长这样。示例用的是一个按登录用户隔离数据的 Web 服务，注释写的是这份文件什么时候被读到。
照着建目录即可。钩子脚本放在 .cursor/hooks/，由 hooks.json 的 command 调起。
AGENTS.md # 每次对话自动读仓库根这一份
.cursor/
├── rules/
│ └── backend-tests.mdc # globs 命中 backend/**/*_test.go 才生效
├── skills/
│ ├── check-scope/
│ │ └── SKILL.md # 人输入 /check-scope 才执行
│ └── trace-retrieval/
│ └── SKILL.md # 描述命中时助手自己用
├── agents/
│ └── verifier.md # readonly: true，只读验收
├── hooks.json # version: 1
└── hooks/
└── block-env.py # 由 hooks.json 调起，从仓库根执行
backend/
└── AGENTS.md # 只在改 backend/ 时叠加
frontend/
└── AGENTS.md # 只在改 frontend/ 时叠加
顺序不能颠倒：后面每一步都引用前面的结论。每步产出一个文件，验证过再进下一步。
.cursor/rules/*.mdc，用 globs: 限定文件范围、alwaysApply: false。一份规则只讲一件事，正文 50 行以内。.cursor/skills/<名称>/SKILL.md，name 与目录名相同，description 用第三人称写清在什么任务里用。disable-model-invocation: true，助手就不会因为觉得相关而自己套用。.cursor/agents/*.md，只读的加 readonly: true，沿用当前模型写 model: inherit。.cursor/hooks.json（version: 1，事件名 preToolUse）和 .cursor/hooks/ 下的脚本，并显式设 failClosed: true。每加一个文件，就用一次真实任务验证它有没有起作用：助手还犯那个错，就把对应的约束写具体；已经不再犯，就删掉那一条。没验证过的文件等于没写。