Skip to content

第四章:CLAUDE.md 项目记忆

4.1 为什么需要 CLAUDE.md

想象一下这个场景:

你每天早上到办公室,需要和一个助手协作。但这个助手每天都是"崭新"的——他不记得昨天你们讨论过什么、项目的规范是什么、团队的编码习惯是怎样的。每次你都需要重新交代一遍。

CLAUDE.md 就是解决这个问题的。

CLAUDE.md 是一个特殊的 Markdown 文件,Claude Code 在每次启动时会自动读取它。你可以把项目的关键信息写在里面,这样 Claude Code 每次启动都能"记住"这些信息,不需要你反复交代。

一句话总结

CLAUDE.md = Claude Code 的"记忆文件"。写一次,每次启动自动加载。

4.2 CLAUDE.md 的三个层级

CLAUDE.md 不是只有一个文件,它有三个层级,从宽到窄分别是:

┌─────────────────────────────────────────┐
│ 层级1:用户级(全局)                      │
│ ~/.claude/CLAUDE.md                     │
│ 作用范围:你所有的项目                     │
│ 内容:个人偏好、通用习惯                   │
├─────────────────────────────────────────┤
│ 层级2:项目级(项目根目录)                 │
│ /your-project/CLAUDE.md                 │
│ 作用范围:当前项目                        │
│ 内容:项目信息、技术栈、编码规范            │
├─────────────────────────────────────────┤
│ 层级3:目录级(子目录)                    │
│ /your-project/src/CLAUDE.md             │
│ 作用范围:特定目录                        │
│ 内容:该目录/模块的特殊说明                │
└─────────────────────────────────────────┘

层级1:用户级 CLAUDE.md

位置: ~/.claude/CLAUDE.md

这个文件对你电脑上的所有项目都生效。适合放一些跨项目的通用偏好。

Windows 路径:C:\Users\你的用户名\.claude\CLAUDE.md
macOS 路径:  /Users/你的用户名/.claude/CLAUDE.md
Linux 路径:  /home/你的用户名/.claude/CLAUDE.md

适合放什么内容:

  • 你的语言偏好(比如"请用中文回复")
  • 你的代码风格偏好
  • 你常用的工具和库
  • 通用的工作流程

示例内容:

markdown
# 个人偏好

## 语言
- 请使用中文回复
- 代码注释使用中文
- 变量名和函数名使用英文

## 代码风格
- 使用 2 个空格缩进
- 字符串统一使用单引号
- 文件末尾保留空行

## 通用习惯
- 修改文件前先说明要做什么改动
- 生成代码时添加适当的注释
- 如果不确定需求,先问我确认再动手

层级2:项目级 CLAUDE.md

位置: 项目根目录下的 CLAUDE.md,或 .claude/CLAUDE.md

这是最常用的层级。每个项目一个,包含项目特定的信息。项目级 CLAUDE.md 可以放在两个位置:

your-project/
├── CLAUDE.md              <-- 项目级(位置一)
├── .claude/
│   └── CLAUDE.md          <-- 项目级(位置二,.claude 目录内)
├── package.json
├── src/
└── ...

两个位置的效果相同,如果两者同时存在则都会被加载。将 CLAUDE.md 放在 .claude/ 目录下可以保持项目根目录更整洁。

CLAUDE.local.md —— 个人项目级指令:

除了团队共享的 CLAUDE.md,你还可以创建 CLAUDE.local.md 用于存放个人的、不需要提交到 Git 仓库的项目级指令:

your-project/
├── CLAUDE.md              <-- 团队共享,提交到 Git
├── CLAUDE.local.md        <-- 个人使用,已被 gitignore
├── package.json
└── ...

CLAUDE.local.md 会被 Claude Code 自动添加到 .gitignore 中,适合放置个人偏好或本地环境相关的指令,比如本地调试端口、个人的代码审查偏好等。

