Claude Code 真正的核心：30分钟学会写好 CLAUDE.md

很多人疯狂折腾插件、Hook、Agent。

但真正决定 Claude Code 上限的，往往只是一个 CLAUDE.md。

如果 AI 编程工具有一张进化路线图

如果把近几年 AI 编程工具的发展画成一张地图，那么 Claude Code 大概率会是其中一个关键节点。

2025 年 2 月，Anthropic 首次推出 Claude Code Early Preview；到 2025 年 5 月，它已经逐渐进入更广泛的开发团队。

它真正改变的，并不是“又多了一个聊天窗口”。

而是：

• AI 开始真正进入终端
• 能读取整个代码仓库
• 能编辑文件
• 能运行命令
• 能定位 Bug
• 能推进任务执行

从这一刻开始，软件开发的协作方式开始发生变化。

而在 Claude Code 的世界里，有一个极其关键、却经常被低估的文件：

CLAUDE.md

很多人折腾半天插件和 Rules，最后发现：

一个写得好的 CLAUDE.md，往往比十几个插件更有效。

因为它真正改变的是：

AI 与项目之间的协作方式。

01｜什么是 CLAUDE.md？

CLAUDE.md 本质上是一个 Markdown 文件。

Claude Code 会在每次会话启动时自动读取它，并将其中的内容作为长期上下文。

你可以在里面编写：

• 项目说明
• 开发规范
• 技术约束
• 工作流程
• 个人偏好

随后 Claude Code 会在整个协作过程中持续遵循这些规则。

很多开发者喜欢用一个经典梗图来形容这种体验：

左边是装备复杂、插件拉满的选手； 右边是单手插兜、只靠一个 CLAUDE.md 的“土耳其射击哥”。

虽然只是玩笑，但它确实点出了核心：

与其疯狂堆配置，不如认真写好 CLAUDE.md。

一个简单示例

复制# 项目说明

有关项目概述，请参见 @README.md  
有关可用命令和脚本，请参见 @package.json  
有关测试约定，请参见 @docs/testing.md  
有关 API 设计规则，请参见 @docs/api-guidelines.md
md

看起来只是几行文本，但已经足够让 Claude Code：

• 快速理解项目结构
• 找到关键文档
• 遵循已有规范
• 避免到处乱猜

它的核心价值在于：

把 Claude Code 从“通用 AI”，变成“真正理解项目的开发助手”。

02｜CLAUDE.md 是怎么加载的？

很多人以为：

CLAUDE.md 只是项目根目录里的一个 Markdown 文件。

实际上并不是。

Claude Code 使用的是一种“分层加载”的机制。

不同位置的 CLAUDE.md，作用范围也不同。

三种作用域

1. 用户级（全局）

作用于所有项目。

适合放：

• 通用编码习惯
• 默认代码风格
• 常用工具偏好

例如：

复制默认使用 pnpm
优先使用 TypeScript
提交前必须运行 lint
md

2. 项目级（仓库根目录）

作用于当前仓库。

适合放：

• 项目架构说明
• 团队规范
• 特殊约束
• CI/CD 规则

3. 子目录级（局部目录）

只在特定目录生效。

适合：

• 微服务
• Monorepo 子模块
• 特殊业务目录
• 独立技术栈

例如：

复制/apps/admin/CLAUDE.md
/packages/sdk/CLAUDE.md
bash

加载规则

Claude Code 的读取逻辑大致如下：

1. 启动时读取当前工作目录相关的 CLAUDE.md
2. 同时加载用户级配置
3. 当 AI 实际进入某个子目录时，再动态加载对应目录的 CLAUDE.md

也就是说：

子目录规则不是一开始全部加载，而是“按需激活”。

这样既减少上下文消耗，也提高规则准确性。

冲突怎么处理？

Claude Code 使用的是：

最近范围原则

谁离当前任务最近，谁优先级最高。

例如：

用户级规则：

复制使用 4 空格缩进
md

项目级规则：

复制统一使用 2 空格缩进
md

那么在当前项目里：

Claude Code 会优先使用 2 空格。

简单理解：

越具体、越靠近当前任务的规则，权重越高。

03｜如何编写 CLAUDE.md？

很多人第一次写时，会陷入一种“文档完美主义”。

结果：

• 写了几千字
• AI 抓不到重点
• 上下文大量浪费

正确做法其实非常简单：

先写最有价值的信息

第一步：直接生成初稿

进入项目目录后运行：

复制claude
bash

然后输入：

复制/init
bash

Claude Code 会自动分析：

• 技术栈
• 项目结构
• 常用命令
• 目录组织

并帮你生成一个基础版本。

通常已经能覆盖 60% 的需求。

第二步：优先补充高价值信息

建议优先添加以下内容：

常用命令

例如：

复制开发启动：
pnpm dev

运行测试：
pnpm test

代码检查：
pnpm lint

构建：
pnpm build
md

这样 AI 就不会反复猜命令。

项目特殊约束

例如：

