在《国内环境下的Claude Code安装与使用教程》一文中，我们讲了Claude Code的安装、配置和一个最简单的使用案例。如果单纯从使用的角度来说，安装部署之后，便可以尽情发挥你的想象力，指挥AI为你做事了。
但如果你想把Claude Code用得更好，事半功倍，那么，还有一件非常重要的事，甚至可以说是安装部署之后第一件要做的事情是：与Claude Code签订一份契约，即定义CLAUDE.md文件。
这篇文章我们便围绕CLAUDE.md文件体系展开，详细讲讲Claude Code的CLAUDE.md文件以及一些最佳实践。
CLAUDE.md是个什么？
当你使用Claude Code一段时间，你一定会发现一个问题，那就是它经常忘记你曾经说过的话，特别是一些基本的编程规则和规范。
比如你要重复的告诉它：
- 使用严格的类型；
- 保持最小的改动（diff）操作；
- 不要加入没有要求的兜底逻辑；
- 不要因为一时兴起就重写半个文件；
- 等等；
每次对话或者时不时都要这样给AI提要求，的确是有些烦，也有些浪费。CLAUDE.md文件体系的出现就是为了解决这个问题，它可以在不同的作用域让AI来遵循你的基本约束和规范。
Claude Code在每次启动新会话时，第一件事就是读去CLAUDE.md文件。通过该文件Claude Code可以了解项目结构、代码风格、测试命令、常见陷阱等基本约束。CLAUDE.md可以说是Agent的「宪法」，是代码库中最重要的文件。
如果没有它的存在，Claude Code就像刚接手代码而且记性不太好的新同事，什么都得从头摸索，时不时你还要告诉它，向它强调该怎么做，想想就感觉累吧。
反之，我们可以将编码偏好、架构说明、命名规则、测试命令等通过CLAUDE.md文件来定义，这样在使用时只需关注核心业务逻辑即可。CLAUDE.md文件通常是逐步迭代的，当发现AI经常犯同样的错，就可以把对应的约束写入CLAUDE.md文件中。
Claude Code的约束体系
CLAUDE.md文件不仅仅是一个配置文件，它是Claude Code定义的一整套约束体系，Claude Code会自动按顺序读取多个位置的CLAUDE.md。
在这套体系当中CLAUDE.md，按照层级通常可以分为三个层级：全局CLAUDE.md文件、项目CLAUDE.md文件和本地CLAUDE.md文件。
全局CLAUDE.md文件：通常位于~/.claude/CLAUDE.md，是用户级的全局CLAUDE.md文件，所有项目都会加载，可保存长期稳定的编码偏好。比如上面提到的“使用严格的类型”、“保持最小的改动操作”，“注释用英文”等这类要求，都可以放在全局文件当中。
项目CLAUDE.md文件：通常位于./CLAUDE.md 或 ./.claude/CLAUDE.md，是共享的项目层文件，作用域某一个项目，可定义架构说明、命令、目录结构、命名规范、文档归类、技术栈约定、常见陷阱等。比如，“进行测试之前需要先执行xxx命令”这类跟具体项目有关的要求，则可放在项目文件当中。
项目文件还有一个延伸层——子目录文件，比如一个项目中既包含了前端代码又包含了后端代码，此时在前端代码和后端代码的根目录下存放不同的CLAUDE.md文件，避免前后端规范约束的相互干扰。
本地CLAUDE.md文件：通常位于项目根目录下的CLAUDE.local.md ，用来撰写开发者自己本地的项目备注，这个文件最好不要提交到Git仓库。
在上述三个CLAUDE.md文件中，重点需要关注全局CLAUDE.md文件和项目CLAUDE.md文件。
CLAUDE.md编写通用技巧
在了解具体的CLAUDE.md文件编写之前，我们先来了解一些通用的技巧和最佳实践。
虽然CLAUDE.md文件能够对AI提供一些具体的要求，但这些要求并不是越多越好，也不是越详细越好。初次使用最容易犯的错误就是事无巨细的，甚至包括API文档参数等都忘CLAUDE.md文件中写入。
我们前面已经提到，每次Claude Code开启会话时都会加载CLAUDE.md文件中的内容，如果写得太多，不仅吃掉大量上下文，消耗大量tokens，也会导致Claude Code“遗漏”部分内容，挤占真正要执行的操作指令，干扰执行效果。
Boris（Claude Code的创建者）团队的CLAUDE.md只有大约2500 tokens，大概100行。在中文环境下，实践得出的结论是：最好控制在80行以内，最多不超过200行。
在实践的过程中，一个比较好的策略是：从最小化的CLAUDE.md开始，然后基于Claude Code犯的错，逐步完善规范，AI每犯一次错就添加一条规则，而不是一次性编写一个完整的手册。
甚至可以尝试让Claude Code自己将它犯的错误写入CLAUDE.md文件，「Claude非常擅长为自己编写规则。」你告诉它犯了什么错，它自己就能写出精确的规则防止下次再犯。
另外，当你在思考一条规则是否适合写到规范当中时，有一个判断规则可以参考：Claude自己能从代码里读出来的，不要写；Claude猜不到的，必须写。
这里的规范与给开发人员看的规范稍有不同，比如标准的Java代码规范，在给开发人员看时，需要明确细节，因为开发人员可能不知道这些规范，但对于Claude Code来说，它是完全知道的，就不需要逐项写到文件当中。
Claude Code自生成规则案例
这里举一个简单案例，仅为大家提供一个操作思路和示例。这里以《国内环境下的Claude Code安装与使用教程》中生成的index.html项目为基础，让Claude Code来汇总规则。
首先让Claude Code在项目根目录创建一个CLAUDE.md文件（或手动创建也可以，不再演示），然后让它检查一下代码中的问题，由此来生成规则。
可以看到Claude Code提炼出的这个规则很明显过于详细，不符合上面所说的要求，让它进一步提炼精简一下。
此时可以看到CLAUDE.md中的规则已经变得更加精炼了，下面让Claude Code优化一下index.html中的代码，看它是否能够利用以上规则。
优化结果汇总：
可以看到Claude Code顺利的完成了错误的发现、规则的生成、规则的提炼以及利用规则来优化代码的操作。
全局CLAUDE.md文件实践
对于全局CLAUDE.md文件（后面简称，全局文件），Claude Code会读取的路径为~/.claude/CLAUDE.md的文件。如果安装之后，发现该目录没有对应的文件，可手动创建一个。
Linux（或MacOS）下创建指令：
touch ~/.claude/CLAUDE.md
如果已经存在该文件，直接编辑即可。
对于全局文件，在本机（或用户级别）的全局适用的，每个项目都会加载，因此该文件中的约束和规范一定需要简约。通常，定义那些在不同仓库中反复出现、确实重要的规则。
全局文件根据不同的开发者、所使用的AI、团队规范等又有所不同，比如有的开发者更侧重一些编码限制，比如严格的类型、显式的错误处理、最小化修改等等。
一些简单的规则示例：
## 沟通方式
- 默认中文，代码、命令、变量名用英文
## 代码风格
- 注释仅使用英文
- 遵循 DRY、KISS 和 YAGNI 原则
## 错误处理
- 始终显式抛出错误，绝不静默忽略
- 使用能清楚表达问题原因的具体错误类型
- 错误信息必须包含足够的调试上下文：请求参数、响应体、状态码
- 日志应使用结构化字段，而不是把动态值插值进消息字符串里
## 终端使用
- 优先使用带参数的非交互式命令，而不是交互式命令
- 始终使用非交互式 git diff：`git --no-pager diff` 或 `git diff | cat`
- 优先使用 `rg` 搜索代码和文件
## Claude Code 工作流
- 修改前先阅读现有代码和相关 `CLAUDE.md` 文件
- 保持改动最小，并且只围绕当前请求
- 即使仓库风格与我的个人偏好不同，也应匹配现有仓库风格
- 不要回退无关改动
- 如果不确定，就检查代码库，不要凭空发明模式
- 如果项目指令中包含测试或 lint 命令，并且这次任务修改了代码，那么完成前应运行这些命令
上面这些只是示例，可根据具体情况，把部分规则写入项目级别的文件当中。
也有的使用者并不是开发人员或者不是用来开发软件，那就需要在该文档中定义好“我是谁”、“思考问题的原则”等。比如：
## 关于我
我叫XXX，是一名产品经理，在做XXX领域的产品探索。
我使用Claude Code主要用来做XXX的MVP产品尝试。
## 思维原则
所有决策从问题本质出发，不因「惯例如此」照搬。
回到问题本身：要解决什么？最直接的路径是什么？从零设计会怎么做？
总之，根据不同的角色、不同的需求、不同习惯以及不同的实践经验，可以把共用性的约束写在全局文件内。
项目CLAUDE.md文件实践
在通用技巧中，我们通过自然语言让Claude Code在项目根目录生成了一个CLAUDE.md文件，这个文件就属于项目级别的CLAUDE.md文件。
顾名思义，该文件主要是针对具体的某个项目来进行约束的，比如包含命令、架构、命名和边界等，相对全局约束来说，更具体，更有针对性，更具有场景化。
前面我们通过自然语言创建了一个空白文件，并且逆向提炼了一些规则。实际上，Anthropic专门提供了一个/init命令来说初始化一个项目CLAUDE.md文件，来生成一个初稿。
执行/init指令，Claude Code会根据当前项目的情况，来生成一个初始化的CLAUDE.md文件。
完整内容如下：
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is a simple static HTML demo page that displays a "Hello, Claude Code!" message with a Matrix-style falling characters animation. The project consists of a single `index.html` file with embedded CSS and JavaScript.
## Development
To view the page, open `index.html` in a web browser directly, or serve it with any static file server:
```bash
# Using Python
python3 -m http.server 8000
# Using Node.js (npx)
npx serve .
```
可以看到，虽然生成了一个基础的文件和一些内容，只是一个草稿，但是效果并不理想。此时，可以通过指令让AI将内容改为中文。另外，后续也需要开发者手动修改或通过沟通、探讨让AI自己来添加规则（上面已经演示过了）。
这个沟通修改的过程，实践的越多，你会发现越有意思，也能够沉淀不少经验，重要的是要去尝试。
小结
这篇文章重点介绍了在使用Claude Code时最核心最重要的一件事，就是CLAUDE.md体系内规则与约束的配置。先了解了CLAUDE.md体系，以及该文件的通用编写最佳实践，以及针对不同层级CLAUDE.md文件的编写案例。
关于案例部分属于抛砖引玉，场景不同描述不同，大家可自行迭代。我们需要关注的也不是具体的规则，也是这件事本身以及后续的迭代。后续我们将继续分享一些Claude Code的功能及最佳实践，点一下，持续关注。
