---
title: "使用记忆机制"
description: "Claude Code 的记忆分成 CLAUDE.md 和 auto memory（自动记忆）。学会文件位置、加载顺序、@import、.claude/rules、/memory、claudeMdExcludes 和排障边界。"
canonical: "https://xiangyugongzuoliu.com/tag/claude-code"
verifiedAt: "2026-05-08"
---

Claude Code 的记忆不是一个神秘数据库，而是每次会话开始时被装进上下文的一组说明。你把规则写清楚，它就少走弯路；你把规则写乱，它会把混乱也带进下一次工作。——Aaron

> [!NOTE]
> **这一章用 15 分钟换什么**：你已经知道 settings（设置）和 permissions（权限）管配置与权限。现在补上另一半：Claude 每次开始时“知道什么”。读完你应该能判断规则该写进 `CLAUDE.md`、`.claude/rules/`、Skill、settings，还是交给 auto memory（自动记忆）。

## 1. 先划清边界：记忆是上下文，不是强制层

新手最容易把三件事混在一起：

- 记忆：告诉 Claude 项目结构、约定、偏好、经验。
- 配置：告诉 Claude Code 客户端如何运行，比如 scope（作用域）、环境变量、Hooks、模型、插件。
- 权限：控制工具调用能不能执行，比如 `Bash`、`Read`、`Edit`、`WebFetch`、MCP 工具。

`CLAUDE.md` 和 auto memory 都属于第一类。它们会影响 Claude 的判断，但不会像 `permissions.deny` 那样强制拦截工具。

如果你在 `CLAUDE.md` 写：

```md

## Security

- Never read `.env` files.
```

这是一条行为提醒。它有用，但不是安全边界。

如果你要真的阻止读取 `.env`，要写进 settings permissions：

```json
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}
```

> [!IMPORTANT]
> **第一性原理**：记忆让 Claude 更懂项目；权限限制 Claude Code 能调用什么工具。不要用记忆承担安全职责。

## 2. Claude Code 每次启动会装载什么

一个会话开始时，Claude Code 会把多种材料放进上下文窗口：

- 当前对话。
- 系统指令。
- 你启动位置相关的 `CLAUDE.md` / `CLAUDE.local.md`。
- 规则文件 `.claude/rules/*.md`。
- auto memory 的入口内容。
- 后续工具读到的文件、命令输出、网页内容。

可以把它理解成一条启动流水线：

| 顺序 | 加载内容 | 作用 |
|------|----------|------|
| 1 | 当前对话与系统指令 | 建立基础行为边界 |
| 2 | 工作目录相关的 `CLAUDE.md` / `CLAUDE.local.md` | 注入项目、用户和本地规则 |
| 3 | `.claude/rules/*.md` | 加载通用规则，或在匹配路径时按需加载 |
| 4 | auto memory 入口内容 | 带入本机学习记录 |
| 5 | 工具读取的新文件、命令输出、网页内容 | 随任务推进继续补上下文 |

这里最关键的是：上下文会被消耗。规则越多，占用越多；规则越模糊，遵循越不稳定。

> [!TIP]
> **不要追求“写全”**：`CLAUDE.md` 的目标不是把项目百科搬进去，而是把 Claude 每次都必须知道的少数事实写准。

## 3. 两套记忆：你写的，和 Claude 自己写的

Claude Code 官方把记忆分成两类。

```text
机制               谁写                 主要用途
----------------   ------------------   ------------------------------
CLAUDE.md          你或团队              项目规则、命令、架构、工作流
auto memory        Claude 自动维护       调试经验、偏好、反复纠正过的事
```

`CLAUDE.md` 更像项目手册。它适合放稳定、明确、团队可共享的内容：

- 项目结构。
- 构建、测试、发布命令。
- 代码风格。
- 命名约定。
- 常见工作流。
- 不该靠代码自动推断的团队规则。

Auto memory 更像 Claude 的本地笔记。它适合记录 Claude 在工作中学到的东西：

- 某个测试需要本地 Redis。
- 这个项目总是用 `pnpm`，不要用 `npm`。
- 某个模块的调试入口。
- 你多次纠正过的个人偏好。

> [!WARNING]
> **auto memory 不是团队规范**：它是本机本项目的学习记录，不会自动同步到其他机器，也不应该替代提交到仓库的项目说明。

## 4. `CLAUDE.md` 应该放在哪里

