【CLAUDE】CLAUDE.md 完全实战指南：用好Claude Code的核心记忆体系

目录

1. CLAUDE.md 到底是什么？为什么它是核心？
2. 高价值内容清单：CLAUDE.md 该写什么
3. 避坑指南：这些内容别往里面写
4. 开箱即用：可直接复制的模板
5. 优先级规则全解：搞懂谁覆盖谁
6. 3步自检：判断你的文档写得好不好
7. 总结
8. 参考资料

很多使用Claude Code的开发者都会遇到一个高频痛点：每次开启新会话，都要反复跟Claude解释项目的技术栈、常用命令、编码规范、不能随意修改的文件……不仅耗时耗力，还经常出现Claude记不住规则、执行出错的情况。

而解决这个问题的核心钥匙，就是CLAUDE.md——这个在Claude Code体系里看似只是普通Markdown文件，却能决定AI编码效率、准确性和规范性的核心持久化记忆文件。

本文会从CLAUDE.md的核心定位、高价值内容清单、避坑红线、可直接复用的模板，到最容易踩坑的优先级规则，做一次完整的实战拆解，帮你彻底搞懂并用好这个文件。

一、CLAUDE.md 到底是什么？为什么它是Claude Code的核心？ 🎯

核心定位与价值

CLAUDE.md本质是一个纯Markdown格式的文本文件，但在Claude Code的会话体系中，它有着不可替代的地位：它是唯一会在每次会话启动时自动加载、全程生效的「项目持久化指令手册」。

你可以把它理解为给Claude准备的「项目入职指南」：里面写清楚项目的核心定位、架构逻辑、工作流程、编码规范、操作禁区、常用命令等核心信息。每次开启新会话，Claude都会自动读取并对齐这些规则，你再也不用反复重复相同的说明。

官方定义的核心用途

根据Claude Code官方文档的定义，CLAUDE.md的核心作用，是承载「你希望指导Claude行为的、通用且持久的指令」，是Claude Code分层记忆体系中，项目级共享规则的核心载体。

二、高价值内容清单：CLAUDE.md 该写这些 📋

1. 项目概览（Project Overview）

这是给Claude的「项目一句话简介」，核心是让它快速搞懂仓库的定位、目标用户、核心模块分布，避免无意义的代码检索。

• 项目定位：一句话说清仓库的核心功能、目标用户和应用场景
• 核心模块说明：简要介绍关键子系统/子目录的作用，比如前端入口、后端服务、公共组件库等

2. 技术栈与环境约束

明确项目的技术选型和硬约束，避免Claude用错工具、版本或语法。

• 核心技术栈：开发语言、框架、数据库及对应的版本要求
• 包管理器：明确指定使用pnpm/npm/uv/poetry等，避免混用导致的依赖问题
• 运行环境：项目运行所需的环境、最低版本要求等

3. 架构导览

给Claude一张清晰的「项目地图」，让它明白代码的边界和数据流走向，避免写出不符合架构设计的代码。

• 目录结构说明：重点解释入口文件、核心业务模块、配置中心、依赖注入的核心逻辑
• 数据流与边界：梳理清楚API层、领域层、数据层之间的调用关系和职责边界

4. 标准工作流

对齐团队的研发流程，让Claude的操作符合团队规范，而非自由发挥。

• 分支策略：明确main/dev/feature分支的使用规则和命名规范
• PR提交要求：规定PR需要满足的条件，比如必须通过测试、附带变更日志、UI改动需附截图等
• 标准开发步骤：比如「需求分析→方案确认→编写测试→功能实现→lint校验→文档更新」的固定流程

5. 常用命令

官方文档特别强调：用自然语言配合明确的命令，能大幅提升Claude执行任务的成功率。这里只放最通用、最核心的命令，避免冗余。

• 基础操作：依赖安装、开发服务启动、测试、lint校验、构建等核心命令
• 故障排查：命令执行失败时的标准排查方案，比如「先清缓存再重装依赖」

6. 操作禁区与风险控制

这是最关键的部分之一，直接避免Claude执行危险操作，造成线上问题或代码污染。

