CLAUDE.md 完全指南 —— 真正能改变 Claude Code 行为的那个文件
CLAUDE.md 是一个 Claude Code 项目里杠杆最高的文件 —— 也是最常被写坏的那个。这是总入口：这个文件是什么、该放什么，以及通往「怎么写、怎么瘦身、怎么扩展、怎么和 AGENTS.md 共存」四篇深入文章的链接。
CLAUDE.md 是 Claude Code 在每次会话开始时都会读的指令文件 —— 你把构建命令、代码约定、以及一个全新模型无法单靠读代码推断出来的硬约束,都放在这里。写对了,Claude 表现得像个早就熟悉你仓库的工程师;写坏了 —— 臃肿、自相矛盾、或者干脆没有 —— 你会在每一次会话里悄悄付出代价:更差的输出 + 更高的 token 成本。
这个页面是我们关于 CLAUDE.md 所有文章的总入口。先在这里建立心智模型,再顺着深入文章往下读。
CLAUDE.md 到底是什么
CLAUDE.md 是 Claude Code 的原生记忆文件。有三点让它区别于「给 AI 看的 README」:
- 它是分层的。 仓库根目录的项目
CLAUDE.md,加上你个人的~/.claude/CLAUDE.md,两个都会加载 —— 项目规则在先,你的个人偏好叠在上面、且只对你这台机器生效。 - 它支持导入。
@path/to/file.md会在加载时把另一个文件拉进来,所以你可以组合指令,而不是维护一个巨型文件。 - 它每次会话都被完整加载。 这既是它的威力,也是它的税:你写的每一行,每次运行都被重新读取(并重新计费)。CLAUDE.md 不是写一次就忘的文档 —— 它是压在每一次交互上的实时成本。
最后这一点引出的纪律,就是整件事的核心:只说一个全新模型不会自己做的事,而且只说一遍。
四篇深入文章
下面每一篇都是独立的实战指南。合起来覆盖了 CLAUDE.md 的「写、瘦、扩、和解」四件事。
1. 怎么写才管用
如何写好一份 CLAUDE.md —— 手艺活:文件分层、什么该放哪,以及来自真实生产代码库的前后对比改写。第一次写、或要重写一份已经长歪的,从这篇开始。
2. 怎么保持精简
五个正在悄悄烧 token 的习惯 —— 一份臃肿的 CLAUDE.md 可能让整个团队每次会话的 token 成本多 30–60%。几乎每次审计都能看到的五个具体错误,以及修法。如果你的已经超过一屏,读这篇。
3. 怎么在团队里扩展
5 人以上团队的 CLAUDE.md 难题 —— 单人用 CLAUDE.md 没问题;到了五个工程师左右就开始翻车:规则漂移、互相矛盾。会坏在哪,以及修好它的四个习惯。如果不止一个人在改这个文件,读这篇。
4. CLAUDE.md vs AGENTS.md
Claude Code 到底读哪个? —— AGENTS.md 如今是 30 多个 agent 都读的跨厂商标准,但 Claude Code 仍然只读 CLAUDE.md。怎么同时用两个而不用维护两份,以及它们冲突时谁说了算。如果你的仓库(或团队)用了不止一个 agent,读这篇。
相关阅读
- Claude Code hooks(2026) —— 配置 Claude Code 的另一半:生命周期 hook、哪四个值得用、以及那个 fail-open 陷阱。
- AI 编程 agent 往你磁盘里写了什么 —— CLAUDE.md 和其它每个 agent 文件,在你机器上到底存在哪。
当你的 CLAUDE.md 已经长得管不住了
我们见得最多的情形:一份 CLAUDE.md 起初是五行有用的话,不知不觉变成两屏半真半假、自相矛盾、塞满个人偏好的指令,没人确定它到底有没有帮上忙。每次会话都在为它买单,在团队里这成本还要乘以每个人。
这正是 CLAUDE.md 审计要解开的结 —— 我们读你的指令文件,砍掉在烧钱的部分,还你一份精简、克制、token 友好的版本。个人文件 $299,2–10 人团队 $799。