位置决定作用域。

```text
作用域             位置
----------------   --------------------------------------------------
组织级             macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
组织级             Linux / WSL: /etc/claude-code/CLAUDE.md
组织级             Windows: C:\Program Files\ClaudeCode\CLAUDE.md
项目共享           ./CLAUDE.md
项目共享           ./.claude/CLAUDE.md
用户全局           ~/.claude/CLAUDE.md
本地个人           ./CLAUDE.local.md
```

选择方式很直接：

- 所有机器、所有人都必须遵守：组织级 managed `CLAUDE.md`。
- 这个仓库所有协作者都应该知道：项目 `CLAUDE.md` 或 `.claude/CLAUDE.md`。
- 只有你自己所有项目都要用：`~/.claude/CLAUDE.md`。
- 只有你自己、当前项目、当前机器要用：`CLAUDE.local.md`。

`CLAUDE.local.md` 应该加入 `.gitignore`。它适合写本机端口、个人测试账号名、个人习惯、临时实验说明。

如果你设置了 `CLAUDE_CONFIG_DIR`，官方文档里的 `~/.claude` 路径会整体移动到那个目录下。排障时要先确认这一点，否则你可能一直在看错误的配置目录。

> [!CAUTION]
> **不要把个人偏好提交到项目记忆**：你喜欢的编辑器、端口、测试数据、别名，不一定是团队规则。

## 5. 什么时候该写进 `CLAUDE.md`

官方给的判断很实用：你本来会反复向 Claude 解释的东西，就应该沉淀进 `CLAUDE.md`。

适合写入：

- Claude 第二次犯同一个项目级错误。
- 代码审查指出它本应知道的约定。
- 新同事也需要知道的启动、测试、发布流程。
- 项目结构不明显，靠文件名很难推断。
- 某个目录有强规则，比如 API handler、数据库迁移、支付逻辑。

不适合写入：

- 一次性任务背景。
- 长篇会议纪要。
- 密钥、账号、token。
- 复杂操作 SOP 的完整正文。
- 只对某个文件类型生效的规则。
- Claude 自动发现即可的普通代码事实。

多步 SOP 更适合做 Skill。只对部分路径生效的规则，更适合 `.claude/rules/`。

> [!IMPORTANT]
> **目标长度**：官方建议每个 `CLAUDE.md` 目标控制在 200 行以内。超过这个范围，规则会占用更多上下文，也更容易互相冲突。

## 6. 怎么写一个有效的 `CLAUDE.md`

有效的记忆有三个特点：

- 具体：能被验证。
- 稳定：下周仍然成立。
- 简短：每句话都值得进入上下文。

弱规则长这样：

```md

## Coding

- Write clean code.
- Be careful.
- Follow best practices.
```

这类规则几乎不可执行。它们听起来正确，但 Claude 无法稳定判断“clean”和“best”到底是什么。

更好的写法是：

```md

## Project Commands

- Use `pnpm install` to install dependencies.
- Use `pnpm test` before changing files under `src/core/`.
- Use `pnpm build` before opening a pull request.

## Code Conventions

- API handlers live under `src/api/handlers/`.
- Database migrations live under `db/migrations/`.
- Public React components use PascalCase filenames.
- Do not edit generated files under `src/generated/`.

## Workflow

- Before changing payment code, read `docs/payment-flow.md`.
- After editing GraphQL schema, run `pnpm codegen`.
```

这份文件不追求完整解释项目，只告诉 Claude 不能靠猜的关键事实。

> [!TIP]
> **写法标准**：用动词开头，写可验证动作。少写价值观，多写路径、命令、条件和例外。

## 7. `/init` 可以帮你生成起点

新项目可以直接在 Claude Code 里运行：

```text
/init
```

官方说明：`/init` 会分析代码库，生成或改进项目 `CLAUDE.md`，通常会包含构建命令、测试命令和项目约定。已有 `CLAUDE.md` 时，它会建议改进，而不是简单覆盖。

官方还提供了一个新流程开关：

```bash
CLAUDE_CODE_NEW_INIT=1 claude
```

启用后，`/init` 会以更交互的多阶段方式询问要设置哪些 artifact，比如 `CLAUDE.md`、Skills、Hooks。它会先探索代码库，再提出可审查的方案。