适合放什么内容:

  • 项目概述和业务背景
  • 技术栈说明
  • 编码规范
  • 常用命令
  • 项目结构说明
  • 特殊注意事项

层级3:目录级 CLAUDE.md

位置: 项目子目录中的 CLAUDE.md

当项目的某个目录有特殊的规范或说明时,可以在该目录下放一个 CLAUDE.md。

your-project/
├── CLAUDE.md              <-- 项目级
├── src/
│   ├── CLAUDE.md          <-- src 目录级
│   ├── components/
│   │   └── CLAUDE.md      <-- components 目录级
│   └── api/
│       └── CLAUDE.md      <-- api 目录级
└── ...

适合放什么内容:

  • 该目录的模块说明
  • 该模块特有的编码规范
  • 组件的命名和文件组织约定
  • API 接口的设计规范

层级优先级

当多个层级的 CLAUDE.md 存在冲突时,更具体的层级优先。也就是说:

目录级 > 项目级 > 用户级

例如,如果用户级说"使用 2 空格缩进",但项目级说"使用 4 空格缩进",Claude Code 会遵循项目级的设置。

4.3 如何创建 CLAUDE.md

方法一:使用 /init 自动生成

最简单的方法是让 Claude Code 帮你生成。在项目目录中启动 Claude Code,然后运行:

> /init

 ✻ Analyzing your project...

  I've analyzed your project structure and created a CLAUDE.md file.

  The file includes:
  - Project overview
  - Tech stack
  - Project structure
  - Common commands
  - Coding conventions

  Would you like me to customize it further?

/init 会自动分析你的项目(读取 package.json、查看目录结构、识别技术栈等),然后生成一个初始的 CLAUDE.md。

/init 生成后的优化

/init 自动生成的内容是一个不错的起点,但通常需要你根据实际情况做一些补充和调整。建议生成后仔细阅读并添加项目特有的信息。

方法二:手动创建

你也可以手动创建 CLAUDE.md 文件。在项目根目录下创建一个名为 CLAUDE.md 的文件,然后写入内容。

bash
# 在项目根目录下创建文件
touch CLAUDE.md

然后用你喜欢的编辑器打开这个文件,写入项目信息。

方法三:让 Claude Code 帮你写

你可以在交互式对话中让 Claude Code 帮你写一个更详细的 CLAUDE.md:

> 帮我创建一个详细的 CLAUDE.md 文件。
  这个项目是一个电商后台管理系统,
  使用 React + TypeScript + Ant Design,
  后端 API 是 RESTful 风格的。
  我们团队的编码规范是...

 ✻ 好的,我来为你创建一个详细的 CLAUDE.md...
  [生成并保存文件]

4.4 CLAUDE.md 内容最佳实践

一个好的 CLAUDE.md 应该包含以下几个部分。让我们逐一来看。

4.4.1 项目概述

告诉 Claude Code 这个项目是做什么的,业务背景是什么。

markdown
# 项目概述

## 项目名称
城市军团电商后台管理系统(City Legion Admin)

## 业务背景
这是城市军团的内部电商管理平台,主要供运营人员和客服团队使用。
系统管理商品、订单、用户、营销活动等核心业务。

## 目标用户
- 运营人员:管理商品和营销活动
- 客服人员:处理订单和用户问题
- 管理员:系统配置和权限管理

为什么项目概述很重要?

当你问 Claude Code "帮我添加一个新功能"时,它如果知道项目的业务背景,就能更好地理解你的需求,生成更符合业务逻辑的代码。

4.4.2 技术栈

列出项目使用的所有技术和版本。

markdown
## 技术栈

### 前端
- **框架**:React 18.2
- **语言**:TypeScript 5.3
- **UI 库**:Ant Design 5.x
- **状态管理**:Zustand 4.x
- **路由**:React Router 6.x
- **请求库**:Axios 1.x
- **构建工具**:Vite 5.x

### 后端(对接的 API)
- RESTful API
- 基础 URL:https://api.cityledion.com/v1
- 认证方式:Bearer Token (JWT)

