搞懂 CLAUDE.md：给 Claude Code 写一份专属的「项目说明书」

如今 AI 编码助手已经成了开发日常的标配，Claude Code 凭借强大的代码理解和终端操作能力，成为很多人写代码、改 Bug、重构项目的效率工具。但很多人都会遇到同一个痛点：每次开新对话，都要从头跟 Claude 解释一遍「这是什么项目」「用了什么技术栈」「代码要遵循什么规范」「哪里有坑要注意」。

说少了 AI 理解不到位，生成的代码不符合预期；说多了又浪费时间和 Token，反复做重复劳动。

有没有办法让 Claude 一进入项目就「心里有数」？答案就是 CLAUDE.md —— 一个放在项目根目录的小小 Markdown 文件，就能让 Claude 自动掌握项目全貌，从根源上解决每次重复铺垫上下文的问题。

一、到底什么是 CLAUDE.md？

CLAUDE.md 是专门为 Claude Code 设计的项目说明文件，通常放置在项目的根目录下。Claude Code 每次启动会话时，会自动从当前目录向上递归查找并读取这个文件，将其中的内容注入到系统提示中，作为全程生效的全局上下文。

简单来说，它就是你写给 Claude AI 看的「项目说明书」。有了它，Claude 不用你每次开口介绍，就能默认知道项目的背景、规则和约束。

它和项目里的 README 有本质区别：README 是写给人看的，内容全面且偏向项目介绍与使用说明；而 CLAUDE.md 是写给 AI 看的，只保留最核心的开发相关信息，目的是让 AI 快速抓住重点，生成符合项目要求的代码。

二、为什么你一定要配置 CLAUDE.md？

别看只是一个几十行的小文件，它带来的体验提升非常明显：

1. 省去重复上下文，提升对话效率
   不用每次开新对话都重复讲解技术栈、目录结构、命名规范，启动 Claude 就能直接进入正题，大幅减少无效铺垫。

2. 输出更稳定，代码风格统一
   把编码规范、类型要求、命名规则写进文件，Claude 生成的代码会始终遵循项目约定，不会出现风格忽左忽右的情况。

3. 提前规避常见坑点
   把边界情况、特殊业务规则、容易出错的地方提前说明，比如「除法必须处理除数为 0」「所有接口必须加异常捕获」，能显著降低 AI 写出问题代码的概率。

4. 团队协作认知一致
   将 CLAUDE.md 提交到 Git 仓库，所有团队成员使用 Claude 时都会加载同一套项目规则，避免每个人描述不一致导致的代码风格差异。

三、手把手：创建并验证你的第一个 CLAUDE.md

1. 创建文件

在项目根目录新建一个名为 CLAUDE.md 的文件即可。你可以手动编写，也可以在 Claude Code 中输入 /init 命令，让 AI 扫描项目后自动生成一份初稿，再手动调整补充。

这里给一个最简单的完整示例：一个 TypeScript 实现的计算器项目：

# 计算器项目

## 技术栈
TypeScript + Node.js

## 项目结构
src/
  calculator.ts  — 计算器核心逻辑
  utils.ts       — 通用工具函数
tests/
  calculator.test.ts — 单元测试文件

## 编码规范
- 函数名使用 camelCase 命名
- 所有导出函数必须写 JSDoc 注释
- 每个核心函数必须配套对应的单元测试

## 注意事项
- 除法运算必须处理除数为 0 的异常情况
- 所有数值统一使用 number 类型

一行命令就能快速创建：

cat > CLAUDE.md << 'EOF'
# 计算器项目

## 技术栈
TypeScript + Node.js

## 项目结构
src/
  calculator.ts  — 计算器核心逻辑
  utils.ts       — 通用工具函数
tests/
  calculator.test.ts — 单元测试文件

## 编码规范
- 函数名使用 camelCase 命名
- 所有导出函数必须写 JSDoc 注释
- 每个核心函数必须配套对应的单元测试

## 注意事项
- 除法运算必须处理除数为 0 的异常情况
- 所有数值统一使用 number 类型
EOF

2. 验证是否生效

在终端启动 Claude Code：

claude

直接提问：

这个项目的编码规范是什么？

