记忆与 CLAUDE.md

每个 Claude Code 会话都从全新的上下文窗口开始。有两种机制能跨会话传递知识：

• CLAUDE.md 文件：你写的持久指令。Claude 也可以读取仓库里的 AGENTS.md，单独读或和 CLAUDE.md 一起读
• 自动记忆（auto memory）：Claude 根据你的纠正和偏好自己写的笔记

CLAUDE.md 与自动记忆

两者互补，都在每次对话开始时加载。Claude 把它们当作上下文，而不是强制执行的配置——想无论 Claude 怎么决定都拦住某个动作，请用 PreToolUse Hook。指令越具体、越简洁，Claude 遵守得越稳定。

CLAUDE.md 文件

CLAUDE.md 是纯文本 markdown 文件，Claude 在每次会话开始时读取。

什么时候往里加

把它当作「你否则要反复解释的内容」的存放处。出现下面情况就该加：

• Claude 第二次犯同样的错
• 代码评审指出了 Claude 本该了解的代码库知识
• 你在对话里输入了和上次一样的纠正或说明
• 新同事需要同样的背景才能上手

只放每次会话都该知道的事实：构建命令、约定、项目结构、「总是做 X」的规则。多步骤流程或只和代码库某一部分相关的内容，放到 Skill 或按路径生效的规则里。

放在哪里

按加载顺序从最宽到最具体排列，所以项目指令出现在用户指令之后：

工作目录及其上级目录里的 CLAUDE.md 在启动时加载；子目录里的在 Claude 读取该目录下文件时按需加载。

创建项目 CLAUDE.md

在 ./CLAUDE.md 或 ./.claude/CLAUDE.md 里写下适用于所有人的指令：构建和测试命令、编码规范、架构决策、命名约定、常见工作流。在会话里运行 /context，在 Memory files 下确认文件已加载。

运行 /init 可以自动生成起始版本：Claude 会分析代码库，写入它发现的构建命令、测试说明和项目约定。已有 CLAUDE.md 时 /init 会建议改进而不是覆盖。

写出有效的指令

写得要具体到可以验证：

• 「使用 2 空格缩进」，而不是「把代码格式化好」
• 「提交前运行 npm test」，而不是「测试你的改动」
• 「API 处理器放在 src/api/handlers/」，而不是「保持文件有条理」

保持简短、有结构、前后一致：

• 大小：每个 CLAUDE.md 控制在 200 行以内。更长的文件占用更多上下文、降低遵守度。只对部分代码有意义的内容移到按路径生效的规则。@ 导入有助于组织，但不会减少上下文成本，因为被导入的文件同样在启动时加载
• 结构：用 markdown 标题和项目符号分组，比大段文字更容易被遵循
• 一致：两条指令互相矛盾时，Claude 可能随便选一条。定期检查 CLAUDE.md、子目录里的 CLAUDE.md 和 .claude/rules/，清除过时或冲突的内容。可以运行 /doctor prompt-audit 让 Claude 帮你检查（需要 v2.1.283 或更新版本）

导入其他文件

CLAUDE.md 可以用 @path/to/import 语法导入其他文件，被导入文件在启动时展开并和引用它的 CLAUDE.md 一起加载。相对路径相对于包含该导入的文件解析，导入可以递归，最多四层。

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

导入解析会跳过 markdown 行内代码和代码块；想提到某个路径但不导入，用反引号包起来。

不想提交进版本控制的个人偏好，写进项目根目录的 CLAUDE.local.md（记得加入 .gitignore）。如果在同一仓库的多个 git worktree 之间工作，可以从家目录导入一个文件来共享个人指令：

# Individual Preferences
- @~/.claude/my-project-instructions.md

路径解析到工作目录之外的导入属于「外部导入」。项目首次遇到时会弹出批准对话框，列出这些文件；拒绝后导入保持禁用，对话框不会再出现。

CLAUDE.md 如何加载