• 文件保护清单：明确列出禁止随意修改的文件，比如生产环境配置、数据库迁移脚本、密钥文件等
• 高危操作规范：针对数据库改动、基础设施变更等高危操作，明确必须遵循的流程，比如「先出变更计划→确认回滚方案→二次人工确认后再执行」
• 代码生成要求：明确生成代码必须附带的保障措施，比如单元测试、边界处理、异常捕获等

三、避坑指南：这些内容别往里面写 ⚠️

很多人写CLAUDE.md的误区，是把它当成了「代码规范大全」，什么都往里塞，结果反而导致Claude忽略核心规则，效果大打折扣。

核心原则：别让AI做工具能搞定的事

行业最佳实践反复强调：永远不要让大模型去做linter、formatter这类确定性工具能稳定完成的工作。

• 像代码缩进、单双引号、函数命名规范这类格式细节，完全可以用ESLint、Prettier、Biome这类工具自动校验和修复，写进CLAUDE.md只会增加上下文噪音
• 大模型的指令遵循能力会随着指令数量的增加而下降，塞入过多无关细节，会导致核心的架构规则、风险控制规则被稀释，甚至被Claude忽略

书写红线：这些内容尽量别写

• 不写过于细碎的、能从现有代码库中学习到的格式细节
• 不写只针对特定场景、不具备通用性的指令（比如某个特定接口的写法）
• 不写大段的代码片段，优先用文件路径引用，避免内容过时失效

四、开箱即用：可直接复制的CLAUDE.md 模板 📦

1. 仓库根目录通用模板

适用于项目根目录，定义全仓库通用的核心规则，可直接复制修改：

## Project Overview - 仓库定位：<一句话说明项目核心功能、目标用户> - 核心模块说明： - /apps/web：<前端应用说明> - /apps/api：<后端服务说明> - /packages/shared：<公共组件/工具库说明> ## 优先级说明（优先阅读） - 子目录中的CLAUDE.md 会覆盖本文件的对应规则 - 出现规则冲突时，优先遵循离被编辑文件最近、最具体的CLAUDE.md ## 技术栈与环境 - 开发语言：<如 TypeScript> - 运行环境：<如 Node 20+> - 包管理器：<如 pnpm> - 数据库：<如 PostgreSQL> - 核心框架：<如 Next.js / NestJS> ## 架构规则 - 职责边界： - 前端UI层禁止直接访问数据库，所有数据请求必须通过API层 - 业务逻辑必须收敛在API的domain层，禁止散落在Controller中 - 核心入口文件：<填写关键入口文件路径> ## 标准工作流 - 推荐开发流程： 1. 先输出实现方案，确认后再开发 2. 最小化代码改动 3. 补充/更新对应的单元测试 4. 执行lint和类型校验，全部通过后再提交 - PR提交要求： - 必须通过所有自动化测试 - PR描述中必须附带简要的变更日志 ## 常用命令 - 依赖安装：pnpm i - 开发服务启动： - 前端：pnpm --filter web dev - 后端：pnpm --filter api dev - 测试执行：pnpm test - 代码校验：pnpm lint - 生产构建：pnpm build ## 操作禁区 - 禁止修改的文件： - <填写禁止随意修改的文件/目录清单> - 数据库迁移操作规范： - 必须先说明迁移方案和回滚策略，确认后再执行 - 所有高危变更操作，必须先人工确认，再执行

2. 子项目覆盖模板

当仓库是monorepo、子项目有差异化规则时，可在对应子目录新建CLAUDE.md，覆盖根目录的通用规则，示例如下：

## 前端项目规则（覆盖根目录CLAUDE.md） - 优先复用/components目录下已有的UI组件，禁止重复造轮子 - 所有用户可见的UI变更，必须满足： - 更新对应的组件快照 - PR描述中附带变更前后的对比截图 - 业务组件必须附带对应的Storybook文档 ## 子项目专属命令 - 开发服务：pnpm --filter web dev - 单元测试：pnpm --filter web test - E2E测试：pnpm --filter web e2e

五、优先级规则全解：搞懂谁覆盖谁 🔍

在Claude Code的分层记忆体系中，CLAUDE.md的存放位置，直接决定了它的作用范围和优先级，核心原则是：越具体、越靠近当前工作目录的指令，优先级越高，也就是我们常说的「就近原则」。

