CLAUDE.md 与项目记忆

Claude Code 的记忆是分层的文件：项目级 CLAUDE.md 写给团队和项目，用户级 ~/.claude/CLAUDE.md 记录你的跨项目个人偏好，配合 # 快捷记忆和 /memory 维护。

为什么要有 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 Code 的记忆不是一个会“自动积累”的黑盒，而是几份分层的 Markdown 文件：

• 项目级 ./CLAUDE.md：跟着仓库走，团队共享，写项目本身的规则和边界。
• 用户级 ~/.claude/CLAUDE.md：只属于你，跨项目生效，写你的个人习惯和偏好。
• # 快捷记忆：在输入框开头打 #，CC 会问你把这条记忆存到项目还是用户级文件里。
• 上级目录的 CLAUDE.md 也会被向上查找并合并，适合 monorepo。

用户级记忆适合记这类跨项目的稳定经验：

• 某类报错的排查结论。
• 反复纠正过的偏好，例如“这个项目不要自动格式化全文件”。
• 你个人固定的汇报格式或工作习惯。
• 某个测试或构建的历史坑点。

它适合记录“已经反复出现、被确认有效”的习惯，不适合记录一次性任务。任何一层记忆里有过期内容，都会让 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. 用户级记忆是否记录了过时或错误的信息。
3. 是否有可以删掉的重复规则。
4. 是否有应该从临时对话沉淀到 CLAUDE.md 的长期规则。

只做分析，不要直接修改。

什么时候更新 CLAUDE.md

适合更新：

• 项目目录结构发生长期变化。
• 团队确认了新的检查方式。
• 某个目录被明确划为禁止随意修改。
• 反复出现的偏好已经稳定下来。
• 发布、验收、审查流程发生变化。

不适合更新：

• 本次任务临时要求。
• 某个未确认的猜测。
• 一次性的排障结论。
• 还在讨论中的团队约定。

CLAUDE.md、任务提示词、Skill 怎么分工

验收结果

• 你知道项目级 CLAUDE.md 和用户级记忆的区别。
• 你会先让 CC 出草稿，而不是直接写。
• 你知道需要强制执行的规则应该进入权限或 Hook 层。
• 你知道 CLAUDE.md 写入前要审查，写入后要用只读任务验证。
• 你知道哪些内容适合长期保存，哪些只适合当前对话。