用 CLAUDE.md 为项目建立持久记忆

每段 Claude Code 会话都从全新的上下文窗口开始——智能体并不记得你上一次的对话。CLAUDE.md 文件正是你跨会话传递知识的方式：它是一份用纯 Markdown 写成的持久指令文件，Claude 会在每段会话开始时读取它。

可以把它看作专为智能体写的项目“入职文档”。构建命令、各部分代码所在的位置、团队遵循的约定——任何你原本每次都要重新解释的内容，在这里写一次就够了。

你不必从零开始编写 CLAUDE.md。在 Claude Code 会话中运行：

/init

Claude 会分析你的代码库，并生成一份起始的 CLAUDE.md，其中包含它能自行发现的构建命令、测试说明与约定。如果 CLAUDE.md 已经存在，/init 会给出改进建议，而不会覆盖它。

把生成的文件当作初稿。再用 Claude 无法推断出的内容来完善它——架构决策、“始终执行 X”的规则，以及一位新队友需要的背景信息。

CLAUDE.md 可以存放在几个位置，每个位置作用域不同。Claude 会从你启动它的目录沿目录树向上查找，并加载找到的每一个文件，作用域从最广到最窄：

• 项目记忆——./CLAUDE.md 或 ./.claude/CLAUDE.md。团队共享，纳入版本控制。这是你最常用的一个。
• 用户记忆——~/.claude/CLAUDE.md。你在所有项目中的个人偏好（仅你自己）。
• 本地记忆——./CLAUDE.local.md。个人的、项目特定的笔记；请把它加入 .gitignore，以免被提交。
• 托管策略（Managed policy）——由 IT 部署的组织级文件（例如 macOS 上的 /Library/Application Support/ClaudeCode/CLAUDE.md）。

越靠近你工作目录的文件越晚被读取，因此项目指令会叠加在用户指令之上。

目标是写入 Claude 在每段会话中都应记住的事实与约定——而不是分步骤的操作流程。好的条目具体且可验证：

• 构建与测试命令：“提交前运行 npm test。”
• 约定：“使用 2 个空格缩进。”
• 项目结构：“API 处理器位于 src/api/handlers/。”
• 这个仓库特有的“始终执行 X”规则。

应当省略的内容：

• 多步骤的操作流程或任务特定的工作流 → 改为制作一个 Skill，让它只在相关时加载。
• 只对代码库某一部分有意义的指令 → 改用 .claude/rules/ 中的路径限定规则。
• 含糊的指导，比如“把代码格式化得好看些”或“测试你的改动”——太模糊，难以可靠遵循。

让每个 CLAUDE.md 保持在 约 200 行以内：它在每段会话中都会被完整载入，臃肿的文件会消耗上下文，反而降低 Claude 的遵循程度。使用 Markdown 标题和要点，让智能体能像你一样快速浏览它。

随着工作推进，你会发现需要补充的内容——Claude 重复犯的某个错误，或你反复输入的某条纠正。要查看和编辑你的记忆文件，运行：

/memory

/memory 会列出当前会话中加载的每一个 CLAUDE.md、CLAUDE.local.md 和规则文件，并允许你在编辑器中打开其中任意一个。（这也是确认某个文件确实被加载的最快方式——如果它不在列表里，Claude 就看不到它。）你也可以直接对 Claude 说*“把这条加到 CLAUDE.md 里”*，它会替你修改文件。