Appearance
第四章: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 Flow4.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.tsCLAUDE.md 内容建议
- 简洁为主:CLAUDE.md 的内容会占用 context window 空间,所以不要写得太长
- 关键信息优先:把最重要的信息放在前面
- 保持更新:项目演进时及时更新 CLAUDE.md
- 不要放敏感信息:不要在 CLAUDE.md 中写密码、API Key 等敏感信息
4.6 用户级 CLAUDE.md 示例
下面是一个用户级 CLAUDE.md 的示例(放在 ~/.claude/CLAUDE.md):
markdown
# 个人偏好设置
## 语言和交流
- 使用中文回复和注释
- 技术术语保留英文原文
- 解释代码时请用通俗易懂的语言
## 工作习惯
- 修改文件之前先告诉我你打算做什么修改
- 完成后给出修改摘要
- 如果任务比较复杂,先给出实施方案让我确认
## 代码偏好
- 缩进使用 2 空格
- 优先使用 TypeScript
- 优先使用函数式编程风格
- 变量命名使用 camelCase4.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 exportmarkdown
---
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.mdClaude Code 会在加载 CLAUDE.md 时自动将 @ 引用的文件内容内联展开。路径相对于当前 CLAUDE.md 文件所在目录。
使用场景
- 团队共享规范:将团队编码规范放在单独的文件中,多个项目的 CLAUDE.md 可以引用同一份规范
- 模块化管理:将不同类型的指令拆分到独立文件中,保持 CLAUDE.md 主文件简洁
- 复用规则:在项目级和目录级 CLAUDE.md 中引用相同的规则文件
4.12 CLAUDE.md 维护建议
何时更新 CLAUDE.md
| 触发事件 | 需要更新的内容 |
|---|---|
| 引入新的技术/库 | 技术栈部分 |
| 修改目录结构 | 项目结构部分 |
| 团队规范变更 | 编码规范部分 |
| 新增常用命令 | 常用命令部分 |
| 发现 Claude Code 反复犯的错误 | 注意事项部分 |
维护原则
- 保持简洁:CLAUDE.md 的内容会消耗 context window,不要写得太长
- 只写关键信息:Claude Code 能自己发现的信息不需要写(比如"这是一个 React 项目",它看 package.json 就知道了)
- 写 Claude Code 不容易推断的信息:团队约定、业务逻辑、特殊规范
- 定期清理:删除过时的信息
- 团队共享:项目级 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 自动生成,或手动创建 |
| 核心内容 | 项目概述、技术栈、常用命令、编码规范、注意事项 |
| 维护原则 | 简洁、关键、及时更新 |
练习任务
- 在你的练习项目中运行
/init,查看自动生成的 CLAUDE.md - 根据本章学到的最佳实践,优化生成的 CLAUDE.md
- 创建一个用户级的
~/.claude/CLAUDE.md,写入你的个人偏好 - 在项目的某个子目录下创建一个目录级的 CLAUDE.md
- 重启 Claude Code,验证 CLAUDE.md 是否被正确加载(可以问 Claude Code "你知道这个项目使用什么技术栈吗?")