导读：同样一个 Claude Code，为什么有人用着"很懂我的项目"，有人却觉得它"老跑偏、不按规矩来"？差别常常就在一个文件——CLAUDE.md。通过系列文章把 CLAUDE.md 一次讲透：它是什么、该写哪些内容、怎么写它才真正听话、怎么分层管理、怎么长期维护。看完你就能给自己的项目写出一份好用的说明书。
同样是 Claude Code，有人用着它"很懂我的项目"，有人却觉得它"老跑偏、不按规矩来"。差别常常就在一个文件上——CLAUDE.md。
我自己印象最深的一次：我在 CLAUDE.md 里明明写了"字符串别硬编码、统一进资源文件"，它还是时不时硬编码。我以为是规则不够细，又加了几条，结果它更不听了。后来才搞明白——不是它不听话，是我的 CLAUDE.md 写错了。
这一篇我们就把 CLAUDE.md 一次讲透：它是什么、该放哪些内容、怎么写它才真正听话、怎么分层管理、怎么长期维护。看完你就能给自己的项目写出一份好用的说明书。
一、CLAUDE.md 是什么，为什么它这么关键
一句话：CLAUDE.md 是放在你项目里的一个 Markdown 文件，Claude Code 每次开始工作前都会自动读取它，把它当作这个项目的"说明书 + 长期记忆"。
熟悉大模型的话，你会发现它其实就是"System Prompt"（系统提示词）在 Claude Code 里的落地——每一轮对话，它都带着这份说明书在干活。
为什么关键？因为 Claude Code 默认只懂"通用的编程常识"，它不懂你这个项目的特殊性：你用什么构建命令、什么架构、什么命名规范、踩过哪些坑。这些它猜不到的东西，写进 CLAUDE.md，它就懂了；不写，它就只能靠猜——猜错了，就是你看到的"跑偏"。
所以 CLAUDE.md 的作用，就是把"一个聪明但不熟悉你项目的新同事"，变成"一个熟悉项目规矩的老手"。
结论：CLAUDE.md 是每轮对话都自动加载的项目说明书，它决定了 Claude Code 到底懂不懂你的项目——这是用好它的第一块基石。
二、怎么创建，以及一份 CLAUDE.md 该有哪些板块
创建很简单：在项目根目录进入 Claude Code，敲一个命令：
/init它会自动扫描你的项目，探测构建系统、测试框架、代码风格，生成一份起始版的 CLAUDE.md。这是起点，但别指望它一步到位——真正好用的版本，需要你按自己项目的情况补充和修剪。
那一份结构清晰的 CLAUDE.md，通常包含这几个板块（不必每个都有，按项目需要取舍）：
项目概览：一句话说清这是什么项目、技术栈是什么。
构建与测试命令：怎么编译、怎么跑测试、提交前要跑什么检查。这是最高频、最该写的。
代码约定：架构模式、命名规范、和默认不一样的风格要求。
架构决策：项目特有的、Claude 猜不到的设计选择。
坑 / 注意事项：踩过的坑，写成"别再犯"。
参考链接：长文档不要粘贴，用链接或引用指过去（后面讲
@import）。
这六块覆盖了日常绝大多数需求。你会发现它们有个共同点：全是"Claude 读你代码也猜不出来"的东西。这正是下一节的判断标准。
结论：用/init生成起点，再按"项目概览 / 构建测试 / 代码约定 / 架构 / 坑 / 参考"几个板块补全——重点永远是"它猜不到的"那些。
三、该写什么，不该写什么
这是 CLAUDE.md 写得好不好的核心。官方给了一个极简、极好用的判断标准，记住这一句就够：
逐行问自己：删掉这行，会让 Claude 犯错吗？不会，就删。
按这个判据，官方整理了一张"该写 / 不该写"对照表，建议你照着对：
✅ 应该写（Claude 猜不到的） | ❌ 不该写（删掉它也不犯错的） |
|---|---|
Claude 猜不出的 Bash 命令（自定义构建 / 脚本） | 读代码就能推断出来的东西 |
与默认不同的代码风格规则 | Claude 已知的语言标准惯例 |
测试指令、首选的测试运行器 | 详细 API 文档（改成链接） |
仓库规范（分支命名、PR 约定） | 频繁变动的信息 |
项目特有的架构决策 | 长篇解释 / 教程 |
开发环境的怪癖（必需的环境变量等） | 逐个文件描述代码库 |
常见陷阱、踩过的坑（"别再犯"） | "要写干净的代码"这类正确的废话 |
一句话概括：CLAUDE.md 写的是"高频 + 稳定 + Claude 猜不到"三者的交集，而不是项目百科全书。README 里已有的、读代码能推断的、每周都在变的，统统别往里塞。
结论：判断标准只有一句——"删了会不会让它犯错"；写它猜不到的，删它能推断的。
四、一个关键原则：宁可短，不要全
这一节单独拎出来，因为它最反直觉，也是我开头那个坑的真正原因——CLAUDE.md 不是越全越好，太长反而有害。
有三个实打实的原因：
一是它每行都花钱，而且每轮都花。CLAUDE.md 在 Claude 读你的代码、读你的任务之前就先加载，而且每一轮对话都重新加载一遍。一个 5000 token 的 CLAUDE.md，等于你还没开口，每一轮就先被它吃掉 5000 token。
二是"上下文腐烂"（context rot）。上下文塞得越满，模型对里面内容的注意力越分散、对早期内容的召回越差。也就是说——文件太长，你那条真正重要的规则会被"稀释"掉，技术上还在，实际已经不太起作用了。我开头那条"别硬编码"失效，就是这么回事。
三是官方说得很直白："臃肿的 CLAUDE.md 会让 Claude 忽略你真正的指令"。官方还补了一句特别实用的判断：如果 Claude 反复无视你的某条规则，多半不是它不听话，而是文件太长、规则被淹没了。
所以业界的参考值是：控制在 1000 token 以内、200 行以下，命令优先、长内容用引用而不是粘贴（数据为官方倾向 / 业界共识，截至 2026 年中）。我把开头那份一百多行的文件删到三十行后，它反而老老实实照做了——这不是巧合。
结论：CLAUDE.md 每行都占每轮的上下文预算，越长越被稀释。该写的写全，但能删的坚决删——短，是为了让规则真正生效。
五、怎么写，它才更听话
同样的内容，写法不同，效果差很多。几个让 Claude 更愿意照做的技巧：
1. 具体，不要空泛。"注意网络层规范"它没法执行；"网络层统一走RetrofitClient，不要直接 new"它就能照做。写清"做什么 + 怎么做"，最好连"为什么"都点一句。
2. 重点规则用IMPORTANT/YOU MUST标出来。官方明确说，这两个词能提升 Claude 的遵从度。把你最不希望它违反的那几条这样标记。
3. 命令直接给可复制的原文。写./gradlew ktlintCheck，不要写"提交前记得跑代码检查"。
4. 长文档用@引用，不要粘贴。CLAUDE.md 里可以写@docs/weather-api.md、@README.md这样的引用，需要时 Claude 自己去读那个文件，而不是把整篇文档塞进每轮的上下文里。这既保持了精简，又不丢信息。
结论：具体的指令 +IMPORTANT标重点 + 可复制的命令 +@引用长文档——这四条让 CLAUDE.md 从"它大概知道"变成"它确实照做"。
六、分层放置：全局、项目、个人各管各的
CLAUDE.md 不止能放一个地方。理解分层，能让你管得更清楚：
~/.claude/CLAUDE.md：全局，对你所有项目都生效，放你的个人通用偏好（比如"回答用中文""注释精简"）。./CLAUDE.md：项目级，放在项目根目录、提交进 git，团队共享这一份。./CLAUDE.local.md：个人 + 项目级，加进 gitignore，放你自己在这个项目里的私货，不影响别人。monorepo：子目录也能放自己的 CLAUDE.md，进入对应目录时会被自动叠加。
这套分层的好处是：通用的偏好不用每个项目重写一遍，团队规范和个人习惯也能分开，不会互相污染。
还有两个实用补充：
说明实在多，别都堆进一个 CLAUDE.md——用
.claude/rules/目录把规则按主题拆成多个文件，甚至能让某条规则"只在改到相关类型的文件时才加载"。这才是"内容太多"的正解：拆分，而不是把一个文件写长。项目已经在用
AGENTS.md（给别的 AI 工具看的通用说明）的话，不用重写一份——在 CLAUDE.md 里用@AGENTS.md把它导入进来，两个工具共用同一份。
结论：全局放通用偏好、项目级放团队共享规范、local 放个人私货、内容多就用.claude/rules/按主题拆开——分层让 CLAUDE.md 各归各位、又不臃肿。
七、长期维护，以及它的边界
CLAUDE.md 不是写完一次就不管的，它是个"活文件"。最好的用法是一个简单的正循环：Claude 每犯一个新错，你就把对应的一条教训补进去（"以后别再 X"）；同时定期回头，删掉那些过期的、没用的规则，让它始终保持"短而准"。Boris（Claude Code 团队负责人）本人就是这么用的。
补和改都很方便，几种方式任选：**直接在对话里让 Claude"把这条加进 CLAUDE.md"**；用/memory命令列出并打开记忆文件来编辑；或者干脆手动改这个文件。
顺带一提：新版 Claude Code（v2.1.59+）还带了一套**"自动记忆"（auto memory）——它会在你纠正它、表达偏好时自己记笔记、跨会话复用**，不用你动手。它和你手写的 CLAUDE.md 是互补的两套：CLAUDE.md 是"你定的规矩"，自动记忆是"它自己攒的经验"。
也要知道它的边界，别误用：
CLAUDE.md 是"建议性"的，不是"强制"的。它能大幅提高 Claude 照做的概率，但不保证 100%。如果某件事你要它每次都雷打不动执行（比如每次改完代码必须跑格式化），那该用Hooks（第 7 篇专门讲），而不是指望写进 CLAUDE.md。
偶尔才用到的领域知识 / 长流程，做成 Skill（也是第 7 篇），按需加载，别常驻在 CLAUDE.md 里占每轮的预算。
结论：把 CLAUDE.md 当活文件，犯错就补、过期就删；要强制执行的交给 Hooks，偶尔才用的交给 Skill，CLAUDE.md 只留"每次都需要、且它猜不到"的那部分。
八、一份可以直接照抄的完整示例
把上面的原则落到一份真实文件上。这是一个 Android 天气 App 的 CLAUDE.md，总共不到 30 行，但该有的板块都有：
# 天气 App（Android / Kotlin） ## 项目概览 - 一个查询天气的 Android App，Kotlin + MVVM 架构 ## 构建与测试 - 构建：`./gradlew assembleDebug` - 跑单测：`./gradlew testDebugUnitTest` - 提交前必须先跑 lint：`./gradlew ktlintCheck` ## 代码约定 - 网络层统一走 `RetrofitClient`，不要直接 new Retrofit - 字符串一律进 strings.xml，不要硬编码 - 命名：ViewModel 以 `XxxViewModel` 结尾 ## 坑（别再犯） - IMPORTANT: 天气 API 的 Key 放 local.properties，不要提交进 git - 改网络回调时注意它在主线程刷新 UI，耗时操作要切到 IO 线程 ## 参考 - 接口文档见 @docs/weather-api.md对照前面的原则看：板块清晰、命令能直接复制、规则具体（"统一走RetrofitClient"）、踩过的坑写成"别再犯"并用IMPORTANT标重点、长文档用@引用——全文几十行，但每一行都在干活。你完全可以拿这份骨架改成自己项目的版本。
结论：好的 CLAUDE.md 就长这样——结构清楚、内容具体、短而准，照着这份骨架改就能用。
九、把它用好，是一种习惯
CLAUDE.md 看着只是个小文件，但它几乎决定了 Claude Code 在你项目里"听不听话"。回顾一下要点：
它是什么：每轮自动加载的项目说明书，决定 AI 懂不懂你的项目。
写什么：高频 + 稳定 + 它猜不到的（构建命令、规范、架构、坑）。
怎么写：具体、可复制、
IMPORTANT标重点、长文档用@引用。多长：短而准，~1k token 以内，太长反而被稀释。
怎么管：分层放置、犯错就补、过期就删；强制执行用 Hooks，偶尔用的做 Skill。
这背后还有一条贯穿整个系列的暗线——Claude Code 的上下文是有限的、而且越满越笨。CLAUDE.md 每轮都加载，所以它是你最该"省着用、用在刀刃上"的一块上下文。这条线，下一篇会更系统地展开。
