Claude Code CLAUDE.md记忆文件指南

2026-05-25 13:33

📄 Claude Code 记忆文件指南

什么是记忆文件？

每次用AI编程助手都要重复解释项目配置？记忆文件就是解决方案——一个让AI自动记住你项目规则的文本文件。

三种记忆文件

Claude Code 提供了3层记忆，按优先级从高到低：

文件	位置	用途	提交Git？
本地覆盖	`./CLAUDE.local.md`	你个人的临时偏好	否
项目记忆	`./CLAUDE.md`	团队共享的项目规则	是
全局记忆	`~/.claude/CLAUDE.md`	你所有项目的通用习惯	否

📌 优先级规则本地 > 项目 > 全局

最常用的两个

① CLAUDE.md（项目记忆）

放项目根目录，提交到Git，团队共用：

# 技术栈：Next.js + TypeScript
# 启动命令：npm run dev
# 组件文件名用大写开头

② CLAUDE.local.md（个人覆盖）

放项目根目录，不提交Git，只属于你：

# 回复用中文
# 代码注释写详细点

完整示例：Java SpringBoot 项目

这是一个真实项目的 CLAUDE.md 文件：

# CLAUDE.md — Java SpringBoot 项目规范

## 技术栈

- Java: 1.7（LTS 版本，强制）
- Spring Boot: 3.2.x
- 数据库: MySQL 5.7 或 PostgreSQL 15
- 构建工具: Maven（使用 ./mvnw，不要直接用 mvn）
- 测试框架: JUnit 5 + Testcontainers（集成测试禁止使用 H2）

## 架构规范

### 分层结构

src/main/java/com.company.project/
├── controller/     # REST 端点，只做参数校验和调用 service
├── service/        # 业务逻辑，接口以 I 前缀命名
├── repository/     # 数据访问，继承 JpaRepository
├── model/          # JPA 实体类
├── dto/            # 请求/响应 DTO，不要把 Entity 直接暴露给 API
├── config/         # Spring 配置类
└── exception/      # 自定义异常 + 全局异常处理

### 命名规范

- 包命名：com.company.模块名.层级
- 类命名：大驼峰，Service 接口加 I 前缀（如 IUserService）
- 方法命名：小驼峰，动词开头（如 getUserById、createOrder）
- 常量命名：全大写下划线分隔（如 MAX_RETRY_COUNT）

## 代码规范

### Controller 层

- 使用 @RestController + @RequestMapping
- 统一返回 ResponseEntity<ResponseDTO<T>>
- 参数校验使用 @Valid，不要在 controller 里写 if 判断
- 错误响应使用 ProblemDetail（Spring Boot 3.x 内置，RFC 7807 标准）
- URL 路径使用名词复数：/users 而不是 /getUsers

正确写法：
@PostMapping("/users")
public ResponseEntity<ResponseDTO<UserDTO>> createUser(
    @Valid @RequestBody CreateUserRequest request) {
    return ResponseEntity.ok(ResponseDTO.success(userService.createUser(request)));
}

禁止写法：
@PostMapping("/users")
public UserDTO createUser(@RequestBody CreateUserRequest request) {
    if (request.getName() == null) {
        throw new RuntimeException("name is null");
    }
    return userService.createUser(request);
}

### Service 层

- 使用构造器注入，不要用 @Autowired 字段注入
- 事务注解 @Transactional 只加在 Service 实现类上，不要加在接口上
- 跨服务调用不要嵌套 @Transactional，容易出事务穿透问题

正确写法：
@Service
@RequiredArgsConstructor
public class UserServiceImpl implements IUserService {
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
}

禁止写法：
@Service
public class UserServiceImpl implements IUserService {
    @Autowired
    private UserRepository userRepository;
}

### Repository 层（JPA 规范）

- 使用 DTO Projection 替代直接返回 Entity
- 关联查询优先使用 @EntityGraph 或 JPQL JOIN FETCH
- 禁止在循环里调用 repository 方法（N+1 问题）
- 分页查询必须使用 Pageable 参数
- 禁止在 @OneToMany 上使用 FetchType.EAGER

正确写法：
@Query("SELECT new com.company.dto.UserDTO(u.id, u.name, u.email) " +
       "FROM User u WHERE u.id = :id")
Optional<UserDTO> findUserDTOById(@Param("id") Long id);

禁止写法：
Optional<User> findById(Long id); // 然后直接 return 给 API

### 异常处理

- 业务异常继承 BusinessException，包含错误码和错误信息
- 全局异常处理使用 @RestControllerAdvice
- 不允许直接 throw new RuntimeException("xxx")，必须使用自定义异常
- 日志记录使用 SLF4J，不允许使用 System.out.println

正确写法：
throw new BusinessException(ErrorCode.USER_NOT_FOUND, "用户不存在: " + userId);

禁止写法：
throw new RuntimeException("用户不存在");

## 工作流规范

### Plan Mode（重要）

任何非简单任务都必须先进入 Plan Mode，写详细方案后再执行。

触发条件：
- 超过 3 个步骤的任务 → Plan Mode
- 涉及架构决策 → Plan Mode
- 修改核心业务逻辑 → Plan Mode
- 数据库 Schema 变更 → Plan Mode

工作流四阶段：探索（理解需求）→ 计划（写方案）→ 实施（写代码）→ 提交（验证）

### 每次修改后必须执行

./mvnw test
./mvnw checkstyle:check

测试通过才能提交，不允许跳过。

## 明确禁止的模式

- 禁止直接将 Entity 暴露在 API 响应里
- 禁止在 @OneToMany 上使用 FetchType.EAGER
- 禁止在循环里调用数据库方法
- 禁止使用 System.out.println 输出日志
- 禁止 catch 所有异常后 log.error("失败") 就完事，必须区分异常类型
- 禁止直接在 Controller 里写业务逻辑
- 禁止跳过测试提交代码
- 禁止修改已有的数据库迁移文件，只能新增

## API 设计规范

- URL 路径使用名词复数：/users 而不是 /getUsers
- HTTP 方法语义正确：GET 查询，POST 创建，PUT 全量更新，PATCH 部分更新，DELETE 删除
- 版本管理：URL 路径前缀 /api/v1/
- 分页接口返回 Page 对象，包含 totalElements 和 totalPages
- 所有时间字段使用 ISO 8601 格式（LocalDateTime + @JsonFormat）

## Git 提交规范

格式：类型(范围): 描述

类型：
- feat: 新功能
- fix: Bug 修复
- refactor: 重构（不涉及功能变化）
- test: 测试相关
- docs: 文档修改
- chore: 构建/配置相关

示例：feat(user): 添加用户手机号绑定功能

快速上手

✅ 1. 在项目根目录新建 CLAUDE.md
✅ 2. 按上面的示例写上你的技术栈和代码规范
✅ 3. 可选：新建 CLAUDE.local.md 写个人偏好