> [!WARNING]
> **不要盲收 `/init` 的输出**：它能发现命令和结构，但无法知道团队真正的约定。生成后要删掉噪音、补上隐性规则。

## 8. `@import`：拆文件，不等于省上下文

`CLAUDE.md` 可以用 `@path` 导入其他文件：

```md

## Project Context

- See @README.md for product overview.
- See @package.json for script names.
- See @docs/release-checklist.md before release work.
```

关键规则：

- 相对路径按包含 import 的文件解析，不按当前 shell 工作目录解析。
- 绝对路径和 `~` 路径也可以使用。
- 导入可以递归。
- 最大递归深度是 5 层。
- 首次遇到项目外部导入时，Claude Code 会弹出确认。
- 如果用户拒绝外部导入，后续不会继续读取那些外部文件。

拆 import 适合组织内容，但它不会减少上下文。被导入的内容仍然会在启动时展开并进入上下文。

> [!IMPORTANT]
> **不要用 import 假装瘦身**：如果一个规则不需要每次加载，应该改成 path-scoped rule 或 Skill，而不是换个文件名导入。

## 9. `AGENTS.md` 怎么兼容

官方口径很明确：Claude Code 读取 `CLAUDE.md`，不是直接读取 `AGENTS.md`。

如果一个仓库已经有 `AGENTS.md`，更稳的方式是新建一个 `CLAUDE.md` 导入它：

```md
@AGENTS.md

## Claude Code

- Use plan mode before changing files under `src/billing/`.
- Run `/memory` when debugging instruction loading.
```

这样其他 agent 仍然读 `AGENTS.md`，Claude Code 通过 `CLAUDE.md` 读同一份基础规则，再追加 Claude-specific 说明。

> [!TIP]
> **兼容优先级**：不要维护两份互相复制的规则。让 `CLAUDE.md` 导入 `AGENTS.md`，再只写 Claude Code 特有差异。

## 10. 加载顺序：越靠近启动目录，越晚进入上下文

Claude Code 会从当前工作目录一路向上查找：

- `CLAUDE.md`
- `CLAUDE.local.md`

假设你在这个目录启动：

```text
/repo/apps/web
```

可能加载：

```text
/repo/CLAUDE.md
/repo/CLAUDE.local.md
/repo/apps/CLAUDE.md
/repo/apps/CLAUDE.local.md
/repo/apps/web/CLAUDE.md
/repo/apps/web/CLAUDE.local.md
```

官方说明的顺序是从更高层目录到当前目录。同一目录里，`CLAUDE.local.md` 接在 `CLAUDE.md` 后面。也就是说，越靠近启动位置，越晚进入上下文，通常更容易影响最终行为。

这不是“覆盖”。所有发现的文件会拼接进上下文。冲突规则仍然是冲突规则。

| 加载顺序 | 示例文件 | 含义 |
|----------|----------|------|
| 1 | `/repo/CLAUDE.md` | 仓库根规则先进入上下文 |
| 2 | `/repo/CLAUDE.local.md` | 仓库根本地规则跟随进入 |
| 3 | `/repo/apps/CLAUDE.md` | 更靠近启动目录的规则更晚进入 |
| 4 | `/repo/apps/CLAUDE.local.md` | 对应层级的本地规则跟随进入 |
| 5 | `/repo/apps/web/CLAUDE.md` | 当前启动目录规则最后进入 |
| 6 | `/repo/apps/web/CLAUDE.local.md` | 当前目录本地规则最后进入 |

> [!WARNING]
> **冲突不会自动消失**：上层说用 `npm`，下层说用 `pnpm`，Claude 可能按更近规则执行，也可能在复杂任务里摇摆。最好的排障不是猜优先级，而是删掉冲突。

## 11. 子目录规则是按需加载的

启动时，Claude 不会把当前工作目录下面所有子目录的 `CLAUDE.md` 都读进来。

如果你在 `/repo` 启动：

```text
/repo/CLAUDE.md
/repo/frontend/CLAUDE.md
/repo/backend/CLAUDE.md
```

启动时会读 `/repo/CLAUDE.md`。`frontend/CLAUDE.md` 和 `backend/CLAUDE.md` 会在 Claude 读取对应子目录文件时按需加载。

这对大型 monorepo 很重要：你不需要把所有团队规则都塞进根文件，也不需要让前端任务一开始就加载后端全部规则。

