首页 > 专题 > AI编程 > 文章详情
返回 AI编程

CLAUDE.md 项目记忆文件详解

2026年03月11日 5 阅读 AI编程

CLAUDE.md 项目记忆文件详解

CLAUDE.md 是 Claude Code 的"项目记忆文件"，记录项目结构、构建命令、代码规范、架构决策等信息，让 Claude Code 快速理解项目上下文。

一、什么是 CLAUDE.md？

核心概念

CLAUDE.md 是 Claude Code 的项目知识库文件，具有以下特点：

  • 持久化存储：记录项目相关信息，长期有效
  • 自动读取：Claude Code 自动加载，无需重复解释
  • 团队共享：整个团队可以共享同一份配置
  • 持续演进：随项目发展不断更新

核心价值

| 功能 | 说明 |
|------|------|
| 项目知识库 | 记录项目架构、技术栈、依赖关系 |
| 快速启动 | 自动读取，无需重复解释项目背景 |
| 团队协作 | 共享项目规范，确保团队理解一致 |
| 持续迭代 | 随项目演进自动更新 |

二、CLAUDE.md 最佳位置

文件位置优先级

┌─────────────────────────────────────────────────────────────────┐
│                       文件位置层级                               │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │ 最高优先级: 特定规则                                       │ │
│  │ 位置: .claude/rules/*.md                                  │ │
│  │ 说明: 针对特定模块或功能的详细规则                         │ │
│  └───────────────────────────────────────────────────────────┘ │
│                              ↓                                  │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │ 第二优先级: 模块级配置                                     │ │
│  │ 位置: src/.claude/CLAUDE.md                               │ │
│  │ 说明: 针对特定模块的配置                                   │ │
│  └───────────────────────────────────────────────────────────┘ │
│                              ↓                                  │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │ 第三优先级: 项目配置                                       │ │
│  │ 位置: CLAUDE.md (项目根目录)                              │ │
│  │ 说明: 全局项目配置                                         │ │
│  └───────────────────────────────────────────────────────────┘ │
│                              ↓                                  │
│  ┌───────────────────────────────────────────────────────────┐ │
│  │ 最低优先级: 用户级配置                                     │ │
│  │ 位置: ~/.claude/CLAUDE.md                                 │ │
│  │ 说明: 用户个人偏好设置                                     │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

目录结构示例

project/
├── CLAUDE.md                          # 项目根目录配置
├── src/
│   ├── .claude/
│   │   └── CLAUDE.md                  # 模块级配置
│   └── components/
├── .claude/
│   └── rules/
│       ├── auth.md                     # 认证相关规则
│       ├── database.md                 # 数据库相关规则
│       └── api.md                      # API 设计规范
└── docs/
    └── CLAUDE.md                       # 文档模块配置

三、CLAUDE.md 完整示例

# 项目名称: E-Commerce Platform

## 项目概述
这是一个基于 Node.js + React 的电商平台，支持商品管理、订单处理、支付集成等功能。

## 技术栈
- **前端:** React 18, TypeScript, Tailwind CSS, Redux Toolkit
- **后端:** Node.js 20, Express, TypeScript
- **数据库:** PostgreSQL 15, Redis 7
- **认证:** JWT, OAuth 2.0
- **测试:** Jest, Playwright
- **部署:** Docker, Kubernetes

## 项目结构

src/
├── frontend/ # React 前端
│ ├── components/ # 可复用组件
│ ├── pages/ # 页面组件
│ ├── store/ # Redux store
│ └── utils/ # 工具函数
├── backend/ # Node.js 后端
│ ├── controllers/ # 控制器
│ ├── services/ # 业务逻辑
│ ├── models/ # 数据模型
│ └── routes/ # API 路由
└── shared/ # 共享代码
└── types/ # TypeScript 类型定义


## 常用命令

### 开发环境
```bash
# 安装依赖
npm install

# 启动前端开发服务器
npm run dev:frontend

# 启动后端开发服务器
npm run dev:backend

# 同时启动前后端
npm run dev

构建与部署

# 构建前端
npm run build:frontend

# 构建后端
npm run build:backend

# 构建所有
npm run build

# Docker 构建
docker-compose build
docker-compose up

测试

# 运行所有测试
npm test

# 前端单元测试
npm run test:frontend

# 后端单元测试
npm run test:backend

# E2E 测试
npm run test:e2e

# 测试覆盖率
npm run test:coverage

代码质量

# 代码格式化
npm run format

# 代码检查
npm run lint

# 类型检查
npm run type-check

代码规范

命名规范

  • 文件名: kebab-case (user-profile.ts)
  • 组件名: PascalCase (UserProfile)
  • 函数/变量: camelCase (getUserProfile)
  • 常量: UPPER_SNAKE_CASE (API_BASE_URL)
  • 类型/接口: PascalCase (UserProfile)

Git 提交规范

遵循 Conventional Commits:

  • feat: 新功能
  • fix: 修复 bug
  • docs: 文档更新
  • style: 代码格式调整
  • refactor: 代码重构
  • test: 测试相关
  • chore: 构建/工具链更新

代码审查清单

  • [ ] 代码符合项目命名规范
  • [ ] 添加了必要的注释
  • [ ] 更新了相关文档
  • [ ] 编写了/更新了测试
  • [ ] 通过了所有测试
  • [ ] 通过了 lint 检查
  • [ ] 没有引入安全漏洞

架构决策

ADR-001: 选择 TypeScript 而非 JavaScript

日期: 2024-01-15
状态: 已接受
理由:

  • 类型安全减少运行时错误
  • 更好的 IDE 支持
  • 代码可维护性更高

ADR-002: 采用微服务架构

日期: 2024-02-20
状态: 已接受
理由:

  • 便于团队并行开发
  • 独立部署和扩展
  • 技术栈灵活性

环境变量

必需变量

DATABASE_URL=postgresql://...
REDIS_URL=redis://...
JWT_SECRET=your-secret-key
API_BASE_URL=https://api.example.com

可选变量

LOG_LEVEL=info
NODE_ENV=development
PORT=3000

常见问题

Q: 如何添加新的 API 端点?

A:

  1. 在 backend/routes/ 创建路由文件
  2. 在 backend/controllers/ 创建控制器
  3. 在 backend/services/ 实现业务逻辑
  4. 添加测试用例
  5. 更新 API 文档

Q: 如何调试前端状态管理问题?

A:

  1. 使用 Redux DevTools 浏览器扩展
  2. 在 src/frontend/store/ 添加日志
  3. 检查 action 和 reducer 逻辑

重要注意事项

  1. 安全: 永远不要在代码中硬编码密钥或敏感信息
  2. 性能: 大数据查询必须使用分页
  3. 测试: 所有新功能必须包含测试
  4. 文档: API 变更必须更新文档
  5. 兼容性: 确保向后兼容，使用版本控制

相关资源


## 四、生成 CLAUDE.md

### 方式一：使用 /init 命令

```bash
# 在项目根目录
claude /init

Claude Code 会自动扫描项目并生成初始 CLAUDE.md，包含：

  • 构建和测试命令
  • 目录结构说明
  • 代码规范和架构决策
  • 技术栈信息

方式二：手动创建

# 创建基础文件
touch CLAUDE.md

# 让 Claude Code 帮助生成
claude "请根据当前项目结构生成 CLAUDE.md 文件"

方式三：模块化规则

# 在 .claude/rules/ 目录创建多个规则文件
.claude/rules/
├── auth.md          # 认证相关规则
├── database.md      # 数据库相关规则
├── api.md           # API 设计规范
└── testing.md       # 测试规范

方式四：Memory Updates 动态更新

# 直接告诉 Claude 更新知识
Update CLAUDE.md: always use bun instead of npm
Update CLAUDE.md: 不要使用 enum,改用 string union

# Claude 会自动把新知识写入记忆文件，无需手动编辑

五、CLAUDE.md 的 AI 进化机制

核心理念

让 Claude 在 Code Review 中自我迭代，越用越聪明。

实战流程

  1. 在 PR 中发现问题
# 在 GitHub PR 评论中
@claude 这里的代码使用了 enum，但我们项目规范要求使用 string union，请修复
  1. 让 Claude 记住教训
# 在 PR 中直接告诉 Claude
@claude 请把这次的教训写入 CLAUDE.md:不要使用 enum,改用 string union
  1. Claude 自动更新
# Claude 会在 CLAUDE.md 中添加
## 代码规范更新 (2026-01-03)

### Enum vs String Union
- ❌ 不要使用 enum
- ✅ 改用 string union
- 理由:更好的类型推断和 Tree-shaking
  1. 团队共同维护
# 将 CLAUDE.md 签入 Git
git add CLAUDE.md
git commit -m "docs: 更新 CLAUDE.md 规范"

# 整个团队共享这份"行为准则"

实际演进示例

# CLAUDE.md - 实际演进示例

## 初始版本 (第1周)
- 使用 TypeScript
- 测试覆盖率 > 80%

## 第1次更新 (第2周 - PR反馈)
+ 永远使用 bun 而不是 npm
+ 理由:启动速度快 10 倍

## 第2次更新 (第3周 - PR反馈)
+ 不要使用 enum,改用 string union
+ 理由:更好的类型推断

## 第3次更新 (第4周 - PR反馈)
+ 所有 API 必须添加错误处理
+ 使用 try-catch 包装所有 async 函数

六、CLAUDE.md 最佳实践

1. 保持简洁

# GOOD
## 测试命令
npm test

# BAD
## 测试命令
为了确保代码质量，我们需要运行测试。
首先安装依赖，然后运行测试...

2. 结构清晰

# 推荐结构
# 项目名称

## 概述
[1-2行描述]

## 技术栈
- 列表

## 项目结构

目录结构


## 常用命令

命令


## 代码规范
[要点]

3. 持续维护

# 定期更新
- 新功能添加后更新
- 架构变更时更新
- 团队反馈后更新

# 签入版本控制
git add CLAUDE.md
git commit -m "docs: 更新项目规范"

4. 团队协作

# 团队维护规则
## 贡献指南
- 发现问题请更新 CLAUDE.md
- 更新后通知团队成员
- 定期审查 CLAUDE.md 内容

七、常见问题

问题 1：CLAUDE.md 不生效

可能原因：

  1. 文件位置不正确
  2. 格式错误
  3. 编码问题

解决方案：

# 检查文件位置
ls -la CLAUDE.md

# 验证格式
cat CLAUDE.md | head -20

# 确保是 UTF-8 编码
file CLAUDE.md

问题 2：内容太多

解决方案：

# 拆分成多个文件
.claude/rules/
├── auth.md
├── database.md
└── api.md

# 在 CLAUDE.md 中引用
See [.claude/rules/](.claude/rules/) for detailed guidelines.

问题 3：与团队成员冲突

解决方案：

# 统一 CLAUDE.md
- 定期同步
- 建立维护流程
- 签入版本控制

# 冲突解决
git merge CLAUDE.md

八、进阶技巧

1. 条件加载

# 在特定条件下生效
# Condition: TypeScript project

# 当检测到 TypeScript 时自动加载

2. 变量引用

# 使用变量
{{PROJECT_NAME}}
{{NODE_VERSION}}
{{TEST_COMMAND}}

3. 模板系统

# 组件模板
{{COMPONENT_TEMPLATE}}

# API 模板
{{API_TEMPLATE}}

九、总结

通过本指南，你已经了解了：

  1. ✅ CLAUDE.md 的核心概念和作用
  2. ✅ 文件位置和优先级
  3. ✅ 完整的 CLAUDE.md 模板
  4. ✅ 生成和更新方式
  5. ✅ AI 进化机制
  6. ✅ 最佳实践

CLAUDE.md 是 Claude Code 强大的项目知识管理机制，通过合理配置 CLAUDE.md，可以大大提升 Claude Code 对项目的理解能力和开发效率。

参考资源

Claude教程