Claude Code 从当前工作目录及其上的每一级目录加载 CLAUDE.md 和 CLAUDE.local.md。在 foo/bar/ 运行，就会加载 foo/bar/CLAUDE.md、foo/CLAUDE.md 及同目录的 CLAUDE.local.md。

所有发现的文件会拼接进上下文，而不是互相覆盖，顺序从文件系统根目录向下到工作目录，所以离你启动位置越近的指令越靠后。同一目录里 CLAUDE.local.md 排在 CLAUDE.md 之后。

HTML 块注释（<!-- 维护者备注 -->）在注入上下文前会被剥离，可以给人类维护者留言而不消耗 token（代码块内的注释会保留）。

--add-dir 添加的额外目录默认不加载其 CLAUDE.md；设置环境变量 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 才会加载：

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

用 .claude/rules/ 组织规则

大项目可以把指令拆成多个文件放进 .claude/rules/。每个文件讲一个主题，文件名要有描述性，如 testing.md、api-design.md；所有 .md 文件会被递归发现，可以按 frontend/、backend/ 分子目录。

your-project/
├── .claude/
│   ├── CLAUDE.md           # 项目主指令
│   └── rules/
│       ├── code-style.md   # 代码风格
│       ├── testing.md      # 测试约定
│       └── security.md     # 安全要求

没有 paths 前置信息的规则在启动时加载，优先级与 .claude/CLAUDE.md 相同。

按路径生效的规则：用 YAML 前置信息里的 paths 字段把规则限定到特定文件，只有 Claude 处理匹配文件时才生效：

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

没有 paths 的规则无条件加载。paths 支持 glob，例如 **/*.ts（任意目录的 TypeScript 文件）、src/**/*（src/ 下所有文件）、*.md（项目根的 markdown）；可以写多个模式，也支持花括号展开，如 "src/**/*.{ts,tsx}"。paths 是 Claude Code 从规则里读取的唯一字段。

.claude/rules/ 支持符号链接，可以维护一套共享规则链接进多个项目；但指向工作目录之外的符号链接会被当作外部导入，需要先批准。要让个人规则对本机所有项目生效，放进 ~/.claude/rules/；用户级规则先于项目规则加载，两者冲突时 Claude 可能遵循任意一个，所以要保持一致。

大型团队的管理

• 组织级 CLAUDE.md：把文件放在托管策略位置，用 MDM、组策略或 Ansible 等分发；这个文件不能被个人设置排除。也可以用托管设置里的 claudeMd 键直接写入内容。技术性强制（拦截工具、沙箱、环境变量）放托管设置，行为性指导（代码风格、合规提醒）放托管 CLAUDE.md
• 排除某些 CLAUDE.md：在大型 monorepo 里，用 claudeMdExcludes 设置按路径或 glob 跳过不相关的文件，数组在各设置层之间合并；托管策略的 CLAUDE.md 不能被排除

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

AGENTS.md

Claude Code 可以直接把 AGENTS.md 当作项目指令读取（需要 v2.1.277 或更新版本），为其他编码智能体准备的仓库无需额外加 CLAUDE.md。默认行为：

想改默认行为，在会话里输入 /config，把 Project instructions 设为：claude-md-or-agents-md（默认）、claude-md-and-agents-md（两者一起读）、claude-md（只读 CLAUDE.md）或 managed-only（只读组织的托管 CLAUDE.md 和自动记忆）。

如果想让 AGENTS.md 继续作为各工具共享的唯一文件，可以在它旁边的 CLAUDE.md 里导入它，并在下面补充 Claude 专属指令：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

也可以用符号链接 ln -s AGENTS.md CLAUDE.md，但 Edit/Write 工具拒绝通过符号链接写入，且 Windows 上创建符号链接需要管理员权限或开发者模式，那种情况请用 @AGENTS.md 导入。

从其他工具迁移：/init 会读取 .cursor/rules/、.cursorrules、.github/copilot-instructions.md 等并融入生成的 CLAUDE.md；/import 可把受支持的编码智能体配置（含 MCP 服务器、命令、子智能体和 Skill）导入 Claude Code（需要 v2.1.213 或更新版本）。