### 开发工具
- 包管理器:pnpm
- 代码规范:ESLint + Prettier
- Git 工作流:Git Flow

4.4.3 项目结构

帮助 Claude Code 快速定位文件。

markdown
## 项目结构

src/ ├── api/ # API 接口定义 │ ├── products.ts # 商品相关接口 │ ├── orders.ts # 订单相关接口 │ └── users.ts # 用户相关接口 ├── components/ # 公共组件 │ ├── Layout/ # 布局组件 │ ├── Table/ # 通用表格组件 │ └── Form/ # 通用表单组件 ├── pages/ # 页面组件 │ ├── products/ # 商品管理页面 │ ├── orders/ # 订单管理页面 │ └── users/ # 用户管理页面 ├── hooks/ # 自定义 Hooks ├── stores/ # Zustand 状态管理 ├── types/ # TypeScript 类型定义 ├── utils/ # 工具函数 └── styles/ # 全局样式

4.4.4 常用命令

列出开发中常用的命令。

markdown
## 常用命令

```bash
# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建生产版本
pnpm build

# 运行测试
pnpm test

# 运行 lint 检查
pnpm lint

# 修复 lint 问题
pnpm lint:fix

# 生成 API 类型定义
pnpm generate:types

:::tip 为什么列出常用命令?
当你让 Claude Code "帮我运行测试"时,它就知道应该使用 `pnpm test` 而不是 `npm test` 或 `yarn test`。这避免了很多不必要的错误。
:::

### 4.4.5 编码规范

描述团队的编码习惯和规范。

```markdown
## 编码规范

### 命名规范
- 组件文件名:PascalCase(如 `UserProfile.tsx`)
- 工具函数文件名:camelCase(如 `formatDate.ts`)
- 常量:UPPER_SNAKE_CASE(如 `MAX_PAGE_SIZE`)
- CSS 类名:kebab-case(如 `user-profile`)

### 组件规范
- 使用函数组件 + Hooks,不使用 class 组件
- Props 类型使用 interface 定义,命名为 `XxxProps`
- 组件文件结构:类型定义 → 组件本体 → 导出

### 代码风格
- 缩进:2 个空格
- 引号:单引号
- 分号:必须加
- 最大行宽:100 字符

### Git 提交规范
- feat: 新功能
- fix: Bug 修复
- docs: 文档更新
- style: 代码格式调整
- refactor: 重构
- test: 测试相关
- chore: 构建/工具相关

示例:`feat: 添加商品批量导入功能`

4.4.6 特殊注意事项

列出一些需要特别注意的地方。

markdown
## 注意事项

### 不要修改的文件
- `src/config/constants.ts` - 包含环境配置,由 CI/CD 管理
- `public/` 目录下的文件 - 静态资源由设计团队管理

### API 相关
- 所有 API 请求需要通过 `src/api/request.ts` 中的封装函数
- 不要直接使用 axios,使用封装好的 request 实例
- API 返回格式统一为 `{ code: number, data: T, message: string }`

### 权限相关
- 页面级权限通过路由配置控制
- 按钮级权限使用 `usePermission` Hook
- 新增页面时需要在 `src/config/permissions.ts` 中注册权限码

### 已知问题
- 商品列表在数据量超过 10000 时性能下降,正在优化中
- 导出 Excel 功能在 Safari 浏览器下有兼容问题

4.5 完整 CLAUDE.md 示例

下面是一个完整的项目级 CLAUDE.md 示例,你可以作为模板参考:

markdown
# City Legion Admin - 城市军团电商后台

## 项目概述
这是城市军团的电商后台管理系统,供内部运营和客服团队使用。
主要功能包括商品管理、订单处理、用户管理和营销活动管理。

## 技术栈
- React 18 + TypeScript 5 + Vite 5
- UI 库:Ant Design 5
- 状态管理:Zustand
- 请求:Axios(通过 src/api/request.ts 封装)
- 包管理器:pnpm