1. 官方分层与优先级排序

Claude Code官方定义了多层级记忆文件，核心优先级参考如下：

2. 实测完整优先级排序

通过实测验证，完整的优先级从高到低排序为：

1. ./.claude/CLAUDE.local.md（项目私有本地配置，优先级最高）
2. ./.claude/CLAUDE.md（项目共享配置）
3. ./CLAUDE.local.md（项目私有本地配置）
4. ./CLAUDE.md（项目共享配置）
5. ~/.claude/CLAUDE.md（用户全局配置）
6. 命令行注入的系统提示词

实测环境配置参考：

3. 常见踩坑点

实测中发现，Claude并非100%会自动读取所有层级的文件，经常出现漏读低优先级、甚至高优先级的本地文件的情况：

• 首次提问时，Claude可能只读取了项目共享的CLAUDE.md，忽略了私有本地的CLAUDE.local.md
• 只有当你明确提醒它读取对应文件时，它才会按照完整优先级执行规则

比如，按照上面的测试环境，我第一次问它1+1，它只读了《CLAUDE.md》、没有读《CLAUDE.local.md》：

而且第一次强调后，它也只是读了《CLAUDE.local.md》，而忽略了《.claude/CLAUDE.local.md》；直到我再次提醒它时，它才说出正确的答案：

4. 其他优先级补充说明

• 命令行注入提示词：通过claude --append-system-prompt传递的提示词，优先级最低，会被所有CLAUDE.md文件的内容覆盖，同时Claude会对注入内容做准确性和安全性校验，不符合事实的内容会被直接忽略。

命令行注入优先级测试：

注入内容安全校验：

• 企业组织级策略：由企业IT/DevOps统一管理，优先级高于用户个人配置和项目配置，个人用户无法修改，比如企业禁用了fast mode，用户执行/fast命令会直接报错。

企业级策略限制示例：

5. 实务建议

• monorepo项目：把全仓库通用的规则放在根目录的CLAUDE.md，各子项目的差异化规则放在对应子目录的CLAUDE.md，既保证规范统一，又能适配差异化需求
• 个人私有配置：把自己的本地测试地址、专属快捷命令等，放在CLAUDE.local.md中，避免提交到Git污染团队配置
• 规则冲突时，优先遵循「就近原则」，越靠近被操作文件的规则，优先级越高

六、3步自检：判断你的CLAUDE.md 写得好不好 ✅

写完CLAUDE.md后，可以通过这3个步骤，快速判断文档的质量：

1. 新人可读性测试

把Claude当成刚入职的新同事，只给它这份CLAUDE.md，看它能不能快速搞懂：项目是做什么的、代码要在哪里写、标准开发流程是什么、哪些操作绝对不能做。如果它能清晰回答这些问题，说明文档的信息是完整、清晰的。

2. 决策有效性测试

逐行检查文档里的每一条规则，问自己：这条规则会不会影响Claude的开发决策？

• 比如「数据库变更必须先确认回滚方案」，会直接改变Claude对高危操作的处理逻辑，是有效规则
• 比如「代码用2空格缩进」，可以用prettier自动处理，不会影响核心开发决策，是无效规则

删掉所有不会影响核心决策的无效规则，能大幅提升Claude对核心规则的遵循度。

3. 抗噪性测试

检查文档的长度和指令数量：

• 行业最佳实践建议，CLAUDE.md的内容控制在300行以内，越短越好
• 指令数量越少，Claude的遵循度越高，优先保留最核心、最通用的规则

如果文档里塞满了细碎的格式要求，一定要精简，把确定性的工作交给工具处理。

七、总结

总结一下，CLAUDE.md的核心价值，是用最少、最精准、最通用的规则，给Claude对齐项目的边界、标准和流程。它不是越全越好，而是越精准、越能影响核心决策越好。

用好「就近优先」的优先级规则，既能保证团队通用规范的统一，也能灵活适配子项目的差异化需求；同时把格式校验这类确定性的工作交给工具，让CLAUDE.md只承载最核心的规则，才能最大化发挥它的价值。

八、参考资料

1. Claude Code 官方内存配置文档
2. Writing a good CLAUDE.md - humanlayer.dev