> [!TIP]
> **大型仓库策略**：根 `CLAUDE.md` 写全局最小规则；具体目录规则放在对应子目录或 `.claude/rules/`。

## 12. 附加目录不会默认加载记忆

`--add-dir` 可以给 Claude 额外目录访问权限：

```bash
claude --add-dir ../shared-config
```

但官方说明：默认不会加载这个附加目录里的 `CLAUDE.md`。

如果你想同时加载附加目录里的记忆文件，需要设置：

```bash
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
```

这会加载附加目录中的：

- `CLAUDE.md`
- `.claude/CLAUDE.md`
- `.claude/rules/*.md`
- `CLAUDE.local.md`

如果你用 `--setting-sources` 排除了 local，附加目录里的 `CLAUDE.local.md` 也会被跳过。

> [!CAUTION]
> **别把访问权限和记忆加载混为一谈**：`--add-dir` 让 Claude 可以访问目录，不代表目录里的说明自动进入上下文。

## 13. `.claude/rules/`：给大型项目拆规则

当 `CLAUDE.md` 变长，第一反应不应该是继续加标题，而是把路径相关规则拆到 `.claude/rules/`。

推荐结构：

```text
your-project/
  .claude/
    CLAUDE.md
    rules/
      code-style.md
      testing.md
      security.md
      frontend/
        react.md
      backend/
        api.md
```

规则文件是普通 Markdown。官方说明所有 `.md` 文件会被递归发现。

没有 `paths` frontmatter 的规则，会像 `.claude/CLAUDE.md` 一样每次加载。

带 `paths` 的规则，只在 Claude 处理匹配文件时加载：

```md
---
paths:
  - "src/api/**/*.ts"
  - "tests/**/*.test.ts"
---

## API Development Rules

- All API handlers must validate input.
- Use the shared error response format.
- Update OpenAPI comments when adding endpoints.
```

适合用 path rules 的场景：

- `src/api/**` 有接口约定。
- `db/migrations/**` 有迁移规则。
- `packages/mobile/**` 和 `packages/web/**` 使用不同框架。
- `*.test.ts` 必须走固定测试工具。
- `docs/**` 有写作和链接规则。

> [!IMPORTANT]
> **path rule 不是权限规则**：它决定什么时候加载说明，不决定文件能不能读写。文件访问边界仍然由 permissions 和 sandbox 控制。

## 14. user-level rules 与项目规则的关系

你也可以把个人规则放在：

```text
~/.claude/rules/
```

这适合写个人偏好，例如：

- 所有项目默认先读 `CLAUDE.md`。
- 回答默认使用简体中文。
- 代码审查默认先列风险。

官方说明：user-level rules 先加载，project rules 后加载，所以项目规则优先级更高。

这个设计是合理的。你可以有全局习惯，但项目约定应该能压过个人习惯。

> [!TIP]
> **个人规则要少而稳**：全局规则会进入很多项目，写得越多，越容易和项目规则冲突。

## 15. 规则支持 symlink，但要避免环

`.claude/rules/` 支持 symlink。你可以把一套共享规则维护在一个目录，然后链接到多个项目：

```bash
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md
```

官方说明 symlink 会正常解析，循环 symlink 会被检测并处理。

这个能力适合个人多仓库或组织模板，但不适合把所有规则都做成全局大包。共享规则越多，越要保持单一职责。

> [!WARNING]
> **共享规则不是越多越好**：能模板化的是基础约定，项目差异仍然应该留在项目里。

## 16. `claudeMdExcludes`：跳过不相关的记忆

大型 monorepo 里，经常会遇到祖先目录或其他团队的 `CLAUDE.md` 被加载，结果规则不相关甚至冲突。

官方提供 `claudeMdExcludes`：

```json
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}
```

建议放在：

```text
.claude/settings.local.json
```

原因是排除哪些父级规则，往往和你当前机器、当前工作方式有关，不一定应该提交给团队。

注意两点：

- 匹配的是绝对文件路径。
- managed policy 的 `CLAUDE.md` 不能被排除。

> [!CAUTION]
> **不要用 exclude 掩盖真实冲突**：如果团队都被同一条错误规则影响，应该修改规则源头，而不是每个人各自 local exclude。

## 17. block HTML comments 会被剥离

官方说明：`CLAUDE.md` 里的 block-level HTML comments 会在注入上下文前被剥离。

这意味着你可以给人类维护者留备注：