## 常用命令
- `pnpm dev` - 启动开发服务器
- `pnpm build` - 构建生产版本
- `pnpm test` - 运行测试
- `pnpm lint` - 代码检查

## 项目结构
- `src/api/` - API 接口定义
- `src/components/` - 公共组件
- `src/pages/` - 页面(按业务模块分目录)
- `src/hooks/` - 自定义 Hooks
- `src/stores/` - 状态管理
- `src/types/` - 类型定义
- `src/utils/` - 工具函数

## 编码规范
- 组件使用函数式 + Hooks
- 文件命名:组件 PascalCase,工具函数 camelCase
- 2 空格缩进,单引号,必须分号
- Git 提交:feat/fix/docs/refactor 前缀

## 注意事项
- API 请求必须通过 src/api/request.ts 封装
- 新页面需要在 permissions.ts 注册权限码
- 不要直接修改 src/config/constants.ts

CLAUDE.md 内容建议

  • 简洁为主:CLAUDE.md 的内容会占用 context window 空间,所以不要写得太长
  • 关键信息优先:把最重要的信息放在前面
  • 保持更新:项目演进时及时更新 CLAUDE.md
  • 不要放敏感信息:不要在 CLAUDE.md 中写密码、API Key 等敏感信息

4.6 用户级 CLAUDE.md 示例

下面是一个用户级 CLAUDE.md 的示例(放在 ~/.claude/CLAUDE.md):

markdown
# 个人偏好设置

## 语言和交流
- 使用中文回复和注释
- 技术术语保留英文原文
- 解释代码时请用通俗易懂的语言

## 工作习惯
- 修改文件之前先告诉我你打算做什么修改
- 完成后给出修改摘要
- 如果任务比较复杂,先给出实施方案让我确认

## 代码偏好
- 缩进使用 2 空格
- 优先使用 TypeScript
- 优先使用函数式编程风格
- 变量命名使用 camelCase

4.7 目录级 CLAUDE.md 示例

以下是一个放在 src/components/ 目录下的 CLAUDE.md 示例:

markdown
# Components 目录规范

## 文件组织
每个组件一个目录,目录结构:

ComponentName/ ├── index.tsx # 组件主文件 ├── ComponentName.tsx # 组件实现 ├── types.ts # 类型定义 ├── styles.module.css # 样式(如需要) └── tests/ # 测试文件 └── ComponentName.test.tsx


## 组件编写规范
- 所有组件使用函数式组件
- Props 类型定义在 types.ts 中
- 从 index.tsx 统一导出
- 复杂组件需要编写测试

## 公共组件列表
- `Button` - 按钮组件(封装了权限控制)
- `Table` - 表格组件(封装了分页和排序)
- `Form` - 表单组件(封装了校验逻辑)
- `Modal` - 弹窗组件(统一了样式)

4.8 CLAUDE.md 的加载机制

理解 CLAUDE.md 的加载机制,能帮你更好地组织内容。

加载顺序

当你在项目目录中启动 Claude Code 时,它会按以下顺序加载 CLAUDE.md:

1. 首先加载:~/.claude/CLAUDE.md(用户级)
2. 然后加载:项目根目录/CLAUDE.md(项目级)
3. 最后加载:当前工作目录及祖先目录中的 CLAUDE.md(目录级)

所有层级的内容会被合并到 Claude Code 的上下文中。

自动发现

Claude Code 会自动发现以下位置的 CLAUDE.md 文件:

