CLAUDE.md 是什么、放在哪里、写什么

CLAUDE.md 是 Claude Code 在项目层面最可靠的跨会话记忆载体。对话历史会被清空或压缩，但一份写好的项目记忆会在每次进入该项目时被读取，让代理始终掌握稳定的项目背景与约定。本节讲清它"是什么、放在哪里、该写什么、不该写什么"。

一、CLAUDE.md 解决什么问题

纯对话记忆有两个天然短板：一是 /clear 会清空当前对话历史，二是长会话经 /compact 压缩后早期细节会丢失。CLAUDE.md 则是保存在项目仓库中的普通 Markdown 文件，不随对话清空而消失，专门用来沉淀相对稳定、每次都希望代理知道的事实：项目目标、技术栈、目录约定、常用命令和编码规范。它与易失的聊天记录分工明确：对话负责当前任务的上下文，CLAUDE.md 负责跨会话复用的长期背景。

二、放在哪里

• 主位置：项目仓库根目录下的 CLAUDE.md，是代理进入该项目时最常读取的项目记忆文件。
• 先用工具生成草稿：在项目目录启动会话后运行 /init，它会探索代码库并生成一份起始 CLAUDE.md 草稿，再由人工审阅补充，比从零手写更高效。
• 会话内查看与编辑：可用 /memory 查看当前加载的项目记忆并进行编辑维护；修改后保存到仓库，后续会话即可沿用。
• 前提是在正确目录启动：代理只会围绕当前工作目录读取对应项目文件；若启动目录与项目根不一致，就无法正确加载该项目的 CLAUDE.md。

三、应该写什么

类别	建议写入内容	写作要点
项目简介	一句话说明项目用途、面向用户与核心模块	简洁，帮助代理快速建立定位
技术栈	主要语言、框架、运行时与关键依赖	写稳定版本要求，不堆砌全部依赖清单
目录结构速览	关键目录职责、源码/测试/配置/文档分别在哪	只列高层结构，避免逐文件罗列
常用命令	安装依赖、本地启动、运行测试、构建、代码检查等命令	必须是可直接运行的真实命令，先在终端验证
编码与命名约定	风格偏好、命名规则、错误处理与注释习惯	具体、可执行，少写空泛口号
测试与提交约定	测试组织方式、提交信息风格、必过的检查项	与团队实际流程保持一致
注意事项与禁区	不要改动的目录、兼容性约束、易踩坑点	明确排除项，降低越界改动概率
参考资料	内部文档、规范链接、关键说明文件位置	指向稳定可读的资料，不贴易失效内容

四、不该写什么

• 密钥与凭据：任何令牌、密码、私钥都不写入。
• 临时易变状态：当前调试到第几步、今天的临时想法等应留在对话里，不进长期记忆。
• 大段 README 或源码全文：代理可按需读取文件，记忆文件只需提炼约定与命令，避免冗长挤占上下文。
• 无法验证的口号："代码要优雅""注意性能"这类缺乏判据的描述，应替换为具体规则。

五、常见问题排查

现象	可能原因	处理方向
代理似乎没读到约定	启动目录不对、文件未保存或位置不在项目根	确认在项目根启动、文件已保存，用 /memory 核对加载内容
记忆过长、响应变钝	粘贴了过多原文与历史细节	精简为稳定约定与命令，细节交给按需读取
约定与实际代码脱节	项目演进后未更新记忆文件	定期随重构同步命令与结构说明
改了文件但新会话不生效	未保存或未提交到当前工作副本	确认保存成功后再开新会话验证