CLAUDE.md

每次会话读项目根 CLAUDE.md，向上找到的同名文件全部拼接，不是覆盖。矛盾处助手可能挑任意一份，一条约束只写一处。

要加一条却拿不准该不该加，直接看三个上限与三条准入。

本页判断标准

在 /memory 的列表里能看到它，并且说得出这一条删掉后助手会在这个仓库里做错什么吗？

答「不能」，这一条就是背景噪音。删掉它，或者把它下沉到 规则。

三个上限与三条准入

文件篇幅上限
≤ 200 行
用 wc -l CLAUDE.md 检查。超了先按下面三条准入重过一遍再删，不要新开一节放背景。
单条约束长度
1–2 行
一条一件事。超过 2 行的，多半是两条约束黏在一起，拆开或删掉背景。
加载层级
向上全部拼接
不覆盖，所以同一条约束只能写一处。写两处，改一处漏一处。
1. 不写这句话，助手会在这个仓库里做错吗？ 只为已经发生或必然发生的错误加这一条。没发生过的，不写。
2. 这句话能判断对错吗？ 「SQL 必须绑定会话中的 scope_id」能核对。「注意数据安全」核不了，删掉。
3. 代码、lint 或已有文档里是不是已经有了？ 已经有了的不再写一遍。根文件写过的句子，规则文件里不要抄第二遍。
改完怎么确认真的被读到在对话里输入 /memory，它列出本次会话实际加载了哪些 CLAUDE.md 和规则；换到子目录重启会话再跑一次，根文件仍在列表里说明拼接生效。

边界：这三个上限针对课程项目。把某一条改成跨模块的规则文件之前，先确认它不是只对某一端成立——只对 backend/** 成立的句子属于 规则，不属于这一份。

仓库说明在三个工具里的读法

文件名、加载时机、冲突时以谁为准，三处都不一样。跨工具协作时先在这张表里对一遍，再动手建文件；建完用 /memory 确认这一份真被读到了。

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

只给 Claude Code 用的仓库，把约束直接写在 CLAUDE.md 里。同时给 Cursor 或 TraeCode 用的仓库，把共用句子写成 AGENTS.md，CLAUDE.md 只留一行 @AGENTS.md，正文不复制。

两份能直接抄的文件

下面第一份是引入行，第二份是一整份可用的 CLAUDE.md，按一个「按登录用户隔离数据的 Web 服务」写。抄过去后删掉与本项目无关的节，命令只保留已经能复制执行的步骤。

CLAUDE.md · 复用已有文件

仓库里已经有给其他工具用的 AGENTS.md 时，在根 CLAUDE.md 只写这一行。Claude Code 在会话开始时读入那份文件，再接上 @ 下面的句子。写完跑一次 /memory，列表里应同时出现这两个文件。

@AGENTS.md

CLAUDE.md

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

# CLAUDE.md

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

## 当前阶段

只做 README 里已经写明的能力。README 标成不做的，不要顺手加。
产品里给最终用户使用的功能，不是本仓库的技能文件。

## 数据范围

业务数据带 scope_id。
SQL 必须写成 `WHERE scope_id = ?`，问号绑定会话中的 scope_id。
用户不能读到其他范围的数据。
检索没有命中时，回答「无依据」，不要编造句子，也不要为此调用对话模型。
上传文件时 scope_id 取自会话，不取请求参数。

## 密钥

会话密钥、数据库口令和第三方 API 密钥只放在 .env。
.env 不提交。.env.example 里只能是占位符。

## 启动

cp .env.example .env
docker compose up --build -d

还没有可以复制执行的测试命令。不要编造 go test 或 npm 的参数。

这份文件共 28 行，离 200 行上限还有余量。根文件不加目录树、不加框架用法——那些内容代码本身和 README 里已经有。

写了却不生效的四种现象

下面四种都不报错，只是行为和预期不一样。按「现象 → 原因 → 修法」对号入座，改完用该行的修法命令复核一次。

现象原因修法
根 CLAUDE.md 和 .claude/CLAUDE.md 各写一份数据范围，改了根文件助手还是照旧两份都会被读，是拼接；矛盾处助手可能挑任意一份一条约束只写一处。跑 /memory 看本次到底加载了哪几份，把重复的那份删掉
写完 CLAUDE.local.md，git status 里出现它，被同事提交进仓库忘了加进 .gitignore.gitignore 加一行 CLAUDE.local.md；已提交的执行 git rm --cached CLAUDE.local.md
根文件只有 30 行，助手却总在改 README 时顺手补测试把只对某类文件成立的句子（如「测试必须两个所属范围」）写进了根文件，每次对话都读到这类句子移进 .claude/rules/ 并写 paths:，根文件只留整仓成立的短句
换到 TraeCode 后说明完全不生效，看着像「助手不听话」TraeCode 默认不读 AGENTS.md，且它不读 CLAUDE.md在「设置 → 规则 → 导入设置」打开「将 AGENTS.md 包含在上下文中」；跨工具共用的句子写成 AGENTS.md，Claude Code 用 @AGENTS.md 引入
对应知识点 这一页只是 仓库说明 在 Claude Code 里的落地写法。通用规则看 AGENTS.md（第一层 · 上下文）；只对某一端成立的句子，往下走看 规则。