AGENTS.md

AGENTS.md 是放在仓库根目录、给助手读的说明文件；整仓都成立、每次改动都成立的话写在这里，每次对话都会带上它。

本站下文说到「仓库说明」，指的都是这一份文件。它最忌含糊——写得含糊，助手照着含糊的话写出一版，还说不出这版违反了哪一条：文件里根本没有那一条。

本层判断标准

把这份文件交给一个没参与过讨论的人配助手，他产出的第一版代码，能不能过评审？

答「不能」，别去改代码。先查文件：要么缺了某条约束，要么留着一条已经不成立的旧句。

目录结构

仓库说明只有一份，放在仓库根目录，文件名固定。CLAUDE.md 是 Claude Code 的入口，正文里只写一行 @AGENTS.md，不复制内容——复制之后同一条约束就有两处，改一处漏一处。目录级的 AGENTS.md 是例外，只在两个目录确实需要不同做法时才有。

仓库根目录下的仓库说明

仓库根目录/
├── AGENTS.md                      # 唯一的正文，约 110 行
├── CLAUDE.md                      # Claude Code 的入口，正文只有 @AGENTS.md
├── backend/
│   └── AGENTS.md                  # 例外：该目录确有不同做法时才加，写清例外范围
└── .cursor/
    └── rules/                     # 只对某类文件成立的句子下沉到这里

判据落在文件名上：根目录只该有 AGENTS.md 与引入它的 CLAUDE.md 两个。在 CLAUDE.md 里写正文而不是 @AGENTS.md，同一条约束就写了两处，冲突时哪一份生效由工具决定。

典型应用示例：一条约束怎么每次都在场

场景：新开一次会话，让助手「给列表接口加按租户导出」。这次对话里没提 scope_id 三个字，也没贴任何文档。

有它 AGENTS.md 随这次对话进入上下文，其中「查询只绑定会话中的 scope_id，不从请求里读」就在场，初版代码一次写对；到了评审，评审人对照的也是这份文件里的同一条。
没有它 助手按最常见的写法从请求体里读 scope_id：能跑通，但等于把越权查询写进接口，发现问题要等到评审甚至更晚。

一条能不能写进去：四问筛选

候选句子按顺序问四条，任一条答「能」或「是」，就不写进根文件。四问都在问同一件事：这句话有没有一个能指认的落点。

删掉它，助手会不会改错？不会，就不写。
它能不能被一条检查命令挡住？能，就交给检查，根文件只留命令名。
代码、构建脚本或 docs/ 里是不是已经有同一条？有，就不重复写。
是不是只对某一类文件或某一次任务成立？是，就往下沉到规则或 specs/。

四问筛完还能留在根里的通常只剩十几条；仍拿不准的一律不写，等它真的导致第二次错误再补。已经不再做错的句子要删——长度是预算，清理的节奏见上下文分层与预算。

落在哪

一条约束只写一处。两种工具并用时，另一种用引入的方式复用，不复制正文——同一条约束写两处时，哪一份生效由工具决定。

工具根文件与入口落地页
CursorAGENTS.md，自动读取Cursor 仓库说明落地页
TraeCodeAGENTS.md，需在设置里打开「将 AGENTS.md 包含在上下文中」TraeCode 仓库说明落地页
Claude CodeCLAUDE.md，正文只写 @AGENTS.mdClaude Code 仓库说明落地页