自动记忆

自动记忆让 Claude 在不需要你写任何东西的情况下跨会话积累知识。它会为自己保存四类笔记，在记忆文件的前置信息里用 type 字段标记：

• user：你的角色、专长和工作偏好
• feedback：你给 Claude 的纠正和你确认过的做法
• project：进行中的工作、截止时间和无法从代码或 git 历史推出的决策
• reference：项目之外信息的位置，如工单系统或看板

能从代码库推出的内容（架构、文件路径、调试修复）和 CLAUDE.md 里已有的内容，它会跳过。并不是每次会话都会保存，Claude 会判断这条信息对将来的对话是否有用。

开关：默认开启。在会话里用 /memory 切换，或在设置里写 "autoMemoryEnabled": false；也可以设置环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

存储位置：每个项目一个记忆目录 ~/.claude/projects/<project>/memory/，<project> 由 git 仓库推导，所以同一仓库的所有 worktree 和子目录共享同一份。想换位置，在 settings.json 里设置 autoMemoryDirectory（必须是绝对路径或以 ~/ 开头）。

~/.claude/projects/<project>/memory/
├── MEMORY.md           # 索引，每条记忆一行，每次会话都加载
├── user_role.md        # 一条记忆
├── feedback_testing.md # 一条记忆
└── ...

工作方式：每次对话开头加载 MEMORY.md 的前 200 行或 25KB（以先到者为准）；详细内容放在单独的主题文件里，启动时不加载，Claude 需要时用标准文件工具按需读取。自动记忆是本机的，不会跨机器或云端环境同步；主对话的自动记忆不会加载进子智能体（fork 除外）。

自动记忆文件就是普通 markdown，随时可以编辑或删除。

用 /memory 查看和编辑

/memory 列出你的 CLAUDE.md、CLAUDE.local.md 等记忆文件位置，可以开关自动记忆、打开自动记忆文件夹；选中任一文件就在编辑器里打开（不存在的会先创建）。想知道本次会话实际加载了哪些文件，运行 /context。

让 Claude 记住某事（比如「永远用 pnpm，不用 npm」）会保存进自动记忆；想写进 CLAUDE.md，要直接说「把这个加到 CLAUDE.md」，或自己用 /memory 编辑。

排查记忆问题

Claude 没有遵循我的 CLAUDE.md：CLAUDE.md 是作为系统提示之后的用户消息送达的，不保证严格遵守。排查：

• 运行 /context，在 Memory files 下确认文件已加载
• 确认 CLAUDE.md 放在会被当前会话加载的位置
• 让指令更具体
• 检查各文件是否有互相冲突的指令
• 如果 Claude Code 自带的提交/PR 指导和你的冲突，用 includeGitInstructions 关闭内置的，用 attribution 设置署名文字

必须在固定时点执行的事（如每次提交前、每次改文件后），请写成 Hook。需要系统提示词级别的指令，用 --append-system-prompt（更适合脚本和自动化）。

我的 AGENTS.md 没加载：通常是路径上某处有 CLAUDE.md。依次检查：是否有 CLAUDE.md / .claude/CLAUDE.md / CLAUDE.local.md（~/.claude/CLAUDE.md 不算）；claude --version 是否 v2.1.277 以上；/config 里 Project instructions 是否被设成 claude-md 或 managed-only。用 /memory 看列表里有没有它的路径。

CLAUDE.md 太大：超过 200 行会占用更多上下文、降低遵守度；超过 4 MiB 的文件会被跳过。超长时启动和 /status 会警告。/doctor 会为已提交的 CLAUDE.md 提出精简建议：删掉能从代码库推出的内容（目录结构、依赖列表、架构概览），保留踩坑点、原因说明和与工具默认值不同的约定。

/compact 之后指令像是丢了：项目根的 CLAUDE.md 在压缩后会从磁盘重新读入；子目录里的 CLAUDE.md 和带 paths: 的规则会在 Claude 再次读取相关文件时重新加载。只在对话里说过的指令会丢，要持久就写进 CLAUDE.md。