详解 CLAUDE.md：让 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
# 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`.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
## 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.

1
2
3
4
## 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 就越不需要靠猜。