文件位置发现方式说明
~/.claude/CLAUDE.md总是加载用户级,全局生效
项目根目录/CLAUDE.md启动时自动加载项目级
项目根目录/.claude/CLAUDE.md启动时自动加载项目级(.claude 目录内)
项目根目录/CLAUDE.local.md启动时自动加载项目级个人指令(gitignore)
子目录/CLAUDE.md访问该目录时加载目录级,按需加载
.claude/rules/*.md按 globs 条件加载模块化规则

关于 .claude/ 目录

~/.claude/ 是 Claude Code 的用户配置目录,除了 CLAUDE.md,它还可能包含其他配置文件(如认证信息、历史记录等)。

~/.claude/
├── CLAUDE.md          # 用户级记忆文件
├── credentials.json   # 认证信息(自动管理)
├── settings.json      # 用户设置
└── history/           # 对话历史

4.9 CLAUDE.md 的进阶用法

为不同任务类型设置指引

你可以在 CLAUDE.md 中为不同类型的任务设置具体的操作指引:

markdown
## 任务指引

### 添加新页面时
1. 在 src/pages/ 下创建新目录
2. 创建 index.tsx 作为页面入口
3. 在 src/router/config.ts 中添加路由
4. 在 src/config/permissions.ts 中注册权限
5. 在 src/config/menu.ts 中添加菜单项

### 添加新 API 接口时
1. 在 src/api/ 对应的模块文件中定义接口
2. 在 src/types/api/ 中定义请求和响应类型
3. 使用 request 封装函数
4. 编写接口测试

### 修复 Bug 时
1. 先阅读相关代码理解上下文
2. 编写一个能复现 bug 的测试用例
3. 修复 bug
4. 确保测试通过
5. 检查是否有类似的问题需要一并修复

提供代码模板

你可以在 CLAUDE.md 中提供代码模板,这样 Claude Code 生成代码时会遵循统一的风格:

markdown
## 代码模板

### React 组件模板
新建组件时请遵循以下模板:

interface XxxProps {
  // props 定义
}

const Xxx: React.FC<XxxProps> = ({ ...props }) => {
  // hooks

  // handlers

  // render
  return (
    <div>
      {/* content */}
    </div>
  );
};

export default Xxx;

### API 接口模板

import { request } from './request';
import type { XxxRequest, XxxResponse } from '@/types/api';

export const fetchXxx = (params: XxxRequest) => {
  return request.get<XxxResponse>('/api/xxx', { params });
};

标记不应修改的内容

有些文件或代码区域不应该被 Claude Code 修改,你可以在 CLAUDE.md 中明确标注:

markdown
## 禁止修改的区域

### 文件级
- `src/config/env.ts` - 环境配置,由 DevOps 团队管理
- `src/generated/` - 自动生成的代码,不要手动修改
- `.github/workflows/` - CI/CD 配置,修改需要通知 DevOps

### 代码级
- `src/utils/crypto.ts` 中的加密算法 - 已通过安全审计,不要修改
- `src/api/request.ts` 中的拦截器逻辑 - 涉及全局错误处理

4.10 模块化规则:.claude/rules/ 系统

除了 CLAUDE.md 文件,Claude Code 还支持 .claude/rules/ 目录,用于存放模块化的规则文件。每个规则是一个独立的 .md 文件,可以根据文件路径模式条件激活。

基本结构

your-project/
├── .claude/
│   └── rules/
│       ├── general.md          <-- 通用规则,始终生效
│       ├── frontend.md         <-- 前端规则
│       ├── testing.md          <-- 测试规则
│       └── api-design.md       <-- API 设计规则
└── ...

条件激活

规则文件支持通过 YAML frontmatter 中的 globs 字段来指定激活条件。只有当 Claude Code 操作的文件匹配对应的 glob 模式时,该规则才会被加载:

markdown
---
globs: "src/components/**/*.tsx"
---

# 组件开发规则

- 所有组件使用函数式组件 + Hooks
- Props 类型必须使用 interface 定义
- 组件文件必须包含导出的 default export
markdown
---
globs: "**/*.test.ts"
---

# 测试规则

- 每个测试文件必须包含 describe 块
- 使用 AAA 模式(Arrange-Act-Assert)
- Mock 外部依赖,不要 mock 被测模块

