编辑 - CLAUDE.md 是什么？ - 个人运维平台

取消

## 一句话理解

**CLAUDE.md** 是放在项目根目录下的一个 Markdown 文件，用来告诉 Claude Code 你的项目是什么、怎么运行的。相当于给 Claude 的"项目说明书"。

没有 CLAUDE.md 时，Claude 只能从代码中自己推断项目信息，效果会打折扣。有了它，Claude 能更准确地理解你的项目上下文。

## 为什么需要它？

每次启动 Claude Code，它会自动读取 `CLAUDE.md` 文件。这个文件帮助 Claude 了解：

- **技术栈**：用什么语言、框架、数据库、工具链
- **目录结构**：每个目录存放什么内容
- **常用命令**：开发、测试、构建、部署怎么运行
- **代码规范**：命名约定、目录约定、设计模式
- **常见问题**：已知的坑、特殊配置、注意事项

## 一个完整的示例

```markdown
# My Express API

## 技术栈
- 运行时：Node.js 20 + TypeScript
- 框架：Express 4 + Prisma ORM
- 数据库：PostgreSQL 16
- 测试：Vitest + Supertest
- 包管理：pnpm

## 目录结构
- src/              源代码
  - routes/         API 路由定义
  - middleware/     中间件（鉴权、日志、错误处理）
  - services/       业务逻辑层
  - models/         数据模型定义
  - utils/          工具函数
- prisma/           数据库 schema 和迁移
  - schema.prisma   数据模型定义
- tests/            测试文件（镜像 src/ 结构）
  - routes/         接口测试
  - services/       单元测试

## 常用命令
- pnpm dev          启动开发服务器（热重载）
- pnpm build        编译 TypeScript
- pnpm test         运行所有测试
- pnpm test:watch   监听模式运行测试
- pnpm lint         代码规范检查
- pnpm migrate      执行数据库迁移
- pnpm seed         填充测试数据

## 开发约定
1. 所有 API 路由放在 src/routes/ 下，按模块拆分
2. 数据库操作通过 Prisma Service 层，不直接在路由中调用
3. 错误处理统一使用 src/middleware/errorHandler.ts
4. API 返回格式：{ code, data, message }
5. 提交信息使用 Conventional Commits 规范
6. 新功能必须包含单元测试和接口测试

## 环境变量
- DATABASE_URL    PostgreSQL 连接地址
- JWT_SECRET      JWT 签名密钥
- PORT            服务端口（默认 3000）
```

## 如何创建？

### 方式一：自动生成

在项目目录中启动 Claude Code，选择生成项目文档：

```bash
cd your-project
claude
# 首次启动时选择"生成项目文档"
```

或用 /init 命令：

```bash
/init
```

Claude 会自动扫描项目并生成 CLAUDE.md。

### 方式二：手动创建

在项目根目录创建 `CLAUDE.md` 文件，写入项目上下文。

### 方式三：让 Claude 生成

```bash
claude "分析当前项目，生成一份 CLAUDE.md"
```

Claude 会读取项目文件，自动整理出技术栈、目录结构、命令等信息。

## 写什么内容？

| 内容 | 重要性 | 说明 |
|------|--------|------|
| 技术栈 | ⭐⭐⭐ | 语言、框架、数据库、工具版本 |
| 目录结构 | ⭐⭐⭐ | 每个目录的用途 |
| 常用命令 | ⭐⭐⭐ | 开发/测试/构建/部署命令 |
| 代码规范 | ⭐⭐ | 命名、目录约定、设计模式 |
| 环境变量 | ⭐⭐ | 需要配置哪些变量 |
| 架构说明 | ⭐⭐ | 核心模块的职责和关系 |
| 常见问题 | ⭐ | 已知的坑和解决方案 |
| 部署流程 | ⭐ | 发布步骤和注意事项 |

## 和 Memory 的区别

| | CLAUDE.md | Memory |
|---|-----------|--------|
| 作用范围 | **项目级别** | **全局级别** |
| 存放位置 | 项目根目录 | .claude/projects/-root/memory/ |
| 内容 | 项目本身的说明 | 你的个人偏好和习惯 |
| 是否提交 Git | ✅ 会提交 | ❌ 仅本地 |
| 谁维护 | 项目成员共同维护 | 你自己 |

> 简单说：**CLAUDE.md 告诉 Claude 项目是什么**，**Memory 告诉 Claude 你是谁、怎么工作**。

## 注意事项

- **不要写敏感信息**：密码、API 密钥不应放在 CLAUDE.md 中
- **保持更新**：技术栈变更后同步更新
- **简洁清晰**：关键信息到位即可，不是越长越好
- **中英文皆可**：用你舒服的语言写
- **结合 README**：CLAUDE.md 是给 AI 看的，README 是给人看的，可以互补

## 💡 实际使用场景

### 场景：用 CLAUDE.md 加速新成员 onboarding

前端组来了个新人小刘，项目 README 过时了。TL 花 15 分钟写了一份 CLAUDE.md：

```markdown
# 电商后台管理系统

## 技术栈
React 18 + TypeScript + Ant Design + Zustand + Vite

## 目录说明
- src/pages/ — 页面组件
- src/components/ — 通用组件
- src/store/ — 全局状态
- src/api/ — 接口调用

## 本地开发
npm install → npm run dev → 访问 localhost:5173
```

小刘拿到项目后运行 `claude`，Claude 自动读取了 CLAUDE.md。小刘输入：

```
根据 CLAUDE.md 的介绍，带我理解这个项目的核心业务流程
```

Claude 结合项目代码和文档说明，带小刘一步步走通了主要页面和数据处理流程。

### 场景：为开源项目贡献代码

小张想给一个开源项目提 PR。他先 fork 了项目，然后创建 CLAUDE.md：

```
claude "分析项目的代码风格和贡献指南，帮我生成一份适合这个项目的 CLAUDE.md"
```

Claude 读完了 CONTRIBUTING.md 和现有代码后，生成的 CLAUDE.md 包含了代码规范、测试要求、提交信息格式。小张基于这份文档，后续每次提交前 Claude 都能自动遵循项目规范。

### 场景：脚手架项目标配

团队的所有新项目模板都内置了一份 CLAUDE.md，包含技术栈和目录规范。新项目启动时，开发者只需运行 `claude`，Claude 就能直接理解项目结构开始工作，不需要额外解释。

预览

编辑内容后实时预览...