```md
<!-- This section is for maintainers and will not enter Claude context. -->

## Build Commands

- Use `pnpm build` before release.
```

这些注释不会消耗上下文 token。代码块里的注释会保留；你直接用 Read 工具打开 `CLAUDE.md` 时，也仍然能看到注释。

> [!TIP]
> **维护说明和执行规则分开**：给人看的解释可以放 HTML comment，给 Claude 执行的规则放正文。

## 18. Auto memory 默认开启

Auto memory 是 Claude 自己维护的跨会话笔记。官方说明它从 Claude Code v2.1.59 起可用，并且默认开启。

你可以用三种方式控制：

```text
方式                         用途
--------------------------   --------------------------------
/memory                      会话内查看、编辑、切换 auto memory
autoMemoryEnabled            在项目 settings 里启用或关闭
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1   用环境变量关闭
```

关闭示例：

```json
{
  "autoMemoryEnabled": false
}
```

Auto memory 不会每个会话都写。Claude 会判断某条信息未来是否有用，再决定是否保存。

> [!IMPORTANT]
> **auto memory 是辅助，不是审计系统**：不要假设 Claude 一定记录了某个结论，也不要假设它永远不会记录你给过的信息。

## 19. Auto memory 存在哪里

默认位置是：

```text
~/.claude/projects/<project>/memory/
```

目录里通常有：

```text
memory/
  MEMORY.md
  debugging.md
  api-conventions.md
  other-topic-files.md
```

`<project>` 由 git repository 推导。同一个仓库里的不同 worktree 和子目录会共享同一个 auto memory 目录。仓库外则按 project root 推导。

Auto memory 是机器本地的：

- 不会自动跨机器同步。
- 不会自动进入 GitHub。
- 不会自动进入云端开发环境。
- 不会替代项目 `CLAUDE.md`。

如果你要改存储位置，可以在 user settings 写：

```json
{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}
```

官方限制：`autoMemoryDirectory` 必须是绝对路径或以 `~/` 开头，并且只接受 policy、user settings 或命令行 `--settings`。不能放在 project/local settings 里。

这个限制是安全设计：仓库不能通过提交项目配置，把你的个人记忆重定向到敏感路径。

> [!CAUTION]
> **不要同步整个 auto memory 目录**：里面是 Claude 的本地学习笔记，可能包含调试路径、命令输出、偏好和项目细节。团队共识应该写入仓库的 `CLAUDE.md`。

## 20. `MEMORY.md` 不是无限加载

Auto memory 目录里的入口文件是：

```text
MEMORY.md
```

官方说明：每次会话开始只加载 `MEMORY.md` 的前 200 行，或前 25KB，取较小者。

详细主题文件不会启动时全部加载。Claude 会在需要时用标准文件工具按需读取，比如：

- `debugging.md`
- `architecture.md`
- `test-fixtures.md`
- `api-conventions.md`

这也是为什么 `MEMORY.md` 应该像索引，而不是长文档。

> [!TIP]
> **auto memory 的好结构**：`MEMORY.md` 保持短索引，细节拆到 topic files。否则超过阈值的内容一开始就不会进入上下文。

## 21. `/memory` 是排障入口

当你不确定 Claude 到底读了什么，先运行：

```text
/memory
```

官方说明 `/memory` 可以：

- 列出当前会话加载的 `CLAUDE.md`。
- 列出 `CLAUDE.local.md`。
- 列出 rules 文件。
- 切换 auto memory。
- 打开 auto memory 文件夹。
- 选择文件用编辑器打开。

你也可以直接让 Claude 记住某条经验：

```text
Remember that this project uses pnpm, not npm.
```

如果你想把内容写进 `CLAUDE.md`，表达要更明确：

```text
Add this rule to CLAUDE.md: use pnpm test before editing src/core.
```

> [!IMPORTANT]
> **排障先看 `/memory`**：不要凭感觉判断 Claude 是否加载了某个文件。先让当前会话列出来。

## 22. 记忆、rules、Skill、settings 怎么选

把内容放错地方，是 Claude Code 项目越用越乱的主要原因。

