AGENTS.md

Cursor 每次对话自动读仓库根的 AGENTS.md。从仓库根到当前文件的沿途，每一份同名文件都会叠进上下文：根文件对整个仓库生效，子目录文件只在改那个目录时额外生效，两边冲突时以更近的那份为准。把根文件控制在 100–200 行。

三种情况下会打开这一页：仓库根还没有 AGENTS.md，要写第一份 → 从「示例：三份 AGENTS.md」抄一份，删掉与本项目无关的段落；写了却没被遵守，改后端时那条要求像消失了一样 → 先看「Cursor 怎么读 AGENTS.md」，再拿「常见错误」的现象表对一行；要从 Claude Code 或 TraeCode 搬过来 → 先在「仓库说明在三处」逐行核文件名与叠加方式。

最容易写错的是把子目录当成分区：在 frontend/AGENTS.md 里写一条后端也要遵守的约束，改前端时读得到，改后端时读不到。两边都要遵守的句子只留根文件，子目录只补根文件没有的事实。

本页判断标准

删掉 backend/AGENTS.md，助手在这个仓库里会少知道哪一条事实？

答不出具体一条，那份文件里写的就是别处也有的话。子目录文件只留这个目录独有的事实，两边都要遵守的句子只在根文件写一次。

Cursor 怎么读 AGENTS.md

改 frontend/ 时，助手读得到根文件和 frontend/AGENTS.md，读不到 backend/AGENTS.md；改 backend/ 时反过来。所以「谁可以使用、数据范围怎么隔离、密钥放哪里」这类两边都适用的事实，只在根文件写一次。

根文件篇幅
100–200 行
超过 200 行，先删三样：框架教程、完整目录树、个人习惯。还超，就把只在某类文件里成立的句子移到子目录文件或 .cursor/rules/。
1. 不写这句话，助手会在这个仓库里做错吗？ 只为已经发生或必然发生的错误加一条。没出过错的不加。
2. 这句话能判断对错吗？ 「SQL 必须绑定会话中的 scope_id」可以核对。「注意数据安全」不能。
3. 代码、lint 或已有文档里是不是已经有了？ 已经有了的不要再写一遍。根文件写过的句子，子目录不要再抄。

三条里有一条答「否」，就不写这一条。写进去之后用一次真实任务验证：助手还犯那个错，就把那一条写具体；已经做到，就删掉它。约束变了，把约束和导致它变化的代码放进同一次合并请求。

仓库说明在三处

同样一份仓库说明，三个工具的文件名、叠加方式和是否自动读都不一样。从另一个工具搬过来时逐行核这张表。

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

Cursor 这一列的两个「——」是它的空位：没有个人文件，也没有 /memory 这类命令。要确认加载了什么，只能靠文件位置本身——这也是每个季度要重读一次根文件的原因。

示例：三份 AGENTS.md

  • 根目录：谁可以使用、数据范围、密钥、启动命令。
  • backend/AGENTS.md：数据库、上传目录、检索索引。改前端时助手读不到这一份。
  • frontend/AGENTS.md：浏览器只走接口，数据范围来自登录会话。

下面三份是一个按登录用户隔离数据的 Web 服务示例，用它看三份文件怎么分工。启动命令只保留能照着复制执行的步骤；测试命令还没固定下来就空着，别编造 go test 或 npm 的参数。

AGENTS.md

全仓库生效。数据范围放在这里，因为改前端时也要遵守。

# AGENTS.md

这是一个按登录用户隔离数据的 Web 服务。隔离边界是用户所属范围。

## 当前阶段

只做 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 的参数。

backend/AGENTS.md

只补充根文件没有的后端事实。改前端时这份不会进上下文。

# backend/AGENTS.md

数据库类型和主键形式跟现有建表脚本走，不要擅自改成另一种 id。
上传文件放在配置的上传目录，不要把文件正文塞进 SQL。
若使用向量库，点的 id 与数据库里的切片 id 对齐。
改查询或检索时，测试要覆盖两件事：本范围读得到，其他范围读不到。

frontend/AGENTS.md

只补充浏览器里才会做错的事。改后端时这份不会进上下文。

# frontend/AGENTS.md

只通过后端接口访问数据。
不要在浏览器里直连数据库或向量库。
数据范围来自登录会话，不要用地址栏里的 id 切换范围。
密钥和网关地址不要打进前端包。

三份文件加起来不到 60 行。再加一条之前，先过一遍上面三问；三条都答「是」才写。仓库只有一层目录、没有前后端之分时，只保留根文件，别为了对称硬造子目录文件。

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

下面每一条都从能观察到的现象开始。对得上现象，就照最右一列的修法改。

现象原因修法
在 frontend/AGENTS.md 写的规则，改成后端时助手就不遵守了Cursor 只把「仓库根 → 当前文件」沿途的文件叠进上下文，改后端时读不到前端目录那份两边都要遵守的句子移到根 AGENTS.md；子目录文件只留该目录独有的事实
仓库里放了 CLAUDE.md，Cursor 完全没读，助手照样犯老错Cursor 读的文件名是 AGENTS.md，不认 CLAUDE.md改名为 AGENTS.md，或保留 CLAUDE.md 的同时另建一份 AGENTS.md
根文件写到 300 行后，末尾几条规则时好时坏地失效整份文件每次对话都进上下文，太长时靠后的句子被稀释按 100–200 行删减：删框架教程、完整目录树、个人习惯；再把某类文件才需要的句子移到 .cursor/rules/ 或子目录文件
同一条约定在根文件和子目录文件各写一遍，改的时候只改了一处，助手行为前后矛盾两边冲突时以更近的那份为准，重复句子等于留了两处真相根文件保留一次；子目录文件删除重复句，只补充根文件没有的事实
助手每次都要提醒「记得用 .env.example」，因为根文件只写了「密钥放 .env」只写了禁止项，没写对应的正确做法在密钥段补一句「.env.example 里只能是占位符」——能核对，也覆盖了正确路径
对应知识点 这一页只是 仓库说明 在 Cursor 里的落地写法。通用规则见 AGENTS.md（第一层 · 上下文）。上游是 上下文分层与预算，下游是 规则（只在某类文件里才需要的句子）。