CLAUDE.md 持久化记忆系统详解

CLAUDE.md 是 Claude Code 的持久化记忆系统，用于在会话之间存储指令和偏好设置。它使团队和个人能够保持一致的编码标准、工作流程和项目上下文，而无需在每次对话中重复这些信息。

理解 CLAUDE.md 的本质

CLAUDE.md 文件作为 Claude Code 的持久化记忆，在每个会话开始时自动加载。这些文件可以包含多种类型的信息：编码标准、格式规则、命名约定、架构模式；项目上下文、技术栈选择、关键决策、系统架构；团队约定、Git 工作流程、测试方法、审查流程；个人偏好、偏好的编码风格、常用命令。

这些指令始终对 Claude Code 可用，且不会占用对话上下文空间，为开发者提供了高效的上下文管理机制。

Claude Code 从多个位置加载 CLAUDE.md 文件，后续层级会覆盖前面的层级，形成层次化的记忆体系。

组织范围内的安全政策和公司标准，适用于所有开发者和项目的强制性规则。这一层级确保企业级的一致性和合规性要求得到满足。

位于项目根目录的 ./CLAUDE.md 或 /.claude/CLAUDE.md，包含团队共享的项目约定，通常提交到版本控制中。适用于技术栈规范、架构模式、团队编码标准等项目特定信息。

个人偏好设置，适用于所有项目的 ~/.claude/CLAUDE.md。包含个人编码风格、偏好的工作流程、沟通偏好等个性化配置。

Claude Code 通过智能发现系统逐步解析记忆文件，采用渐进式目录解析策略。

从当前工作目录开始，Claude Code 向上递归读取 CLAUDE.md 文件，从当前目录一直到但不包括根目录。当访问子目录时，按需加载它们的 CLAUDE.md 文件。

在单体仓库结构中，这种机制特别有用。例如在包含前端、后端和多个包的复杂项目中，不同层级可以有各自的约定。当工作在特定子目录时，Claude Code 会按顺序加载工作空间级别、前端级别和特定包级别的约定，最后加载个人偏好。

每个文件都可以添加或覆盖前面文件链中的指令，形成细粒度的配置层次。

以井号开头输入内容可以快速向记忆文件添加指令。Claude Code 会提示选择要更新的 CLAUDE.md 文件，这种简化的操作方式鼓励开发者持续完善记忆配置。

使用 /memory 命令可以查看所有已加载的记忆文件，在编辑器中打开记忆文件，查看完整的记忆层次结构。这个命令显示导入链并允许直接编辑文件。

避免使用模糊的描述，如”写好代码”或遵循最佳实践。应该提供具体的指导，如使用两个空格缩进 TypeScript，函数最大长度 50 行，优先使用组合而非继承。具体的指令能够确保一致的执行结果。

使用标题、列表和代码块来组织可扫描的内容。将测试标准分为单元测试和集成测试两个部分，每个部分都有明确的要求和指导原则。这种结构化的方法使信息更易于查找和理解。

单元测试应该一次测试一个事物，使用描述性的测试名称，遵循 AAA 模式（准备、执行、断言）。集成测试应该测试关键用户路径，使用测试数据库而非生产环境，每次测试后进行清理。

随着项目的发展，定期审查和更新 CLAUDE.md 文件。移除过时的约定，添加发现的新模式，更新架构决策。这种持续改进确保记忆文件始终反映当前的最佳实践。

企业级别的安全政策和公司标准很少改变；项目级别的团队约定和架构偶尔变化；用户级别的个人偏好随着学习而调整。合理的分层策略确保记忆系统的稳定性和灵活性。

对于复杂项目，可以使用导入功能将 CLAUDE.md 分解为更小、更专注的文件。使用 @path/to/file 语法引用其他文件，主文件可以导入架构文档、编码标准、React 模式等专门文件。

导入功能的优势包括模块化组织，每个文件专注于单一主题；跨项目重用，通过导入共享通用约定；递归导入，导入的文件可以导入其他文件，最多 5 层深度；代码块安全性，代码块内的导入会被忽略。

这种模块化方法使大型项目的配置更加清晰和可维护，同时支持不同项目间的配置复用。