没有 globs 字段的规则文件会始终生效,类似于 CLAUDE.md 中的全局指令。

与 CLAUDE.md 的区别

特性CLAUDE.md.claude/rules/*.md
适合内容项目整体信息、通用规范特定场景的详细规则
激活方式始终加载可按文件模式条件激活
组织方式单文件多文件,按主题拆分
典型用途技术栈、命令、概述编码规范、模块规则

何时使用 rules

当你的 CLAUDE.md 变得过长,或者不同模块有不同的规范时,可以将规则拆分到 .claude/rules/ 目录中。这样既保持了 CLAUDE.md 的简洁,又能提供细粒度的上下文。

4.11 CLAUDE.md 中的文件导入

CLAUDE.md 文件支持使用 @path/to/file.md 语法导入其他 Markdown 文件的内容。这让你可以将常用的指令集中管理,并在多个 CLAUDE.md 文件中复用。

基本语法

在 CLAUDE.md 中,使用 @ 前缀引用其他文件:

markdown
# 项目配置

## 项目概述
这是我们的电商后台管理系统。

## 编码规范
@docs/coding-standards.md

## API 规范
@docs/api-guidelines.md

Claude Code 会在加载 CLAUDE.md 时自动将 @ 引用的文件内容内联展开。路径相对于当前 CLAUDE.md 文件所在目录。

使用场景

  • 团队共享规范:将团队编码规范放在单独的文件中,多个项目的 CLAUDE.md 可以引用同一份规范
  • 模块化管理:将不同类型的指令拆分到独立文件中,保持 CLAUDE.md 主文件简洁
  • 复用规则:在项目级和目录级 CLAUDE.md 中引用相同的规则文件

4.12 CLAUDE.md 维护建议

何时更新 CLAUDE.md

触发事件需要更新的内容
引入新的技术/库技术栈部分
修改目录结构项目结构部分
团队规范变更编码规范部分
新增常用命令常用命令部分
发现 Claude Code 反复犯的错误注意事项部分

维护原则

  1. 保持简洁:CLAUDE.md 的内容会消耗 context window,不要写得太长
  2. 只写关键信息:Claude Code 能自己发现的信息不需要写(比如"这是一个 React 项目",它看 package.json 就知道了)
  3. 写 Claude Code 不容易推断的信息:团队约定、业务逻辑、特殊规范
  4. 定期清理:删除过时的信息
  5. 团队共享:项目级 CLAUDE.md 应该提交到 Git 仓库,让团队所有人共享

理想的 CLAUDE.md 长度

  • 用户级:20-50 行
  • 项目级:50-150 行
  • 目录级:10-30 行

如果你的 CLAUDE.md 超过了 200 行,考虑精简一下。记住,这个文件是给 AI 看的"备忘录",不是给人看的"文档"。

4.13 本章小结

要点内容
作用让 Claude Code "记住" 项目上下文,避免重复交代
三个层级用户级(全局) > 项目级(单项目) > 目录级(子目录)
项目级位置CLAUDE.md.claude/CLAUDE.md
个人指令CLAUDE.local.md(gitignore,个人使用)
模块化规则.claude/rules/*.md(支持 globs 条件激活)
文件导入@path/to/file.md 语法导入其他 Markdown
创建方式/init 自动生成,或手动创建
核心内容项目概述、技术栈、常用命令、编码规范、注意事项
维护原则简洁、关键、及时更新
练习任务
  1. 在你的练习项目中运行 /init,查看自动生成的 CLAUDE.md
  2. 根据本章学到的最佳实践,优化生成的 CLAUDE.md
  3. 创建一个用户级的 ~/.claude/CLAUDE.md,写入你的个人偏好
  4. 在项目的某个子目录下创建一个目录级的 CLAUDE.md
  5. 重启 Claude Code,验证 CLAUDE.md 是否被正确加载(可以问 Claude Code "你知道这个项目使用什么技术栈吗?")

下一章:Plan Mode 规划模式 ->