详解 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
14
15
16
17
18
19
# 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/`.

## 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 会弹出审批对话框列出相关文件。拒绝后，这些导入会保持禁用。

用 `.claude/rules/` 拆分大项目规则

当规则开始变多，.claude/rules/ 是比继续膨胀 CLAUDE.md 更合适的组织方式。这个目录下的 Markdown 文件会被递归发现，可以按主题拆成 testing.md、security.md、api-design.md 等。

没有 paths front matter 的规则会在启动时加载，优先级与 ./.claude/CLAUDE.md 相同。带 paths 的规则只在 Claude 处理匹配文件时触发。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation.
- Use the standard error response format.
- Include OpenAPI documentation comments.

这对 monorepo 尤其有价值。前端、后端、测试、基础设施各自的规则可以按路径触发，既减少启动上下文，也降低跨团队规则互相干扰的概率。

个人级规则也有对应目录：~/.claude/rules/。用户级规则会先于项目规则加载，因此项目规则拥有更高优先级。

CLAUDE.md 与 auto memory 的区别

官方把 Claude 的记忆机制分成两类：CLAUDE.md 和 auto memory。

机制	谁来写	作用域	适合内容
`CLAUDE.md`	人手动维护	组织、用户、项目或本地	明确、稳定、希望团队共享的规则
auto memory	Claude 根据会话自动保存	每个仓库一份，本机共享 worktree	调试经验、架构笔记、工作习惯、代码风格偏好

auto memory 从 Claude Code v2.1.59 开始可用，并且默认开启。它会把 Claude 认为未来可能有用的信息保存为本机 Markdown 文件，例如构建命令、调试发现、架构笔记和工作流习惯。它不会每次会话都写入，而是由 Claude 判断是否值得保存。

存储位置默认是：

1
2
3
4
5
~/.claude/projects/<project>/memory/
├── MEMORY.md
├── debugging.md
├── api-conventions.md
└── ...

<project> 路径由 git 仓库推导。同一个仓库的 worktree 和子目录会共享一份 auto memory；不在 git 仓库中时，则使用项目根目录。auto memory 是本机本地的，不会自动跨机器或云环境同步。

启动时只会加载 MEMORY.md 的前 200 行或前 25KB，取两者中先达到的限制。详细主题文件不会启动即加载，而是在需要时由 Claude 通过普通文件工具读取。这个限制只适用于 auto memory 的 MEMORY.md，不适用于 CLAUDE.md：CLAUDE.md 会完整加载，只是越短越容易被遵守。

用 `/memory` 审计与维护

/memory 是维护记忆系统的入口。它会列出当前会话加载的 CLAUDE.md、CLAUDE.local.md 和 rules 文件，允许你开关 auto memory，并提供打开 auto memory 目录的入口。

如果你对 Claude 说“记住以后都用 pnpm，不要用 npm”，Claude 会把这类信息保存到 auto memory。相反，如果你希望它进入项目共享规则，就应该明确要求“把这条加入 CLAUDE.md”，或者直接通过 /memory 打开文件编辑。

这种区分很重要：团队约定应该版本化，个人偏好可以本地化，自动学习到的经验需要可审计。

大团队中的边界：指导归指导，强制归强制

在组织环境里，CLAUDE.md 可以由 IT 或 DevOps 通过托管策略部署到固定路径，也可以把内容写入 managed settings 的 claudeMd 字段。它适合承载公司代码风格、数据处理提醒、合规要求和行为指导。

但官方文档也给出清晰边界：managed settings 和 managed CLAUDE.md 不是同一种东西。

阻止特定工具、命令或路径：用 permissions.deny 等 settings。
强制沙箱隔离：用 sandbox.enabled。
控制环境变量、API provider、登录方式或组织锁定：用 settings。
说明代码风格、质量标准、数据处理提醒：用 managed CLAUDE.md。

换句话说，CLAUDE.md 负责让 Claude “知道应该怎么做”，settings、权限、hook 和 CI 负责让系统“不能做错”或“做错会失败”。

常见问题与排错方法

如果 Claude 没有遵守 CLAUDE.md，先不要急着把规则写得更凶。按下面顺序检查更有效。

确认文件是否真的被加载。 运行 /memory，查看目标 CLAUDE.md、CLAUDE.local.md 或 rules 文件是否出现在当前会话列表里。如果没有出现，Claude 看不到它。

确认位置是否正确。 当前工作目录会影响加载路径。在 foo/bar/ 启动时，会加载 foo/bar/CLAUDE.md、foo/CLAUDE.md 以及对应的 local 文件；额外通过 --add-dir 加入的目录默认不会加载其中的 CLAUDE.md，除非设置 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1。

检查冲突规则。 多个文件给出相反要求时，Claude 可能任意选择其一。定期清理用户级、项目级、嵌套目录和 .claude/rules/ 中的过期指令。

把模糊话改成可执行规则。 “写高质量代码”不如“修改 API handler 后运行 pnpm test:api”；“保持风格一致”不如“优先复用 src/lib/errors.ts 的错误构造函数”。

该用 hook 的就用 hook。 如果规则必须在某个生命周期点执行，例如每次提交前、每次文件编辑后，使用 hook 比写在 CLAUDE.md 中可靠。

理解 /compact 后的行为。 项目根的 CLAUDE.md 会在 /compact 后从磁盘重新读取并注入；子目录里的嵌套 CLAUDE.md 不会自动重新注入，只有下次 Claude 读取那个子目录下的文件时才会重新加载。

一份可直接改造的 CLAUDE.md 模板

下面这份模板刻意保持短小。真正落地时，不要照抄每一项，而是把它改成能约束你项目行为的事实。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# CLAUDE.md

## Project Overview

- This is a Hugo site. Content lives under `content/post/<slug>/index.md`.
- Front matter uses `authors`, `summary`, `lastmod`, `type: blog`, and `image`.

## Commands

- Install dependencies with `pnpm install`.
- Run local validation with `hugo --destination /tmp/hugo-check`.
- Do not commit generated `public/` output unless explicitly requested.

## Editing Rules

- Keep changes scoped to the user request.
- Match existing front matter and Markdown style.
- Prefer concise Chinese prose for Chinese blog posts.
- Do not rewrite unrelated content.

## Verification

- For content changes, run a Hugo build into a temporary output directory.
- For code changes, run the narrowest relevant test command first.

好的 CLAUDE.md 不追求覆盖一切，而是把最容易遗忘、最容易重复解释、最容易造成返工的项目事实固定下来。它越像一份清晰的协作契约，Claude Code 就越不需要靠猜。

参考资料

How Claude remembers your project - Claude Code Docs