今天分享的主题是CLAUDE.md ，本篇讲介绍它作为项目说明书的场景。
什么是 CLAUDE.md
CLAUDE.md 是项目根目录的一个文件，告诉 Claude 这个项目的基本信息。
Claude 每次启动会自动读取这个文件，所以你不用每次都解释项目背景。
创建 CLAUDE.md
在项目根目录创建：
bash
cat > CLAUDE.md << 'EOF'
# 计算器项目
## 技术栈
TypeScript + Node.js
## 项目结构
src/
calculator.ts --- 计算器核心逻辑
utils.ts --- 工具函数
tests/
calculator.test.ts --- 测试文件
## 编码规范
• 函数名用 camelCase
• 必须写 JSDoc 注释
• 每个函数要有对应的测试
## 注意事项
• 除法要处理除数为 0 的情况
• 所有数字用 number 类型
EOF验证 CLAUDE.md 生效
启动 Claude Code：
bash
claude输入：
这个项目的编码规范是什么？Claude 自动读取了 CLAUDE.md 的内容。
Claude中推荐写的内容
CLAUDE.md 建议包含：
- 项目简介 --- 这是什么项目，解决什么问题
- 技术栈 --- 语言、框架、主要依赖
- 项目结构 --- 主要目录和文件的说明
- 编码规范 --- 命名、注释、代码风格
- 注意事项 --- 容易踩坑的地方
实际案例
来自 modelcontextprotocol/servers 项目（MCP 官方参考服务器实现）：
markdown
# 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这个案例展示了 CLAUDE.md 的典型结构：项目概述、目录结构、构建命令、代码风格。信息简洁但关键。
优先级
CLAUDE.md 有两个级别：
| 级别 | 位置 | 优先级 |
|---|---|---|
| 项目级 | 项目根目录 | 高 |
| 全局级 | ~/.claude/ | 低 |
当两个文件同时存在时，Claude 会合并读取，项目级的配置会覆盖全局的同名配置。
建议：项目相关写项目级 CLAUDE.md，通用偏好写全局 CLAUDE.md。
最佳实践
- 控制在 500 字以内，只写关键信息
- 提交到 Git，团队成员共享
- 项目变动时及时更新
避坑提示
别写太长。
太长的 CLAUDE.md：
- Claude 每次启动要花时间读
- 可能记不住所有内容
建议：只写关键信息，控制在 500 字以内，使得Claude能够抓住重点，也可以省去每次加载的token量。