该写什么：Claude 从代码里看不出来的东西
先在项目里运行 /init。Claude 会读一遍代码库，写出第一版 CLAUDE.md。接下来的活儿多半是删行，Anthropic 最佳实践页面也这么说。目录清单就可以先删，文件夹 Claude 自己会打开看。
每次会话开头，整个文件都会载入一个全新的上下文窗口，不管接下来做什么。你让 Claude 修 CSS，那条部署说明也照样占着上下文。
Anthropic 的记忆文档给了两组例子。“使用 2 个空格缩进”行，“把代码格式整理好”不行。“提交前运行 npm test”行，“测试你的改动”不行。行的那一句，你都能查出 Claude 照没照做。
- 精确的测试、类型检查和 lint 命令，以及怎样只跑单个测试文件。
- 代码会误导人的地方：到处都是、但新代码不该照抄的旧写法，看着没人用、其实还在用的目录。
- 仓库里查不到的决定，比如团队选定了哪个错误处理函数，哪些改动要过迁移评审。
X 官方嵌入卡片的截图，拍摄于 2026 年 11 月 3 日，时间为美国太平洋时间，没有收入链接预览。点击截图可到 X 上打开原帖。
一个简短的 CLAUDE.md 示例
这份是我们给一个小型 TypeScript 接口服务写的。标题照 Anthropic 最佳实践页面的分法，存成项目根目录下的 CLAUDE.md 就能用。
# Commands
- Install: npm ci
- Run one test file: npx vitest run path/to/file.test.ts
- Typecheck: npx tsc --noEmit
# Conventions
- API handlers live in src/api/handlers/, one file per route
- Throw the error classes in src/lib/errors.ts, never raw strings
- src/legacy/ is still live. Do not copy its patterns into new code
# Gotchas
- Integration tests need DATABASE_URL set, see .env.example
- Git workflow: @docs/git-workflow.md
CLAUDE.md 放在哪里，怎样加载
比如你在 foo/bar/ 里启动 Claude Code。这一级和上面每一级目录里的 CLAUDE.md、CLAUDE.local.md 都会加载。先读 foo/CLAUDE.md，再读 foo/bar/CLAUDE.md，离你最近的排在最后。foo/bar/ 再往下的子目录，要等 Claude 读取或修改那里的文件，里面的 CLAUDE.md 才加载。
这些文件是首尾拼起来的，谁也不覆盖谁。项目文件排在用户文件后面（见记忆文档），但两份说法不一样时，Claude 听哪一份都有可能。
示例最后一行 @docs/git-workflow.md 是一条导入。被导入的文件跟着导入它的文件一起加载，所以拆成几个文件并不省上下文。块级 HTML 注释不一样，比如 <!-- maintainer notes -->，送给 Claude 之前就被去掉了。给同事的备注写在里面，不占上下文。
CLAUDE.local.md 加进了 gitignore，只存在于你创建它的那个 git worktree。想让每个 worktree 都用上同一套个人指令，就放进主目录下的一个文件再导入，比如 @~/.claude/my-project-instructions.md。
| 范围 | 位置 | 谁能看到 |
|---|---|---|
| 组织托管策略 | macOS：/Library/Application Support/ClaudeCode/CLAUDE.md。Linux 和 WSL：/etc/claude-code/CLAUDE.md。Windows：C:\Program Files\ClaudeCode\CLAUDE.md | 组织内的所有用户 |
| 用户 | ~/.claude/CLAUDE.md | 只有你，所有项目 |
| 项目 | ./CLAUDE.md 或 ./.claude/CLAUDE.md | 团队，通过版本控制共享 |
| 本地 | ./CLAUDE.local.md，并加入 .gitignore | 只有你，仅限当前项目 |
拍摄方式和日期同上。X 在回复处用“Show more”截断了后面的内容，想看全文请到 X 上打开。
用 /init、/doctor 和 /memory 加行、删行
项目里已经有 CLAUDE.md，/init 就不会覆盖它，只提改进建议。Cursor 和 Copilot 的规则它也会读：Cursor 的在 .cursor/rules/ 或 .cursorrules，Copilot 的在 .github/copilot-instructions.md。
/doctor 会建议删掉 Claude 能从代码里推出来的东西，比如目录结构、依赖清单。容易踩的坑、背后的理由、和工具默认不同的约定，它会留着。它的 prompt-audit 模式要 Claude Code v2.1.283 或更高版本，会多标出三类问题：给旧模型写的指令，指向不存在的文件或命令的引用，互相矛盾的文件。它只出报告。你不让 Claude 应用修改，文件就一个字都不变。
手动改用 /memory。用户和项目两个范围的 CLAUDE.md、CLAUDE.local.md 它都会列出来，还不存在的也列，选哪个就在编辑器里打开哪个。在对话里说一句“把这条加到 CLAUDE.md”也行。扩展功能总览的建议是，同一句纠正别打第二遍，直接这么加进去。
只说“记住这个”，内容进的是自动记忆。那是另一套存储，由 Claude 自己写，记你的偏好、你给过的纠正。每个仓库在 ~/.claude/projects/ 下有一个文件夹，同一仓库的所有 worktree 共用。每次会话只加载 MEMORY.md 索引的开头，主题文件 Claude 要用时再读。开关在 /memory 里。
Anthropic 说什么时候该加一行
Claude 第二次犯同样的错。代码评审发现了 Claude 本该知道的、关于这个代码库的事。你在聊天里输入了和上次会话一样的纠正或说明。新来的同事也需要同样的背景才能上手。
哪些内容不该写，以及改放到哪里
全大写的强调可以先删。现在的模型看到平实的写法就会照做，IMPORTANT 堆多了，反而容易让 Claude 把规则用过头。文件超过推荐长度，Claude Code 启动时会警告。要到 4 MiB 以上，它才整个跳过，一个字都不加载。
只跟接口代码有关的规则，放进 .claude/rules/。在头信息里写一个 paths 过滤条件，只匹配 src/api/ 下的 TypeScript 文件。Claude 读取或修改这些文件时，规则才加载。按需加载的文件，包括子目录里的 CLAUDE.md，在 200K 上下文窗口下每个最多读 40,000 个字符。超出的部分 Claude 收不到，只拿到开头。用 wc -m 数一下，就知道还剩多少。
很长的发布流程，适合做成技能，也就是 .claude/skills/ 下一个带 SKILL.md 的文件夹。每次会话，Claude Code 只加载技能的描述，任务用得上才读完整文件。
你定义的子智能体启动时也带着 CLAUDE.md。文件越长，每次委派重复加载的就越多。内置的 Explore 和 Plan 智能体会跳过它们，自定义智能体设 omitClaudeMd: true 也能不加载。
CLAUDE.md 里写“不要读 .env”，Claude 多半会照做，但不保证次次照做。这份文件放的是准则，Claude 可能觉得某条不适用。设置里加一条 Read(./.env) 拒绝规则，任何权限模式下都管用。“不要动 migrations 文件夹”可以写成 PreToolUse 钩子，拦下 migrations/ 下的所有修改。失手一次就会泄露密钥或损坏数据的规则，我们才搬出去。最佳实践页面也提醒别过头。“优先使用具名导出”例外很多，留在 CLAUDE.md 里就好。
2.5k
个令牌：Claude Code 的创造者 Boris Cherny 说，他的团队提交进仓库的 CLAUDE.md 就这么大
来源：Boris Cherny 在 X 上的帖子 (2026年11月3日 查阅)
| CLAUDE.md | 按路径生效的规则 | 技能 | 钩子或拒绝规则 | |
|---|---|---|---|---|
| 放什么 | 命令、约定和容易踩的坑 | 只和代码库某一部分有关的规则 | 某类任务的一长串做法 | 绝不允许例外的规则 |
| 什么时候送到 Claude 面前 | 启动时，每次会话都有 | Claude 读取或修改匹配的文件时 | 描述每次会话都有，其余部分在任务需要时才读 | 在它监听的事件上，比如每次修改文件之前 |
| 做不相干的任务时也占上下文 | 是 | 否 | 部分 | 否 |
| 每次都会照做 | 否 | 否 | 否 | 是 |
来源：Claude Code 文档：Claude 如何记住你的项目 (2026年11月3日 查阅)；Claude Code 文档：最佳实践 (2026年11月3日 查阅)；Claude Code 文档：用技能扩展 Claude (2026年11月3日 查阅)
这里的每个事实都来自下方来源列表里的页面，阅读日期为 2026 年 11 月 2 日和 3 日。本文是对官方文档的解读，不是实际测试，文件位置、命令和版本要求也会随 Claude Code 的发布而变化。
常见问题
CLAUDE.md 和 AGENTS.md 是同一个文件吗？
不是，这是两个文件，AGENTS.md 在 Claude Code 那里只是备选。v2.1.277 及以后的版本，只有在工作目录及其上级目录里都找不到 CLAUDE.md 或 CLAUDE.local.md 时，才会改读 AGENTS.md。两个都想用，就在 CLAUDE.md 开头写一行 @AGENTS.md，Claude 会先读共用的那份，再读你专门写给 Claude 的内容。在 Windows 上，Anthropic 更推荐这种导入，而不是符号链接，因为 Git 可能把提交进仓库的符号链接检出成只有一行字的文本文件。
Claude 为什么不照我的 CLAUDE.md 做？
先确认它加载了没有。运行 /context，看 Memory files 下面有没有它。子目录里的 CLAUDE.md 是按需加载的，加载前不会出现，加载后会多一行带路径的 Loaded。加载了还不管用，可能是写得太长、太含糊，或者跟另一个文件矛盾。CLAUDE.md 是排在系统提示后面、作为一条用户消息交给 Claude 的。Anthropic 的排查步骤最后一步是把这一行写得更具体，就像前面缩进那组例子。
CLAUDE.md 在 /compact 之后还在吗？
项目根目录的那个文件还在。执行 /compact 之后，Claude 会从磁盘重新读取它并再次注入，嵌套的文件和按路径生效的规则则在需要时重新加载。只在对话里说过的指令可能会丢，想让它一直有效，就写进文件。
在大型单体仓库里，怎样跳过别的团队写的 CLAUDE.md？
在 .claude/settings.local.json 里加一个 claudeMdExcludes 列表，写上路径或 glob 模式，这样排除设置只在你自己的电脑上生效。模式按绝对文件路径匹配。组织托管的 CLAUDE.md 不能被排除。
资料来源
- Claude Code 文档：Claude 如何记住你的项目 https://code.claude.com/docs/en/memory
- Claude Code 文档：最佳实践 https://code.claude.com/docs/en/best-practices
- Claude Code 文档：扩展 Claude Code https://code.claude.com/docs/en/features-overview
- Claude Code 文档：用技能扩展 Claude https://code.claude.com/docs/en/skills
- Claude Code 文档：创建自定义子智能体 https://code.claude.com/docs/en/sub-agents
- Boris Cherny 在 X 上的帖子：Claude Code 团队提交进仓库的 CLAUDE.md 有 2.5k 个令牌 https://x.com/bcherny/status/2007212366094811401
- Boris Cherny 在 X 上的帖子：哪些 CLAUDE.md 在启动时加载，哪些稍后加载 https://x.com/bcherny/status/2016339448863355206