Claude Code 核心记忆文件 CLAUDE.md 实战操作详解

三、CLAUDE.md 项目记忆文件介绍

3.1 CLAUDE.md 文件概述

3.1.1 CLAUDE.md 是什么？

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

简单来说，CLAUDE.md 是 Claude Code 的持久化记忆配置文件，本质是一个普通的 Markdown 文件，却能在每次启动 Claude Code 会话时，自动被加载到 AI 的上下文里，相当于给 AI 提前'灌输'项目信息和规则。

3.1.2 CLAUDE.md 核心特点

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

3.1.3 CLAUDE.md 核心价值

1. 提供项目上下文：快速告知 AI 项目的技术栈、项目结构和模块组织方式。
2. 规范 AI 行为：定义代码风格和命名约定，指定测试命令、构建流程。
3. 提高协作效率：减少重复性的背景说明，避免 AI 产生不符合项目规范的代码。
4. 知识沉淀：记录项目的特殊约定或架构决策，传递团队的最佳实践。
5. 节省 Token 成本：避免每次对话都要重新说明项目背景。

3.2 CLAUDE.md 目录结构说明

Claude.md 放在不同位置，作用范围不同，冲突时也有明确的覆盖逻辑。

3.2.1 Claude.md 文件存放目录优先级

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

1）各优先级使用场景

• 企业级：仅企业账号可用，作用于企业内所有用户，用于统一企业级编码策略和安全规范。
• 项目级：放在项目根目录（路径：./CLAUDE.md），仅对当前项目生效，是最常用的位置。适合存放项目专属的技术栈、团队规范、项目架构等内容。
• 用户级：放在用户主目录（路径：~/.claude/CLAUDE.md），作用于个人所有项目，适合存放跨项目通用的个人偏好。

2）优先级规则 如果多个位置都存在 Claude.md 文件时，AI 会按「优先级从高到低」加载，冲突内容通常以高优先级为准。

优先级顺序：企业级 > 项目级 > 用户级

示例： 如果在用户级 claude.md 中配置了'代码使用单引号'，但当前项目的项目级 claude.md 中配置了'代码使用双引号'，那么在这个项目中，AI 会优先遵循'双引号'规则。

3、Claude.md 目录结构示例

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

3.3 Claude.md 文件创建

推荐实践方式是自动生成，人工再根据生成的文件，结合经验和项目实际情况进行微调优化。

3.3.1 Claude.md 文件创建的几种方式

• 自动生成：在项目根目录启动 Claude Code，输入「/init」命令，AI 会自动分析项目结构、依赖和关键文件，生成初始的 claude.md。
• 手动创建：进入对应目录，通过命令「touch CLAUDE.md」创建文件，再写入基础规则。
• 快速添加：在 Claude Code 对话中，输入以「#」开头的内容（比如「# 所有代码需遵循 PEP8 规范」），选择'存入 claude.md'。

3.4 Claude.md 文件项目操作实践

3.4.1 Claude.md 文件可以存放的内容

分为必须放的内容和推荐放的内容。

3.4.1.1 必须放的内容（核心价值）

1、技术栈声明

## Tech Stack
- Java 21 + Spring Boot 3.3.x
- Maven 3.9+ (use wrapper)
- PostgreSQL 16 + Redis 7
- Kafka 3.x for messaging
- Testcontainers + JUnit 5

2、项目结构

## Project Structure
- `src/main/java/com/example/domain/` - 核心业务逻辑
- `src/main/java/com/example/api/` - REST controllers
- `src/main/resources/db/migration/` - Flyway 脚本
- `src/test/java/` - 单元测试和集成测试

3、构建和运行命令

## Common Commands
- Build: `./mvnw clean package`
- Run: `./mvnw spring-boot:run -Dspring-boot.run.profiles=dev`
- Test: `./mvnw test`
- DB migration: `./mvnw flyway:migrate`

4、关键约定（禁止事项）

## CRITICAL RULES
- NEVER use `@Autowired` on fields - use constructor injection
- NEVER catch `Exception` without logging
- NEVER use `eager` fetching in JPA
- NEVER hardcode credentials

5、架构决策记录

## Architecture Decisions (ADRs)
- Outbox pattern for reliable event publishing
- CQRS for order querying (separate read/write models)
- Circuit breaker for all external HTTP calls

3.4.1.2 推荐放的内容（高价值）

1、常用模式和代码示例

## Code Patterns
### Repository Pattern
public interface OrderRepository extends JpaRepository<Order, Long> {
    Optional<Order> findByOrderNumber(String orderNumber);
}

2、DTO Mapping Use MapStruct: @Mapper(componentModel = "spring")

3、环境配置说明

## Environment Setup
- Dev: `application-dev.yml` (local Postgres, Redis)
- Staging: Kubernetes namespace `staging`
- Prod: Requires approval for deployment

4、测试策略

## Testing Guidelines
- Unit tests: Mock all dependencies
- Integration tests: Use `@Testcontainers` for real DB
- E2E tests: Run with `-Pe2e` profile
- Target coverage: 80% (use JaCoCo)

