CLAUDE.md 与项目记忆
Claude Code 的记忆是分层的文件：项目级 CLAUDE.md 写给团队和项目，用户级 ~/.claude/CLAUDE.md 记录你的跨项目个人偏好，配合 # 快捷记忆和 /memory 维护。
教程基准：Claude Code v2.1.224（当前最新版，核验于 2026-08-07） · 最后核验：2026-08-07 · 适用版本：auto memory 需要 v2.1.59+ · 官方文档
看权限为什么要有 CLAUDE.md
很多人第一次用 CC，会把所有要求都写在当前对话里。短任务还可以，长期项目很快就会失控：
- 每次都要重新解释项目结构。
- 每次都要重复说明哪些目录不能动。
- CC 容易忘记团队约定。
- 新会话不能继承重要规则。
- 同一个项目里，不同人写出来的要求不一致。
CLAUDE.md 解决的是“长期上下文”问题。它让 CC 进入项目后，先知道这个项目是什么、哪些边界不能碰、交付前要怎么检查。
更准确地说，CLAUDE.md 不是给人看的 README，而是给 CC 看的项目工作说明。
CLAUDE.md 适合写什么
- 项目是什么，主要技术栈是什么。
- 关键目录、入口文件和架构边界。
- 已确认存在的检查方式。
- 修改边界、安全要求和禁止事项。
- 代码审查清单、测试偏好、团队约定和任务结束汇报格式。
可以按这个结构写：
# Project Guide for Claude ## Project Overview - 这个项目是什么。 - 面向什么用户。 - 当前主要技术栈是什么。 ## Important Directories - 哪些目录是页面。 - 哪些目录是接口。 - 哪些目录是生成产物，不要手改。 ## Working Rules - 修改前先说明计划。 - 不做无关重构。 - 不新增依赖，除非用户确认。 - 不修改密钥、部署和生产配置。 ## Verification - 已确认的检查方式。 - 什么时候需要运行构建。 - 什么时候只需要静态检查。 ## Report Format - 修改了什么。 - 怎么验证。 - 还有什么风险。
不要写进 CLAUDE.md 的内容
- 临时任务，比如“本次只改首页”。
- 真实 API Key、Token、账号和密码。
- 没有在项目里确认过的命令。
- “代码要优雅”这种无法检查的空话。
- 用户的私人偏好，比如账号、手机号、内部链接和未公开资料。
- 可能过期的结论，比如“这个接口永远不会变”。
如果一句话无法被检查，就不要写成规则。比如“代码要高质量”太空；更好的写法是“修改后必须说明影响文件、验证方式和剩余风险”。
两套记忆机制：CLAUDE.md 和 auto memory
新版 Claude Code 有两套互补机制：你维护的 CLAUDE.md 用来写明确指令，Claude 自己维护的 auto memory 用来记录工作中发现的稳定经验。两者都是可审计的 Markdown，不是看不见的黑盒。
- 项目级
./CLAUDE.md：跟着仓库走，团队共享，写项目本身的规则和边界。 - 项目级
./.claude/CLAUDE.md：与根目录文件作用相同，适合把 Claude 配置集中在.claude/。 - 本地项目级
./CLAUDE.local.md：只给当前使用者的项目偏好，应加入.gitignore。 - 用户级
~/.claude/CLAUDE.md：只属于你，跨项目生效，写你的个人习惯和偏好。 #快捷记忆：在输入框开头打#，CC 会问你把这条记忆存到项目还是用户级文件里。- 上级目录的
CLAUDE.md也会被向上查找并合并，适合 monorepo。 .claude/rules/*.md：把大规则拆成主题文件，还可以按文件路径限定作用范围。- auto memory：保存在
~/.claude/projects/<project>/memory/，由 Claude 记录构建命令、排障经验和反复确认的偏好。
auto memory 默认开启，可以在 /memory 中查看和切换。启动时只加载 MEMORY.md 的前 200 行或 25KB，详细内容可以拆到其他主题文件按需读取。它属于本机数据，不会自动提交到仓库，也不会自动同步给团队。
CLAUDE.md、rules 和 auto memory 怎么选
| 内容 | 推荐位置 | 原因 |
|---|---|---|
| 团队统一构建命令 | 项目 CLAUDE.md | 每个人、每次会话都需要 |
只针对 src/api/** 的规则 | .claude/rules/ | 按路径加载，减少无关上下文 |
| 个人项目偏好 | CLAUDE.local.md | 不应该提交给团队，且不能包含密码 |
| Claude 发现的稳定排障经验 | auto memory | 由 Claude 跨会话复用，可随时审计 |
强制禁止读取 .env | permissions deny | 记忆只是上下文，不是强制安全边界 |
CLAUDE.md 建议控制在 200 行以内。拆成 @import 可以改善组织，但导入内容仍会在启动时进入上下文；如果目标是减少上下文，应优先使用路径作用域 rules，而不是把一个大文件机械拆成多个 import。
用户级记忆适合记这类跨项目的稳定经验：
- 某类报错的排查结论。
- 反复纠正过的偏好，例如“这个项目不要自动格式化全文件”。
- 你个人固定的汇报格式或工作习惯。
- 某个测试或构建的历史坑点。
它适合记录“已经反复出现、被确认有效”的习惯，不适合记录一次性任务。任何一层记忆里有过期内容，都会让 CC 越用越偏，所以要定期用 /memory 复查。
让 CC 生成 CLAUDE.md 草稿
请为当前项目准备一份 CLAUDE.md 草稿。 要求： 1. 先只读分析项目，不要创建或修改文件。 2. 只基于项目文件中能确认的信息写草稿。 3. 不要写 API Key、Token、密码或账号信息。 4. 不要写没有确认过的命令。 5. 草稿包含：项目概况、关键目录、常用检查、修改边界、安全要求、汇报格式。 6. 每条规则要具体、可执行、可检查。 请先只输出草稿，不要写入文件。
让 CC 审查 CLAUDE.md 草稿
草稿出来以后，不要马上写入。先审一遍，重点看是否有编造、过宽、过时和泄密风险。
请审查这份 CLAUDE.md 草稿。 要求： 1. 找出没有项目文件依据的内容。 2. 找出过于空泛、不可检查的规则。 3. 找出可能过期或不应该长期保存的内容。 4. 找出是否包含密钥、账号、内部隐私或敏感路径。 5. 给出可以直接保留、需要改写、应该删除的清单。 只做审查，不要写入文件。
第一次写入后的验证
CLAUDE.md 写入后，必须用一个低风险任务验证它是否真的有效。
请基于当前 CLAUDE.md 做一次只读验证。 要求： 1. 说明你从 CLAUDE.md 里读到了哪些关键规则。 2. 选择一个低风险任务，例如解释项目结构或检查首页链接。 3. 按 CLAUDE.md 的要求给出计划和汇报格式。 4. 不修改任何文件。 5. 如果 CLAUDE.md 有不清楚或冲突的地方，请指出。
如果 CC 读完 CLAUDE.md 后仍然不知道怎么工作，说明文档写得太抽象；如果它把规则理解成“永远不能改某些目录”，说明规则写得太死。
用 /memory 做复查
请打开或检查当前项目记忆，并帮我判断： 1. CLAUDE.md 中哪些规则最重要。 2. 用户级 CLAUDE.md 是否记录了过时或错误的信息。 3. auto memory 保存了哪些经验，是否含有过时结论或敏感信息。 4. 是否有可以删掉的重复规则。 5. 是否有应该沉淀到项目 CLAUDE.md 或路径 rules 的团队规则。 只做分析，不要直接修改。
什么时候更新 CLAUDE.md
适合更新：
- 项目目录结构发生长期变化。
- 团队确认了新的检查方式。
- 某个目录被明确划为禁止随意修改。
- 反复出现的偏好已经稳定下来。
- 发布、验收、审查流程发生变化。
不适合更新：
- 本次任务临时要求。
- 某个未确认的猜测。
- 一次性的排障结论。
- 还在讨论中的团队约定。
CLAUDE.md、任务提示词、Skill 怎么分工
| 内容 | 应该放哪里 |
|---|---|
| “本次只改首页 Hero 区域” | 当前任务提示词 |
| “这个项目生成页不要手改，应该改 content 里的 Markdown” | CLAUDE.md |
| “每次提交前检查 diff、敏感信息、测试结果” | Skill |
| “禁止读取或提交 .env 文件” | 权限规则或 Hook |
| “当前修复这个按钮颜色” | 当前任务提示词 |
| “这个仓库的集成测试需要先启动 Redis” | auto memory，确认稳定后可提升为项目规则 |
验收结果
- 你知道项目级 CLAUDE.md 和用户级记忆的区别。
- 你知道 auto memory、CLAUDE.local.md 和
.claude/rules/的用途。 - 你会先让 CC 出草稿，而不是直接写。
- 你知道需要强制执行的规则应该进入权限或 Hook 层。
- 你知道 CLAUDE.md 写入前要审查，写入后要用只读任务验证。
- 你知道哪些内容适合长期保存，哪些只适合当前对话。