```text
需求                                      放哪里
---------------------------------------   --------------------------------
所有人每次都要知道的项目规则              CLAUDE.md
只对某些路径或文件类型生效的规则          .claude/rules/*.md
跨项目个人表达偏好                        ~/.claude/CLAUDE.md 或 ~/.claude/rules/
一次可复用的复杂工作流                    Skill
工具权限、环境变量、Hooks、模型、插件     settings.json
MCP server 连接                            .mcp.json 或 MCP 配置
Claude 从纠正中学到的本机经验             auto memory
企业强制策略                              managed settings 或 managed CLAUDE.md
```

几个判断句：

- 要强制执行，用 settings / permissions。
- 要按路径加载，用 rules。
- 要复用流程，用 Skill。
- 要团队共享，用 project scope。
- 要个人保留，用 user 或 local scope。
- 要 Claude 自己学，用 auto memory。

> [!TIP]
> **最稳结构**：根 `CLAUDE.md` 保持短；复杂流程做 Skill；路径差异放 rules；安全边界放 permissions。

## 23. 组织级 `CLAUDE.md` 和 managed settings 分工

组织可以部署 managed `CLAUDE.md`，让所有用户都加载组织级说明。

适合写进 managed `CLAUDE.md`：

- 公司代码风格。
- 数据处理提醒。
- 合规要求说明。
- 代码审查原则。
- 内部仓库结构说明。

不适合只写在 managed `CLAUDE.md`：

- 禁止某个工具。
- 禁止读取某类路径。
- 强制 sandbox。
- 强制登录方式。
- 强制组织账号。

这些应该进 managed settings，因为 settings 由客户端执行，不能靠 Claude 自觉。

> [!IMPORTANT]
> **组织策略分两层**：行为指导写 managed `CLAUDE.md`；硬约束写 managed settings。

## 24. `/compact` 后为什么像忘了

上下文会填满，Claude Code 会压缩旧上下文。用户也可以运行：

```text
/compact
```

官方说明：项目根 `CLAUDE.md` 会在 compaction 后从磁盘重新读取并重新注入会话。

但嵌套目录里的 `CLAUDE.md` 不会自动全部重新注入。它们需要等 Claude 再次读取对应子目录里的文件时触发。

所以 `/compact` 后出现“忘了某条规则”，常见原因是：

- 那条规则只在对话里说过，没有写进 `CLAUDE.md`。
- 那条规则在嵌套目录 `CLAUDE.md` 里，但对应目录还没重新触发。
- 规则太模糊或和其他规则冲突。
- 规则来自 auto memory topic file，启动时没有直接加载。

> [!WARNING]
> **不要把会话内提醒当长期规则**：重要规则必须落文件，否则压缩、恢复、换会话后都可能丢。

## 25. 常见故障：Claude 不听 `CLAUDE.md`

按这个顺序查：

1. 运行 `/memory`，确认文件真的被列出。
2. 确认你在正确目录启动 Claude Code。
3. 检查是否设置了 `CLAUDE_CONFIG_DIR`。
4. 检查是否被 `claudeMdExcludes` 排除。
5. 检查规则是不是太长、太泛、互相冲突。
6. 检查相关规则是不是 path-scoped，还没有被触发。
7. 检查是否刚 `/compact`，嵌套规则还没重新加载。
8. 必要时用 `InstructionsLoaded` hook 记录加载了哪些 instruction files。

如果你想把某段说明提升到系统提示词层级，官方提到可以用 `--append-system-prompt`。但它需要每次 invocation 都传入，更适合脚本和自动化，不适合作为普通交互项目的长期规则。

> [!CAUTION]
> **不要用更强提示词压烂规则体系**：先修文件位置、加载顺序和冲突，再考虑 system prompt 级别的注入。

## 26. 常见故障：不知道 auto memory 写了什么

直接运行：

```text
/memory
```

然后打开 auto memory folder。

Auto memory 是普通 Markdown，你可以：

- 读取。
- 编辑。
- 删除。
- 拆分 topic。
- 删除不该保留的敏感内容。

当界面出现 `Writing memory` 或 `Recalled memory`，说明 Claude 正在写入或读取 auto memory 目录。

> [!WARNING]
> **定期审计记忆**：不要把路径、账号、内部细节、一次性判断长期留在 auto memory 里。

## 27. 一个新项目的推荐落地顺序

新项目不要一上来写大而全的规则。按这个顺序收敛：

<Steps>

<Step>
### 项目根运行 `/init`
让 Claude Code 先扫一遍代码库，生成 `CLAUDE.md` 起点（含构建/测试命令、项目结构推断）。
</Step>