5、依赖和版本约束

## Version Constraints
- Spring Boot: 3.3.x ONLY (not 3.2.x or 3.4.x)
- Java: 21 LTS only
- Jackson: 2.17+ (for Java 21 records support)
- Avoid: Lombok, Apache Commons Lang 2.x

3.4.2 基于已有项目创建 CLAUDE.md

进入本地某个项目目录中，进入 Claude 交互式命令行窗口中，使用 /init 命令让 AI 生成一个初始化的 CLAUDE.md 文件。

然后，AI 会对当前的项目进行完整的拆解、分析。

生成完成后，在项目的根目录下，生成了左侧的 CLAUDE.md 文件，该文件中主要包含了下面的核心内容：

• 构建命令
• 项目的基础设施
• 核心业务微服务模块
• 服务之间通讯方式
• 项目规范
• 关键技术栈和技术选型

该文件属于项目根目录配置文件，属于全局配置文件，全局生效。

3.4.3 基于微服务项目级 CLAUDE.md 文件使用

更多情况下，在实际的开发实践中，不同的微服务项目都有属于项目级的规则，比如开发规范、构建标准、技术栈等，一个项目级的 CLAUDE.md 文件目录结构如下：

your-java-microservice/
├── CLAUDE.md                 # 主配置文件（80-150 行）
├── .claude/
│   ├── rules/                # 模块化规则
│   │   ├── testing.md        # 测试规范（条件加载）
│   │   ├── api-design.md     # API 设计规范
│   │   ├── database.md       # 数据库操作规范
│   │   └── security.md       # 安全规范
│   └── commands/             # 自定义命令
│       ├── test.md
│       └── build.md
└── agent_docs/               # 详细文档（可选）
    ├── architecture-guide.md
    └── deployment.md

仍然基于上述的项目，与 Claude Code 共创这几个文件，按照上面的目录结构，依次生成这些文件。

1）生成项目级的 CLAUDE.md 文件 输入下面的提示词。

有了这个文件后，不管是新进入团队的人，还是其他人想快速了解项目时，看这个文件就能了解。

如果初始化的 CLAUDE.md 文件中仍然有一些不尽人意，或者需要继续补充的地方，直接在对应的位置加进去即可。

2）生成项目级下面的其他规则文件 按照上述的项目级的目录结构，我们再依次生成其他的项目规则文件，参考下面的提示词：

在当前工程的 ./claude/rules 目录下，依次生成 api-design.md(API 接口设计规范),database.md（数据库操作规范）,testing.md(测试规范)，作为后续团队对该项目的开发规范，生成后，接下来我将与你持续共创并完善这些文件内容

最后，几个文件按照规范要求生成，并放在指定的目录下。

3.4.4 记忆加载过程

CLAUDE.md 文件生成后，不需要做任何'额外操作'来'激活'它 —— Claude Code 会自动读取并应用。

一、立即验证：确认配置生效 在开始使用前，先确认 CLAUDE.md 已被正确加载。启动 Claude Code 并检查状态：

# 在项目根目录启动 Claude Code
cd your-java-microservice
claude

基于上面已经生成了 CLAUDE.md 文件的情况下，先退出并重新开启会话，启动后，Claude 会自动读取 CLAUDE.md。可以通过以下命令验证：

> /status # 查看当前会话状态和配置
> /context # 查看上下文窗口占用，确认 CLAUDE.md 已加载

在项目的根目录下，下面的检查加载的是全局的那一个 CLAUDE.md 文件。

如果是项目级的话，还需进入到项目目录下，如下，进入到具体的项目目录下之后，再次查看：

• 通过输出的日志信息不难发现，进入到项目目录后，又把前文中项目下的几个 md 文件自动加载到上下文记忆中

3.4.5 基于规则文件开发接口

编写规则，完善规则，将规则加载到 claude 的记忆，这些可以理解为前置的步骤，或者准备，这些准备都是为接下来实际项目开发做参考使用的，即通过这些文件来规范 AI 编写代码应该遵守的边界。

下面提一个明确的需求，让 AI 为我们生成一个接口，最后检查 AI 生成的接口是否符合预期的要求，需求提示词如下：

参考 @doc\api-develop-standard.md 规范，在 TmsWaybillController 新增一个查询订单表的接口，支持多参数查询，比如订单号，创建时间，客户编号

明确要求 AI 编写接口的时候需要参考提前指定好的 API 编写规范文件，确保生成的接口与当前的接口规范是一致的。

接口效果如下，生成的代码基本是按照当前项目的规范，参考了上面创建的 CLAUDE.md 文件的同时，也遵循了引用的接口编写规范文件。

/**
 * 分页查询订单表
 */
@PostMapping("/order/list")
@Operation(summary = "分页查询订单列表", description = "支持按订单号、客户编号、创建时间范围查询")
public R<Pagination<TmsOrderVO>> orderList(@RequestBody TmsOrderPageRequest request) {
    return R.ok(tmsOrderService.listByPage(request));
}