如果 Claude 能准确说出你写在文件里的规则，就说明 CLAUDE.md 已经被成功读取并生效了。

四、一份合格的 CLAUDE.md 该写什么？

不用写得面面俱到，更不用把整个项目文档都搬进来。核心覆盖以下 6 个模块，就能满足绝大多数开发场景：

模块	说明
项目简介	一句话讲清项目定位、核心用途和解决的问题
技术栈	开发语言、框架版本、核心依赖、运行环境
项目结构	关键目录与核心文件的作用，告诉 AI 去哪找代码
编码规范	命名规则、注释要求、代码风格、类型约束
构建与测试	常用的启动、构建、测试、部署命令
注意事项	边界情况、踩坑点、特殊业务规则、禁止操作

真实参考案例

我们来看 MCP（Model Context Protocol）官方参考服务器项目的 CLAUDE.md，这是非常标准的工业级写法：

# CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

## Project Overview
Official MCP reference server implementations. This is an npm workspaces monorepo
containing 7 servers (4 TypeScript, 3 Python) under src/.

## Monorepo Structure
src/
  everything/          TS  @modelcontextprotocol/server-everything
  filesystem/          TS  @modelcontextprotocol/server-filesystem
  memory/              TS  @modelcontextprotocol/server-memory
  ...

## Build & Test Commands
### TypeScript servers
cd src/<server> && npm ci && npm run build && npm test

### Python servers
cd src/<server> && uv sync --frozen --all-extras --dev
uv run pytest

## Code Style
### TypeScript
- ES modules with .js extension in import paths
- Strict TypeScript typing for all functions
- Zod schemas for tool input validation
- camelCase for variables/functions, PascalCase for types/classes

### Python
- Type hints enforced via pyright
- Async/await patterns

可以看到，整个文件信息密度很高，没有冗余内容，项目定位、目录结构、构建命令、代码风格一目了然，非常值得参考。

五、两级配置规则：项目级 vs 全局级

CLAUDE.md 支持两级配置，优先级各不相同：

级别	存放位置	优先级	适用场景
项目级	项目根目录 ./CLAUDE.md	高	当前项目专属的规则与信息
全局级	用户目录 ~/.claude/CLAUDE.md	低	所有项目通用的个人偏好

当两个文件同时存在时，Claude 会合并读取两者的内容，当出现同名配置项时，项目级配置会覆盖全局级配置。

建议：项目相关的技术栈、结构、规范写在项目级 CLAUDE.md 并提交到 Git；个人通用的代码风格偏好、输出习惯写在全局级配置中。

除此之外，子目录中也可以放置 CLAUDE.md，当 Claude 进入对应子目录工作时，会加载该目录下的配置，适合大型 monorepo 项目分模块管理规则。

六、最佳实践与避坑指南

✅ 最佳实践

1. 控制篇幅，只写核心
   官方建议控制在 200 行、500 字以内。内容越精简，AI 抓重点越准，同时也能减少 Token 消耗。

2. 纳入版本控制
   将 CLAUDE.md 提交到 Git 仓库，团队成员共享，随项目迭代同步更新。

3. 善用引用语法
   如果有详细规范写在其他文件里，可以用 @ 语法引用，比如 请参考 @docs/coding-style.md 查看完整编码规范，避免内容重复。

4. 项目变动及时更新
   技术栈升级、目录调整、规范变更时，同步更新 CLAUDE.md，保证信息准确。

❌ 避坑提醒

最常见的误区就是把 CLAUDE.md 写成了完整项目文档。

内容过长会带来两个问题：

• 浪费 Token：Claude 每次启动都会全程加载这些内容，不管当天的任务是否相关，平白增加开销；
• 稀释重点：信息太多反而会让 AI 忽略真正关键的约束，导致核心规则不生效。

记住：CLAUDE.md 是「重点速览」，不是「开发手册」，准确比全面更重要。

写在最后

CLAUDE.md 是一个成本极低、收益很高的开发小配置。只用几十行文字，就能大幅提升 Claude Code 的使用体验和输出质量，不管是个人项目还是团队协作，都值得花几分钟配置一份。

下次打开 Claude 写代码之前，先给你的项目写一份专属的「AI 说明书」吧。