详解 CLAUDE.md：让 Claude Code 真正记住你的项目（一）

很多人第一次用 Claude Code 时，都会把同一批背景信息反复贴进对话：项目怎么启动、测试怎么跑、哪些目录不能乱改、代码评审最在意什么。一次两次还能接受，时间一长就会变成新的维护成本。

CLAUDE.md 解决的正是这个问题。它不是面向读者介绍项目的 README，也不是强制执行的配置文件，而是 Claude Code 在每次会话开始时读取的项目记忆。写得好，Claude 更像一个熟悉仓库习惯的协作者；写得乱，它就会把上下文窗口花在过期、冲突或过于宽泛的指令上。

CLAUDE.md 适合沉淀“每次会话都应该知道”的事实：构建命令、测试方式、目录约定、团队规则，以及那些你不想再解释第二遍的偏好。

CLAUDE.md 到底是什么

根据 Claude Code 官方文档，CLAUDE.md 是一种 Markdown 格式的持久指令文件，可以用于项目、个人工作流或组织级规范。Claude 会在会话开始时读取这些文件，并把内容放入上下文窗口。

这句话里有两个关键点。

第一，它是上下文，不是硬约束。CLAUDE.md 会影响模型行为，但不像权限配置、沙箱设置或 hook 那样由客户端强制执行。如果一条规则必须在固定时机运行，例如“每次提交前必须执行 lint”，更稳妥的做法是把它写进 hook 或 CI，而不

是只放在 CLAUDE.md 里。

第二，它会消耗上下文窗口。文件越长，占用越多；内容越模糊，模型越难稳定遵守。官方建议每个 CLAUDE.md 尽量控制在 200 行以内。超过这个量级后，应该考虑把只适用于局部目录或文件类型的规则拆到 .claude/rules/，而不是继续往一个文件里堆。

什么时候应该写进 CLAUDE.md

一个实用判断是：这条信息是否值得 Claude 在每次进入项目时都知道。

适合写入的内容通常有四类：

构建与测试命令：例如“使用 pnpm test，不要使用 npm test”“后端集成测试依赖本地 Redis”。
项目结构事实：例如“API handler 位于 src/api/handlers/”“共享组件在 packages/ui/”。
团队代码约定：例如缩进、命名、错误处理格式、提交前检查项。
重复纠正过的问题：Claude 第二次犯同样错误、代码评审指出它本该知道的上下文，或者你跨会话重复输入过的说明。

不适合写入的内容也要果断排除。临时任务背景应该留在当前对话；复杂多步流程可以做成 Skill、脚本或文档；只影响某个子目录的规则应该放入 path-scoped rules；涉及强制执行的安全策略应该进入 managed settings、权限配置、hook 或 CI。

文件放在哪里：作用域与加载顺序

CLAUDE.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`	私有测试数据、个人 sandbox URL	当前项目、当前机器

官方文档特别强调，Claude Code 会从当前工作目录开始向上查找目录树中的 CLAUDE.md 和 CLAUDE.local.md。找到的文件不是互相覆盖，而是拼接进上下文：越靠近文件系统根部的内容越早出现，越靠近当前工作目录的内容越晚出现。同一目录下，CLAUDE.local.md 会追加在 CLAUDE.md 后面。

也就是说，越具体的规则越靠后，模型看到它们时也更接近当前任务上下文。

flowchart TD
    A[启动 Claude Code] --> B[从当前工作目录向上查找]
    B --> C[加载组织级 CLAUDE.md]
    C --> D[加载用户级 CLAUDE.md]
    D --> E[加载项目级 CLAUDE.md]
    E --> F[追加同级 CLAUDE.local.md]
    F --> G[按需加载子目录中的 CLAUDE.md]
    G --> H[把内容注入上下文窗口]

如果在大型 monorepo 中工作，父目录或其他团队的指令可能被意外加载。此时可以使用 claudeMdExcludes 排除特定路径或 glob。需要注意的是，组织托管的 CLAUDE.md 不能被个人设置排除。

还有一个容易忽略的细节：CLAUDE.md 里的块级 HTML 注释会在注入上下文前被移除。你可以用它给维护者留下说明，而不用把这些说明也消耗到 Claude 的上下文里；但代码块里的注释会保留。

初始化：从 `/init` 开始，但不要停在那里

项目级 CLAUDE.md 可以手写，也可以用 /init 生成起点。/init 会分析代码库，提取构建命令、测试方式和项目约定；如果仓库里已经有 CLAUDE.md，它会建议改进，而不是直接覆盖。

这一步适合拿到一个初稿，但真正有价值的内容往往来自“工具无法自动发现”的知识。例如：

哪些测试慢，什么时候才需要跑完整套；
哪些目录属于生成产物，不应手改；
哪些依赖版本因为线上兼容性暂时不能升级；
代码评审中经常被要求修正的项目习惯。

如果仓库已经有 AGENTS.md，不要假设 Claude Code 会自动读取它。官方文档明确说明 Claude Code 读取的是 CLAUDE.md，不是 AGENTS.md。兼容做法是在 CLAUDE.md 中用 @AGENTS.md 导入已有说明，再追加 Claude 专属规则；如果不需要额外内容，也可以用符号链接，但 Windows 上创建 symlink 可能需要管理员权限或 Developer Mode。

1
2
3
4
5
6
@AGENTS.md

## Claude Code

- 修改 `src/billing/` 前先进入 plan mode。
- 提交前运行 `pnpm test`。

写法：短、具体、可验证

CLAUDE.md 的质量，直接决定它能不能被稳定遵守。官方给出的方向很明确：具体、简洁、结构化。

模糊指令很容易失效。例如“保持代码整洁”听起来正确，但模型无法判断边界；“使用 2 空格缩进”“API handler 必须返回标准错误结构”“提交前运行 npm test”才是可执行、可检查的规则。

一个推荐结构如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Project Instructions

## Build and Test

- Install dependencies with `pnpm install`.
- Run unit tests with `pnpm test`.
- Run `pnpm lint` before opening a PR.

## Architecture

- API handlers live in `src/api/handlers/`.
- Shared React components live in `packages/ui/`.
- Do not edit generated files under `src/generated/`.

1
2
3
4
5
## Coding Standards

- Use 2-space indentation.
- Prefer existing helper functions before adding new utilities.
- Keep changes scoped to the user request.

这里的重点不是模板本身，而是每条规则都能回答“Claude 该怎么做”。如果一句话不能指导具体行为，就应该删掉或改写。

`@import`：整理结构，不是节省上下文

CLAUDE.md 支持用 @path/to/file 导入其他文件。相对路径会按包含导入语句的文件来解析，而不是按当前工作目录解析；导入可以递归，最大深度是 5 层。

这适合把项目概览、工作流说明、团队规范拆开管理：

1
2
3
4
5
6
See @README.md for project overview.

## Additional Instructions

- Git workflow: @docs/git-instructions.md
- Release checklist: @docs/release-checklist.md

但要注意一个常见误区：导入文件仍然会在启动时展开并进入上下文。它能让文件更好组织，却不会降低上下文占用。如果目标是减少 token，应该把不需要全局加载的内容拆到 .claude/rules/ 的路径规则中，或者放进普通文档，让 Claude 在需要时再读取。

第一次遇到项目中的外部导入时，Claude Code 会弹出审批对话框列出相关文件。拒绝后，这些导入会保持禁用。