@Override
public Pagination<TmsOrderVO> listByPage(TmsOrderPageRequest request) {
    Page<TmsOrder> page = PageHelper.startPage(request.getPageNum(), request.getPageSize());
    List<TmsOrder> list = tmsOrderMapper.listByPage(request);
    List<TmsOrderVO> voList = list.stream().map(order -> {
        TmsOrderVO vo = new TmsOrderVO();
        BeanUtils.copyProperties(order, vo);
        return vo;
    }).collect(Collectors.toList());
    return new Pagination<>(request.getPageNum(), request.getPageSize(), page.getTotal(), voList);
}

3.4.6 Claude.md 应用最佳实践

Claude.md 配置的核心原则是：「精简、精准、分层」。不用写多余的说明，只放 AI 每次会话都需要用到的信息，否则会消耗过多 Token，反而降低 AI 的遵从度。

1）按层级拆分内容，不重复、不冗余 这是最关键的原则。不同层级的 Claude.md 各司其职，发挥不同的作用，为避免重复维护，具体分工可以参考这个决策树：

• 用户级（~/.claude/CLAUDE.md）：放「通用、跨项目」的内容，比如个人编码风格（缩进 2 空格、行尾必须加冒号）、常用操作（提交前运行 npm test）、通用安全规则（禁止硬编码敏感信息）。
• 项目级（项目根目录/CLAUDE.md）：放「项目专属」的内容，比如项目技术栈（React 18 + TypeScript）、项目结构（/src/components 为 UI 组件目录）、团队编码规范（组件命名用 PascalCase）、构建命令（npm run build）。

2）控制文件长度，避免 Token 浪费 Claude Code 上下文 Token 有限，因此 Claude.md 并非越长越好，建议遵循这个下面这个长度标准：

• 单文件最佳长度：100-200 行，最多不超过 300 行，超过这个范围，AI 的规则遵从度会明显下降。
• 内容精简技巧：只写'指令性内容'，删除多余的说明（比如'以下规则是团队讨论决定的'）；复杂规则可通过「@path/to/file.md」语法导入其他文件，拆分维护，最大递归深度为 5 层。

3）用「What-Why-How」结构组织内容 清晰内容结构能让 AI 更容易识别规则，建议按'What-Why-How'的逻辑组织内容，比如：

• What（是什么）：项目技术栈、目录结构、核心架构（比如'前端用 React 18 + Zustand，后端用 Node.js'）。
• Why（为什么）：项目目的、设计原则、约束条件（比如'项目需兼容 IE11，避免使用 ES6+ 新特性'）。
• How（怎么做）：构建命令、测试方法、开发流程（比如'运行 npm run dev 启动本地服务，提交前需运行 npm lint'）。

4）精准配置 paths，减少无效加载 如果项目是多语言、多模块，可在 Claude.md 文件开头用 paths 元数据限定规则的生效范围，避免无关内容加载消耗 Token，如下示例：

• 这样一来，只有操作 Python 文件时，这部分规则才会被加载，操作其他类型文件（如.js）时不会生效，大幅提升 Token 使用效率。

--- paths: "**/*.java" # 仅对 Java 文件生效 ---
# Java 专属规则
1. 必须遵循本项目中 /doc/ap-dev-rule.md 的接口编写规范
2. 变量命名采用驼峰命名
3. 严格遵守 MVC 的编写规范

5）团队协作必做：纳入 Git 版本控制 如果是团队项目，项目级 Claude.md 一定要纳入 Git 版本控制，确保所有的团队成员都能使用统一的规则，避免 AI 生成的代码风格不一致；而用户级 claude.md 属于个人偏好，不建议纳入 Git，避免冲突。

修改 Claude.md 后无需重启 Claude Code，保存后会自动加载生效。若未生效，输入「/restart」命令重启会话即可。

6）避开 3 个常见坑 下面几个坑在实际使用中需要避免：

• 规则冲突，优先级搞混：记住'项目级覆盖用户级'，冲突时优先检查项目级 claude.md 的规则，避免模糊表述（比如同时写'可用单引号'和'可用双引号'）；
• 内容过于冗余，写了任务特定的规则（比如'实现登录功能用 JWT'）：这类内容无需写进 claude.md，仅保留'所有会话都需要的通用规则'，否则 AI 会将其视为噪音，忽略整个文件。
• 规则过多不拆分：如果规则超过 20 条，建议改用「.claude/rules/」文件夹分类管理，比单文件 claude.md 更易维护，且加载更精准。

四、总结

Claude Code 中的 CLAUDE.md 是重要的'记忆文件'，核心就是通过'分层配置 + 精准规则'，让 Claude Code 记住你的偏好、你的项目规范，从而减少重复沟通，提升编码效率。

对于新手来说，先从项目级 claude.md 入手，用「/init」命令生成初始文件，再补充项目技术栈和编码规范；熟悉后再配置用户级 claude.md，统一个人编码习惯；多项目维护时，用好分层规则，就能轻松搞定 AI 编码的'默契感'。

建议定期用「/memory」命令检查、更新规则，删除过期内容，让 AI 始终保持'精准记忆'。