<Step>
### 删除自动生成里的废话
`/init` 输出会有"clean code / best practices"这类不可执行规则，直接删；猜错的命令路径也删。
</Step>

<Step>
### 保留稳定关键事实
构建、测试、目录约定、命名、生成文件、发布边界——这些靠 Claude 自己推断不稳定的事实留下。
</Step>

<Step>
### 把根 `CLAUDE.md` 控制在 200 行以内
官方建议；超过就拆。
</Step>

<Step>
### 路径规则拆到 `.claude/rules/`
按 `src/api/**` / `db/migrations/**` 等路径切，加 `paths` frontmatter 让规则按需加载。
</Step>

<Step>
### 复杂流程做成 Skill
多步 SOP（如 release checklist、bug triage）放 Skill，不挤进 `CLAUDE.md`。
</Step>

<Step>
### 权限写进 settings.json 或 managed settings
安全边界（不能读 `.env`、不能 `rm -rf`、不能 push 到 main）走 permissions deny，不靠 `CLAUDE.md` 自觉。
</Step>

<Step>
### 个人偏好放 user/local scope
你的端口、测试账号、个人习惯走 `~/.claude/CLAUDE.md` 或 `CLAUDE.local.md`，不污染团队规则。
</Step>

<Step>
### `/memory` 验证当前会话加载了什么
跑一次 `/memory`，确认所有该加载的文件都在列表里，没有意外的祖先或外部规则。
</Step>

</Steps>

最小可用版本长这样：

```text
your-project/
  CLAUDE.md
  .claude/
    settings.json
    rules/
      testing.md
      security.md
```

> [!TIP]
> **先短后准**：能稳定减少误操作的 30 行规则，比没人能维护的 300 行手册更有价值。

## 28. 自检清单

学完这一章，你应该能完成这些判断：

- 我能解释为什么记忆不是权限系统。
- 我能判断一条规则该放 `CLAUDE.md`、`.claude/rules/`、Skill、settings 还是 auto memory。
- 我知道 `CLAUDE.local.md` 应该 gitignored。
- 我知道 `@import` 会进入上下文，不是省 token。
- 我知道 Claude Code 读取 `CLAUDE.md`，不是直接读取 `AGENTS.md`。
- 我知道子目录 `CLAUDE.md` 是按需加载，不是启动时全量加载。
- 我知道 `--add-dir` 不会默认加载附加目录记忆。
- 我知道 auto memory 默认位置和 `MEMORY.md` 启动加载限制。
- 我能用 `/memory` 排查当前会话到底加载了什么。
- 我能把安全边界放进 permissions，而不是只写进记忆。

## 29. 术语速查

- `CLAUDE.md`：Claude Code 每次会话加载的长期说明文件。
- `CLAUDE.local.md`：当前项目的个人本地说明，通常不提交。
- `.claude/CLAUDE.md`：项目级说明的另一种官方位置。
- `.claude/rules/`：可按路径或主题拆分的规则目录。
- `paths frontmatter`：控制某条 rule 何时按文件路径加载。
- `@import`：在 `CLAUDE.md` 中导入其他文件的语法。
- `auto memory`：Claude 自动维护的跨会话本地笔记。
- `MEMORY.md`：auto memory 入口索引文件。
- `/memory`：查看、编辑、切换记忆的命令。
- `claudeMdExcludes`：排除某些 `CLAUDE.md` 或 rules 的 settings 字段。
- `InstructionsLoaded hook`：调试 instruction 文件加载的 hook。
- `managed CLAUDE.md`：组织级统一下发的说明文件。

## 官方来源

- [How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory)
- [Claude Code settings](https://code.claude.com/docs/en/settings)
- [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works)

<Cards>
  <Card href="/docs/claude-code/official/01-core-capabilities/mcp" title="连接 MCP 服务" description="记忆决定 Claude 知道什么；MCP 决定 Claude 能连接哪些外部工具和数据源。下一章继续讲连接边界。" />
  <Card href="/docs/claude-code/official/01-core-capabilities/permissions" title="管理权限（上一篇）" description="如果你还没分清记忆和权限，先回到 permissions：那一章讲真正的工具调用边界。" />
  <Card href="/docs/claude-code/understanding/03-memory" title="深度理解：记忆与上下文" description="想继续理解为什么上下文会影响 AI 编程质量，可以读理解篇里的 Memory / Context。" />
</Cards>
