CLAUDE.md：放在哪里、写什么，以及如何与 AGENTS.md 配合

CLAUDE.md 是什么

Claude Code 每次开启会话，都不记得上一次的内容。CLAUDE.md 就是给它提供新同事需要的背景：启动时读取，并在系统提示之后作为一条消息发给 Claude。所以它是上下文，而不是强制执行的配置。Claude 通常会遵守，但凡是必须始终执行或绝不能发生的事，应该放进 hooks 或权限规则。

• 就是普通的 markdown，没有必填字段：标题加简短的要点列表效果最好。
• 文件是叠加而不是覆盖：所有适用的 CLAUDE.md 都会加载，所以相互矛盾的内容会让 Claude 自己挑一条。
• 用 /context all 查看已加载的内容，在 Memory files 下。

CLAUDE.md 放在哪里，以及加载顺序

Claude Code 按从最宽泛到最具体的顺序加载这些文件，所以离启动位置最近的文件最后读取。它还会从工作目录向上查找，加载每一级父目录里的 CLAUDE.md。

怎样写出真正管用的 CLAUDE.md

1. 从 /init 开始

   在项目里运行 /init。Claude Code 会读取代码库并生成一份初始的 CLAUDE.md；如果已经有了，它会给出改进建议而不是直接覆盖。它还会读取 .cursorrules 和 Copilot 的指令。

2. 只留下 Claude 自己找不到的内容

   保留准确的构建、测试和 lint 命令（包括如何只跑一个测试）、代码里容易误导人的地方、没有写在任何地方的决定，以及你已经纠正过两次的事。删掉文件树和 Claude 能从仓库里读出来的架构。Anthropic 建议控制在 200 行以内。

   # Commands
   - Install: pnpm install
   - One test file: pnpm vitest run path/to/file.test.ts
   - Typecheck: pnpm tsc --noEmit
   
   # Conventions
   - 用 src/lib/errors.ts 里的 helper 抛出错误，不要直接抛字符串。
   - src/legacy/ 仍在线上使用，但不要照搬它的写法。
   
   # Gotchas
   - 集成测试需要 DATABASE_URL（见 .env.example）。

3. 要具体，但别大喊大叫

   写“使用 2 个空格缩进”，而不是“把代码格式化好”。最新文档说，IMPORTANT 和全大写已经是过时的建议：它们会让 Claude 过度套用某条规则。如果某一行总被漏掉，就缩短文件，或者把这条规则改成 hook。

4. 用导入和规则文件拆分

   @path/to/file 会导入另一个文件（相对于导入它的文件，最多四层）；放在反引号里的 @ 保持原样。只适用于部分代码的规则放进 .claude/rules/ 并加上 paths glob，这样只有 Claude 碰到匹配的文件时才会加载。

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - 每个 handler 都要用 src/api/schemas/ 里的 schema 校验输入。

5. 把流程挪到 skill 里

   多步骤的工作流，比如怎么发布版本，应该放进 skill（.claude/skills/<name>/SKILL.md），只在相关时才加载。CLAUDE.md 每个任务都会读，所以每一行都在消耗注意力。

6. 保持更新

   当 Claude 重复犯同样的错，或者评审发现了问题，就加一行；用 /memory 编辑文件，或者让 Claude 来更新。文件变得太长时，/doctor 会建议精简。

来源：Claude Code 文档，How Claude remembers your project

CLAUDE.md 与 AGENTS.md 对比

AGENTS.md 是面向编程 agent 的开放指令格式，Codex、Cursor、Gemini CLI、GitHub Copilot 的 coding agent、opencode 等许多工具都在用。Claude Code 现在也会读取它，但默认只在项目没有 CLAUDE.md 时才读。

Claude Code 和 Codex 共用一个文件

如果团队两种 agent 都用，就把共用的指令放在 AGENTS.md 里，让 CLAUDE.md 导入它，再在下面写只给 Claude 的备注。它不会被加载两次。符号链接（ln -s AGENTS.md CLAUDE.md）也可以，但 Windows 上的队友用不了，而且只用文字写一句“去读 AGENTS.md”的 CLAUDE.md 并不可靠。

• 本网站自己的仓库就是这么做的：它的 CLAUDE.md 只有一行 @AGENTS.md。
• Codex 会从仓库根目录一路读到你的工作目录里的 AGENTS.md 文件，合并后的大小默认上限为 32 KiB。

限制与注意事项

• 启动时加载的 CLAUDE.md 最多完整读取 4 MiB；更大的文件会被跳过。
• 按需加载的文件，比如子目录的 CLAUDE.md 和按路径生效的规则，超过单文件上限就会被截断（200K 上下文窗口下为 40,000 个字符）。
• 导入只是整理文件，并不省上下文：被导入的文本照样会加载。
• 项目之外的导入只需批准一次；HTML 注释 <!-- --> 会被去掉，不占任何成本。
• 执行 /compact 之后，项目根目录的 CLAUDE.md 会被重新读取。
• “记住这个”会进入自动记忆（~/.claude/projects/<project>/memory/），而不是 CLAUDE.md。

CLAUDE.md 说明怎么干活，Crewmark 决定干什么、什么时候干。

好的 CLAUDE.md 能让每个 Claude Code 会话一开始就了解情况，但会话仍然要等你的下一条消息。Crewmark 把 Claude Code、Codex、DeepSeek Harness 或 OpenCode 会话变成有岗位、目标和工作时间的 AI 员工，并按心跳唤醒它，从看板上接手下一个 issue。

1. 把会话变成员工

   选一个岗位，比如软件工程师或 SEO 专员，把目标写成一个数字，然后在你的项目里运行设置命令，你的 CLAUDE.md 本来就在那里。

2. 让心跳启动工作

   在工作时间内，员工每 15、30 或 60 分钟在同一个对话里醒来一次；参见如何让 Claude Code 主动工作。多个员工可以共用一个仓库，参见多个 Claude Code agent。

3. 分配 issue，回复它的消息

   把工作放到看板上，员工会接手、边做边评论，需要你拍板时给你发消息。阅读什么是 AI 员工。

CLAUDE.md 常见问题