复制不要修改 src/generated 下的文件
数据库使用软删除
所有接口必须经过 auth middleware
md

这些信息能极大减少 AI 犯错。

工作流程

例如：

复制提交前必须运行 lint
分支命名使用 feature/*
PR 必须附带测试结果
md

架构上下文

尤其是 Monorepo 项目，非常重要。

例如：

复制/apps 为应用层
/packages 为共享模块
禁止跨层直接引用
md

一个判断标准

如果一条信息：

• 不能帮助 AI 更快理解项目
• 不能减少常见错误
• 不能提高任务执行准确率

那就先别写进去。

04｜文件变大后怎么办？

随着项目发展，CLAUDE.md 一定会越来越长。

这时候千万别把所有内容硬塞进一个文件。

否则会出现：

• 上下文污染
• 重点模糊
• Token 浪费
• AI 忽略规则

正确做法是：

拆分文件 + 使用引用

例如：

复制# 项目说明

@README.md
@docs/testing.md
@docs/api-guidelines.md
md

把：

• 测试规范
• API 规范
• 部署流程
• 代码风格

分别拆到独立文档。

主 CLAUDE.md 只保留“导航作用”。

这样会清爽很多。

05｜CLAUDE.md 最重要的能力：持续进化

真正优秀的 CLAUDE.md，

几乎都不是一次性设计出来的。

而是：

在反复协作中逐渐沉淀出来的。

如何持续优化？

1. 把重复错误写成规则

比如你发现 Claude Code 总是：

• 用 npm 而不是 pnpm
• 把测试文件放错目录
• 修改 schema 后忘记重新生成代码

那就把这些问题直接写进去。

例如：

复制统一使用 pnpm，不要使用 npm

测试文件统一放在 __tests__ 目录

修改 schema 后必须运行：
pnpm codegen
md

每修复一次问题，就给 AI 增加一次“长期记忆”。

2. 会话结束后做总结

你可以在每轮协作结束后，让 Claude Code：

复制总结本轮有哪些内容值得加入 CLAUDE.md
txt

它通常会帮你提炼出：

• 新规则
• 易错点
• 项目约束
• 流程依赖

这比纯手工维护高效很多。

3. 利用 Insights 回顾长期问题

相比单次会话：

Insights 更适合发现：

• 哪些问题反复出现
• 哪些规则已经稳定
• 哪些内容值得正式沉淀

这是一种“长期项目记忆”的思路。

06｜CLAUDE.md 最佳实践

1. 保持简洁

很多人喜欢往里面塞大量背景介绍。

结果：

AI 真正关注的信息反而被淹没。

记住：

CLAUDE.md 是上下文，不是项目百科全书。

越短、越明确，效果越好。

2. 规则必须可执行

不要写：

复制请保持代码优雅
md

这种描述对 AI 几乎没有约束力。

更有效的写法：

复制新增接口必须添加 Vitest 测试
提交前必须运行 pnpm lint
md

能执行，才有效。

3. 解释规则背后的原因

不要只告诉 AI：

复制不要修改 src/generated
md

而应该进一步说明：

复制src/generated 为 OpenAPI 自动生成目录，
真正的数据源是 schema 文件。
修改后应重新生成，而不是直接编辑输出文件。
md

这样 AI 才能真正理解：

• 为什么不能改
• 应该改哪里
• 正确流程是什么

这会显著提升任务判断能力。

4. 使用渐进式披露

不要把所有内容都堆进根目录。

更推荐：

• 主 CLAUDE.md 放核心规则
• 复杂内容拆分到 docs
• 子模块使用局部 CLAUDE.md

这样既节省上下文，也更容易维护。

5. 永远不要写入敏感信息

千万不要在 CLAUDE.md 中存放：

• API Key
• Token
• 密码
• 私钥
• 数据库账号

因为：

它极有可能进入 Git 仓库。

这是很多团队容易忽略的安全风险。

07｜和其他 AI 编码工具有什么区别？

目前很多 AI 编码工具都有类似机制。

比如：

• Gemini CLI
• Codex
• OpenCode
• Droid

但 Claude Code 的优势在于：

分层上下文管理

它不是简单地“读取一个文件”。

而是：

• 支持多层级作用域
• 支持动态加载
• 支持局部规则覆盖
• 更适合复杂项目

尤其在：

• Monorepo
• 多团队协作
• 大型工程
• 长期维护项目

中的优势会非常明显。

总结

很多人刚接触 Claude Code 时，会把精力放在：

• 插件
• Hook
• Agent
• 自动化脚本

但真正决定体验上限的，

往往是：

CLAUDE.md

它的本质，是把：

• 项目经验
• 开发规则
• 团队习惯
• 架构约束

转化成 AI 可长期理解的上下文。

最好的方式从来不是：

第一天就写出完美文档。

而是：

从一个能用的版本开始，在真实协作中不断迭代。

当你的 CLAUDE.md 越来越成熟时，你会明显感受到：

Claude Code 不再只是“会写代码”。

而是真正开始“理解你的项目”。