很多人觉得 Claude Code 不稳定，本质上不是模型随机，而是项目上下文每次都重新讲一遍、还讲得不一致。官方把这个问题拆成两套记忆机制：你写的 CLAUDE.md，以及 Claude 自己积累的 auto memory。前者更适合放明确规则、项目结构、命令和长期约束，是多数团队最应该先补上的一层。
CLAUDE.md 到底解决什么问题
官方文档给出的判断标准很实用：凡是你本来会在每次会话里重新解释、第二次还会纠正、或者新同事也必须知道的背景，都适合写进 CLAUDE.md。比如构建和测试命令、目录职责、命名约定、不能碰的模块、提交前检查项。它不是规范仓库的替代品，而是把“Claude 每次都该知道的事实”放到开局上下文里。
CLAUDE.md 和 auto memory 的区别
CLAUDE.md 由你写，适合放规则和说明；auto memory 由 Claude 记录，更适合保存它从会话中学到的调试经验和偏好。官方明确说两者都会在新会话开头加载，但它们都属于上下文，不是强制配置。所以如果你真的要阻止某个危险动作，应该靠权限规则或 Hook，而不是只写一句“不要这么做”。
放在哪里最合适
官方文档列出了多层作用域：组织级、用户级、项目级和本地项目级。对大多数团队来说，最实用的是项目级的 ./CLAUDE.md 或 ./.claude/CLAUDE.md。如果只是你个人在某个项目里的偏好，可以用 CLAUDE.local.md 并加入 gitignore；如果是所有项目通用的个人习惯，再写到 ~/.claude/CLAUDE.md。
一个够用的结构模板
# 项目简介
- 这个仓库做什么
- 核心目录分别负责什么
# 常用命令
- 安装依赖：pnpm install
- 本地启动：pnpm dev
- 测试：pnpm test
- 构建：pnpm build
# 开发约束
- 优先复用现有组件
- 修改接口前先找调用方
- 不要提交密钥和本地配置
# 验收要求
- 改动后先跑单测
- UI 改动附带截图或说明
- 输出变更摘要和风险点这个模板看起来朴素，但比“写一堆空泛原则”有效得多，因为它把 Claude 能直接执行或检查的内容写清楚了。
什么时候要拆分成多份规则
在大型仓库里，官方建议把根目录的规则和子目录规则分层。根目录 CLAUDE.md 放全仓统一约定；packages/api/CLAUDE.md、packages/web/CLAUDE.md 这类子目录文件，只放该区域特有的信息。这样做的好处是减少无关上下文占用，也让 Claude 在进入某个子系统时才加载那部分细则。
还能导入别的文件吗
可以。官方文档说明 CLAUDE.md 支持通过 @path/to/import 导入其他文件，并允许相对路径和绝对路径，最多递归四层。这个机制很适合把冗长的流程说明拆出去，例如把前端样式规范、API 设计约定、测试数据说明分别放在独立文件里，再由主 CLAUDE.md 引用。
哪些内容不建议写进去
一个常见误区是把一切都塞进 CLAUDE.md。其实一次性任务说明、某个临时分支的实验细节、短期排障记录、只对你个人机器有效的路径，都不适合放进去。它们要么会过期，要么会污染团队共享上下文。更好的做法是：长期、稳定、团队通用的信息进 CLAUDE.md；一次性流程做成技能；个人偏好放本地文件；真正的访问限制交给权限规则。
反过来说，只要某条说明你已经连续两次在会话里重复过，基本就值得考虑写入。这个判断标准很简单，但非常实用。
新手最容易写错的地方
- 写成企业文化宣言，几乎没有可执行信息。
- 把一次性任务说明塞进去，导致长期污染上下文。
- 把高风险限制只写在 CLAUDE.md，不配合权限规则。
- 什么都写在根目录文件里，单仓越大越难用。
- 改了项目结构却不更新 CLAUDE.md，最后信息比没有还误导。
高效起步办法
如果你不知道从哪儿写，官方建议可以先运行 /init。Claude Code 会分析仓库，生成一个初版 CLAUDE.md，包含它发现的命令和约定。你再人工补上那些“它靠扫描学不到，但团队必须知道”的内容，效果通常比从空白页硬想更好。
总结
写 CLAUDE.md 的核心不是越长越好，而是让 Claude Code 每次进入项目时都拿到稳定、简洁、可执行的上下文。先写项目简介、命令、约束和验收，再根据仓库规模逐步拆分。配合 权限模式 和 大型项目读取策略，它会成为效率提升最明显的一层基础设施。
